Configuração YAML

Guia completo para edição manual do arquivo template.yaml, abrangendo Layout, Mapeamento e Lógica.

Este guia é destinado a usuários avançados e desenvolvedores que desejam editar o arquivo template.yaml diretamente. Este arquivo atua como a "Fonte Única da Verdade" para o seu perfil, definindo o layout do PDF, mapeamento de dados e lógica de cálculos.

Localização do arquivo

O arquivo de configuração está localizado no diretório do perfil dentro do workspace:

Documents/PDFMailEngine_Workspace/Profiles/<SeuNomeDePerfil>/template.yaml

O local padrão do workspace é a pasta PDFMailEngine_Workspace dentro do diretório Documentos. Você pode alterar a localização do workspace nas configurações do aplicativo.

1. PAGE Configuration (Página)

Define as propriedades físicas do canvas do PDF.

size: Tamanhos padrão (A3, A4, A5, B4, B5, LETTER, LEGAL).
orientation: PORTRAIT ou LANDSCAPE.
margins: Margens globais em milímetros.

Gerenciamento manual de assets

Ao adicionar PDFs de fundo manualmente no arquivo YAML, o aplicativo NÃO importa automaticamente o arquivo para a pasta do perfil.

Você deve copiar manualmente o arquivo .pdf para o diretório do perfil.

Caminho padrão do Designer: assets/background/
Recomendado: Use caminhos relativos (ex.: ./background.pdf ou assets/background/bg.pdf).

PAGE:
  size: "A4"
  orientation: "PORTRAIT"
  margins:
    top: 20
    bottom: 20
    left: 20
    right: 20
  background: "assets/background/stationery.pdf" # PDF de fundo opcional

2. FONTS

Registra fontes TrueType (.ttf) ou OpenType (.otf) personalizadas.

Gerenciamento manual de assets

Você deve copiar manualmente o arquivo de fonte para o diretório do perfil.

Caminho padrão do Designer: assets/fonts/

FONTS:
  # FontName : Relative Path
  "MyCustomFont": "assets/fonts/MyFont-Bold.ttf"
  "CorporateFont": "Corporate-Regular.otf"

3. MAPPING (Vinculação de dados)

Mapeia os cabeçalhos das colunas do CSV/Excel para nomes de variáveis internas usadas no modelo.

Sintaxe: InternalKey: "CSV Column Header"

MAPPING:
  # Internal : External
  customer_name: "Customer Name"
  invoice_no: "Invoice Number"
  date: "Issue Date"
  amount: "Total Amount"

4. CALCULATIONS

Define cálculos automáticos a serem executados durante a ingestão de dados.

Consistência de sintaxe

Use chaves {{ }} para variáveis. Para manter a consistência com campos de texto, recomenda-se envolver os nomes das variáveis em chaves {{ }}, mesmo em fórmulas de cálculo.

Padrão: {{ quantity }} * {{ price }}

scope:
- item: calculado para cada linha (ex.: {{ quantity }} * {{ price }}).
- group: calculado para um grupo de linhas (ex.: sum de totais).
expression: Uma expressão matemática. Suporta funções math como floor(), ceil(), round().

CALCULATIONS:
  # Cálculo por linha (ex.: Imposto)
  - scope: "item"
    target: "tax_amount"
    expression: "floor({{ amount }} * 0.10)" # Use funções math

  # Adicionando para mostrar de onde vem total_with_tax
  - scope: "item"
    target: "total_with_tax"
    expression: "{{ amount }} + {{ tax_amount }}"

  # Cálculo em nível de grupo (Soma de todas as linhas da fatura)
  - scope: "group"
    target: "grand_total"
    type: "sum" # 'sum' soma os valores
    field: "total_with_tax"

5. LAYOUT (Elementos)

A lista LAYOUT define todos os elementos visuais no PDF. Os elementos são desenhados em ordem (elementos posteriores são desenhados por cima).

Sistema de coordenadas

Origem das coordenadas

Modelos criados pelo Designer usam um sistema de coordenadas com origem no canto superior esquerdo (Y=0 é o topo da página). Ao editar YAML manualmente com a chave PAGE, o sistema de coordenadas padrão é origem no canto inferior esquerdo (Y=0 é a parte inferior da página).

O sistema de coordenadas é determinado automaticamente: modelos com a chave canvas (formato do Designer) usam origem superior esquerda, enquanto modelos com a chave PAGE usam origem inferior esquerda.

Propriedades comuns

A maioria dos elementos suporta estas propriedades:

x, y: Posição em milímetros.
visible: Uma expressão condicional que controla se o elemento é renderizado (veja abaixo).
position: absolute (padrão) ou relative.

Propriedade `visible`

A propriedade visible aceita uma expressão Python avaliada contra a linha de dados atual. Se a expressão avaliar como False (ou um valor falso), o elemento é ocultado.

Funções integradas disponíveis: int(), float(), str(), len()

# Mostrar apenas quando o valor é positivo
- type: "text"
  value: "Total: {{ amount }}"
  visible: "{{ amount }} > 0"
  x: 20
  y: 250

# Mostrar apenas quando um campo não está vazio
- type: "text"
  value: "Nota: {{ note }}"
  visible: "len(str({{ note }})) > 0"
  x: 20
  y: 240

