Tags MS Word do Gerador de Documentos

Uma "tag" refere-se a uma expressão que o Gerador de Documentos pode substituir em um modelo de documento usando dados JSON.

Dados

Os dados JSON podem ser armazenados no Object Storage ou especificados em linha em uma Solicitação.

Exemplo - Armazenado no Serviço Object Storage

  "data": {    
    "source": "OBJECT_STORAGE",
    "namespace": "my_namespace",
    "bucketName": "my_bucket",
    "objectName": "my_folder/names.json"
  }

Exemplo - Especificado em linha em data.content

  "data": {
    "source": "INLINE",
    "content": [{"name":"John"},{"name":"Monica"}]
  }

Tags

As tags contêm caminhos para algum valor nos dados JSON. Por exemplo, dados estes dados:

{
  "customer": {
    "first_name": "Jack",
    "last_name": "Smith"
  }
}

Você pode usar este modelo:

Hello {customer.first_name} {customer.last_name}!

Para gerar este texto:

Hello Jack Smith!

Tag de Loop Vertical

Sintaxe: {#loop}...{/loop}

Uma tag {#loop} é usada para produzir cópias de uma seção de texto verticalmente.

Exemplo de Lista

Dados

{
  "class_list": [
    {
      "name": "Sue",
      "student_id": 1
    },
    {
      "name": "Bob",
      "student_id": 2
    },
    {
      "name": "Jean",
      "student_id": 3
    }
  ]
}

Modelo

Class List
{#class_list}* {student_id}: {name}
{/class_list}

Resultado

Class List
* 1: Sue
* 2: Bob
* 3: Jean

Exemplo de Tabela

Dados

{
  "class_list": [
    {
      "name": "Sue",
      "student_id": 1
    },
    {
      "name": "Bob",
      "student_id": 2
    },
    {
      "name": "Jean",
      "student_id": 3
    }
  ]
}

Modelo

IdNome
{#class_list}{student_id}{name}{/class_list}

Resultado

IdNome
1Sue
2Bob
3Jean

Operações de Array

Filtro

A operação filter usa três argumentos:

  1. A propriedade na qual filtrar
  2. A comparação a ser realizada
  3. O valor a ser comparado

Atualmente, a filtragem só é suportada em tipos numéricos.

Para usar um filtro, você deve especificar uma nova lista, chamada {#filtered}...{/filtered}, dentro do array pai que faz a filtragem.

Exemplo

Dados
{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}
Modelo

{#products|filter:price:>=:2}

CategoriaNomePreço
{#filtered}{category}{name}{price}{/filtered}

{/products|filter:price:>=:2}

Resultado
CategoriaNomePreço
Vestuáriocamisa3
AcessórioHat2

Classificação

A operação sort usa dois argumentos:

  1. O nome da propriedade a ser usada para classificação
  2. asc ou desc para classificar a lista na ordem ascending ou descending.

Para usar uma classificação, você deve especificar uma nova lista, chamada {#sorted}...{/sorted}, dentro do array pai que está sendo classificado.

Exemplo

Dados
{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}
Modelo

{#products|sort:price:desc}

CategoriaNomePreço
{#sorted}{category}{name}{price}{/sorted}

{/products|sort:price:desc}

Resultado
CategoriaNomePreço
Vestuáriocamisa3
AcessórioHat2
AcessórioCorreia1

Diferente

A operação distinct usa um único argumento:

  1. O nome da propriedade para selecionar valores distintos.

Exemplo

Dados
{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}
Modelo
Categories:
{#products|distinct:category}

* {category}
  {/products|distinct:category}
Resultado
Categories:

* Accessory
* Clothing

Quebra

O operador break agrupa itens com base em uma propriedade compartilhada. É preciso um argumento:

  1. O nome da propriedade para agrupar itens.

Para usar um intervalo, você deve especificar uma nova lista, chamada {#break}...{/break}, dentro do array pai que está sendo dividido em grupos.

Exemplo

Neste exemplo, observe que os itens "Belt" e "Hat" compartilharam uma categoria ("Acessório"), mas não estão agrupados no array ("Belt" é o primeiro item no array e "Hat" é o último item).

Depois que o operador break tiver sido aplicado, os itens serão agrupados na saída.

Dados
{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}
Modelo
{#products|break:category}
{#break}* Category:{category}, Product:{name}
{/break}
{/products|break:category}
Resultado
* Category:Clothing, Product:Shirt
* Category:Accessory, Product:Belt
* Category:Accessory, Product:Hat

Grupo

Divide uma matriz em submatrizes do tamanho fornecido. É necessário um único argumento:

  1. Um número inteiro especificando o tamanho do grupo.

Para usar um grupo, você deve especificar uma nova lista, chamada {#group}...{/group}, dentro do array pai que está sendo dividido em grupos.

Se a matriz não se dividir perfeitamente em grupos, o último grupo será de tamanho menor. Por exemplo, se você tiver um array de 5 itens e usar group:2 nele, dois grupos de dois itens e um grupo de um item serão criados.

Exemplo

Dados
{
  "products": [
    {
      "price": 1,
      "name": "Belt",
      "category": "Accessory"
    },
    {
      "price": 3,
      "name": "Shirt",
      "category": "Clothing"
    },
    {
      "price": 2,
      "name": "Hat",
      "category": "Accessory"
    }
  ]
}
Modelo
{#products|group:2}Items
{#group}* {name}
{/group}
{/products|group:2}
Resultado
Items
* Belt
* Shirt
Items
* Hat

Tag de Loop Horizontal

Sintaxe: {:loop}...{/loop}

Uma tag {:loop} é usada para produzir cópias de uma seção de texto horizontalmente.

Exemplo de Tabela

Dados

{
  "weekdays": [
    {
      "name": "Monday"
    },
    {
      "name": "Tuesday"
    },
    {
      "name": "Wednesday"
    },
    {
      "name": "Thursday"
    },
    {
      "name": "Friday"
    }
  ]
}

Modelo

Dias{:weekdays}{name}{/weekdays}

Resultado

DiasSegunda-feiraterça-feiraquarta-feiraQuintaSexta-feira

Agregadores

Sum

O Agregador de Soma é usado para calcular a soma de uma matriz.

Exemplo

Dados

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Modelo

Total Price: {items|sum:price}

Resultado

Total Price: 6

Média

O Agregador Médio é usado para calcular a média de um array.

Exemplo

Dados

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Modelo

Average Price: {items|avg:price}

Resultado

Average Price: 2

Máximo

O Agregador Máximo é usado para localizar o valor máximo de uma matriz.

Exemplo

Dados

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Modelo

Max Price: {items|max:price}

Resultado

Average Price: 3

Min

O Agregador Mínimo é usado para localizar o valor mínimo de um array.

Exemplo

Dados

{
  "items": [
    {
      "name": "ball",
      "price": 1
    },
    {
      "name": "stick",
      "price": 2
    },
    {
      "name": "cup",
      "price": 3
    }
  ]
}

Modelo

Minimum Price: {items|min:price}

Resultado

Minimum Price: 1

Tag de Imagem

Sintaxe: {%image}

Uma tag {%image} é usada para injetar uma imagem em um documento. É possível fornecer imagens de um Bucket do OCI Object Storage ou de um URL. As imagens devem ser fornecidas como um objeto, por exemplo:

{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png"
  }
}

Informações Gerais

O esquema específico para cada tipo de origem é descrito abaixo. Além disso, as seguintes propriedades podem ser (opcionalmente) incluídas no objeto de imagem para controlar a formatação da imagem:

  • largura: Um string de dígitos, seguido pela unidade de medida. E.G. 200px. Define a largura da imagem.
  • altura: Um string de dígitos, seguido por unidade de medida. E.G. 200px. Define a altura da imagem.
  • alt_text: Um string. Isso será definido como o texto alternativo da imagem.

Unidades de medida suportadas:

O Gerador de documentos suporta as seguintes unidades de medida para imagens:

  • px (pixels)
  • em (polegadas)
  • cm (centímetros)
  • % (porcentagem)

Tamanho padrão das imagens inseridas:

  • Imagens menores: Se uma imagem for menor que o tamanho da página, o tamanho original será preservado.
  • Imagens maiores: Se uma imagem for maior que o tamanho da página, ela será redimensionada para caber na largura e altura da página. A proporção da imagem é mantida.

Dimensionamento de imagens:

Se apenas uma dimensão de imagem for fornecida, o Gerador de Documentos calculará um valor em escala para a dimensão ausente, a fim de preservar a proporção. Por exemplo:

  • Se você fornecer uma largura, mas não uma altura, uma altura dimensionada será calculada com base nas dimensões nativas da imagem e na largura fornecida.
  • Se você fornecer uma altura, mas não uma largura, uma largura dimensionada será calculada com base nas dimensões nativas da imagem e na altura fornecida.

Formatos Suportados

O Gerador de Documentos suporta os seguintes formatos de imagem:

  • PNG
  • JPG
  • GIF
  • BMP

Esquemas

OCI Object Storage

  • source: deve ser definido como OBJECT_STORAGE
  • objectName: O caminho e o nome do arquivo
  • namespace: O namespace do seu bucket de armazenamento de objetos
  • bucketName: O nome do bucket que contém o arquivo
  • mediaType: O Tipo de Mídia (MIME) da imagem

Exemplo

Dados
{
  "my_image": {
    "source": "OBJECT_STORAGE",
    "objectName": "image.png",
    "namespace": "object_storage_namespace",
    "bucketName": "my_bucket_name",
    "mediaType": "image/png",
    "width": "400px",
    "height": "200px"
  }
}
Modelo
{%my_image}
Resultado

Resultado

URL

  • source: deve ser definido como URL
  • url: o URL da imagem no formato string

Observação: para usar imagens da Internet, o Gerador de Documentos precisa de acesso de saída à Internet. Por exemplo, se o Gerador de Documentos estiver em execução em uma sub-rede privada no OCI, você poderá configurar um Gateway NAT para permitir que o Gerador de Documentos se conecte à Internet.

Exemplo

Dados
{
  "my_image": {
    "source": "URL",
    "url": "https://www.oracle.com/.../.jpg"
  }
}
Modelo
{%my_image}
Resultado

Resultado

URL de Dados

O Gerador de Documentos também suporta a capacidade de transmitir imagens dentro de URLs de Dados. A imagem deve ser codificada em Base64.

  • source: deve ser definido como URL
  • url: o URL da imagem no formato string

Exemplo

Dados
{
  "my_image": {
    "source": "URL",
    "url": "data:image/png;base64,iVBORw0KG...go"
  }
}
Modelo
{%my_image}
Resultado

Resultado

Tags de Quebra de Página e Quebra de Coluna

Sintaxe: {?pagebreak} e {?columnbreak}

Uma tag pagebreak é usada para introduzir uma quebra de página. Há quatro variações dessas tags:

  • {?pagebreak} e {?page} criam quebras de página.
  • {?columnbreak} e {?column} criam quebras de coluna.

Formatação de Número

Se um valor que está sendo fornecido a uma tag {basic} for um número, o Gerador de Documentos suportará a capacidade de formatá-lo.

Um formatador é especificado da seguinte forma: {input_number|format:[format]:[separators]:[currency_symbol]}, em que:

  • [format] é um formato de número suportado
  • [separators] (opcional) é uma string de 2 caracteres. O primeiro caractere indica o separador decimal, o segundo caractere indica o separador de vírgula
  • [currency_symbol] (opcional) o símbolo de moeda a ser aplicado se L estiver presente em [format]

Os formatos de número devem ser especificados em um dos seguintes Formatos de Número Oracle:

  • FML999G999G999G999G990D00
  • FML999G999G999G999G990
  • 999G999G999G999G990D00
  • 999G999G999G999G990D0000
  • 999G999G999G999G999G999G990
  • 999G999G999G999G990D00MI
  • 999G999G999G999G990D00MI
  • S999G999G999G999G990D00
  • 999G999G999G999G990D00S
  • S999G999G999G999G990D00
  • 999G999G999G999G990D00PR
  • FML999G999G999G999G990PR
  • 999G999G999G999G990D00PR

Exemplos

A tabela a seguir é fornecida para compartilhar exemplos desses formatos com um número:

Modelounit_price: 1234,5unit_price: -1234,5
{unit_price|format:"FML999G999G999G999G990D00":"<>":"$"}$1>234<50-$1>234<50
{unit_price|format:"999G999G999G999G990D00":",."}1.234-1.234
{unit_price|format:"999G999G999G999G990D00":", "}1 23,450-1 23,450
{unit_price|format:"999G999G999G999G999G999G990"}1,234-1,234
{unit_price|format:"999G999G999G999G990D00MI"}1,234.51,234.5-
{unit_price|format:"S999G999G999G999G990D00"}+1,234.5-1,234.5
{unit_price|format:"999G999G999G999G990D00PR"}1,234.5<1.234,50>
{unit_price|format:"FML999G999G999G999G990PR"}$1,234<$1,234>