# Combinar múltiplas condições
- type: "text"
  value: "Desconto Aplicado"
  visible: "{{ discount_rate }} > 0 and {{ amount }} >= 10000"
  x: 20
  y: 230

Text

Exibe texto estático ou variáveis dinâmicas usando a sintaxe Jinja2 {{ key }}.

- type: "text"
  value: "Invoice #{{ invoice_no }}" # Dinâmico
  x: 20
  y: 250
  font_family: "Helvetica"
  font_size: 12
  font_weight: "bold"
  align: "LEFT" # LEFT, CENTER, RIGHT
  color: "#000000"
  opacity: 1.0

Image

Incorpora um arquivo de imagem.

Gerenciamento manual de assets

Você deve copiar manualmente o arquivo de imagem para o diretório do perfil.

Caminho padrão do Designer: assets/images/

- type: "image"
  path: "assets/images/logo.png"
  x: 150
  y: 260
  width: 40
  height: 20

Group Table (Dinâmica)

Renderiza uma tabela dinâmica que itera sobre as linhas de dados (Detalhes/Itens de linha).

- type: "group_table"
  x: 20
  y: 180
  # Estilos globais
  header_height: 8
  row_height: 6
  border_color: "#000000"
  grid_color: "#cccccc"
  alt_row_color: "#f0f0f0" # Listras zebra

  columns:
    - header: "Item"
      key: "item_name"
      width: 60
      align: "LEFT"

    - header: "Price"
      key: "unit_price"
      width: 30
      align: "RIGHT"
      format: "currency" # Formata com vírgulas

Static Table (Fixa)

Renderiza uma grade fixa onde as linhas são definidas manualmente. Útil para rodapés, dados bancários ou blocos de assinatura.

- type: "static_table"
  x: 20
  y: 50
  width: 170 # Opcional. Inferido da soma das larguras das colunas se não especificado

  columns:
    - width: 30
      header: "Label"
    - width: 140
      header: "Value"

  # Linhas definidas manualmente
  rows:
    - ["Bank Name", "Mizuho Bank"]
    - ["Account No", "{{ account_number }}"] # Pode usar variáveis
    - ["Note", "Please pay within 30 days"]

Barcode

Gera um código de barras 1D.

Tipos suportados: CODE128, JAN (EAN13 misto), EAN13, EAN8, CODE39, UPCA, NW-7 (Codabar), ITF.

- type: "barcode"
  value: "{{ invoice_no }}"
  x: 20
  y: 20
  width: 50        # Largura máxima (reduzida se necessário)
  height: 10       # Altura total

  barcode_type: "CODE128"
  bar_width: 1.0   # Espessura das barras
  bar_height: 10   # Altura das barras

  # Texto legível
  human_readable: true
  hr_font: "Helvetica"
  hr_size: 10
  hr_color: "#000000"

QR Code

Gera um QR Code 2D.

Níveis de correção de erro: L (7%), M (15%), Q (25%), H (30%).

- type: "qrcode"
  value: "https://example.com/inv/{{ invoice_no }}"
  x: 150
  y: 20
  width: 20       # Tamanho (proporção fixa)

  qr_error_level: "M"
  qr_quiet_zone: true   # Incluir margem branca

  color: "#000000"      # Primeiro plano
  back_color: "#ffffff" # Fundo
  opacity: 1.0

Shapes (Rect / Line)

Apenas edição manual do YAML

Elementos de forma (rect e line) não podem ser adicionados pela interface do Designer. Estão disponíveis apenas ao editar o arquivo YAML diretamente.

Propriedades do Rect:

x, y: Posição em milímetros.
width, height: Dimensões em milímetros.
stroke_color: Cor da borda (hexadecimal, ex.: "#000000").
fill_color: Cor de preenchimento (hexadecimal, ex.: "#f0f0f0"). Omita para sem preenchimento.
stroke_width: Espessura da borda em pontos (padrão: 1).
opacity: Opacidade de 0.0 (transparente) a 1.0 (opaco).

Propriedades do Line: Uma linha é desenhada como um retângulo com height: 0 (horizontal) ou width: 0 (vertical).

x, y: Posição inicial em milímetros.
width: Comprimento de uma linha horizontal.
height: Comprimento de uma linha vertical. Defina 0 para linhas horizontais.
stroke_color: Cor da linha (hexadecimal).
stroke_width: Espessura da linha em pontos.

# Retângulo com borda e preenchimento
- type: "rect"
  x: 10
  y: 100
  width: 190
  height: 50
  stroke_color: "#000000"
  fill_color: "#f0f0f0"
  stroke_width: 1

# Linha horizontal
- type: "line"
  x: 10
  y: 200
  width: 190
  height: 0
  stroke_width: 2
  stroke_color: "#000000"

Configuração YAML

Localização do arquivo

1. PAGE Configuration (Página)

Gerenciamento manual de assets

2. FONTS

Gerenciamento manual de assets

3. MAPPING (Vinculação de dados)

4. CALCULATIONS

Consistência de sintaxe

5. LAYOUT (Elementos)

Sistema de coordenadas

Origem das coordenadas

Propriedades comuns

Propriedade visible

Text

Image

Gerenciamento manual de assets

Group Table (Dinâmica)

Static Table (Fixa)

Barcode

QR Code

Shapes (Rect / Line)

Apenas edição manual do YAML

Propriedade `visible`