Um template é um modelo ou estrutura predefinida que serve como base para criar ou formatar algo de forma consistente e eficiente. Ele pode ser usado em diversos contextos permitindo personalização sem a necessidade de criar algo do zero. Templates ajudam a padronizar processos e economizar tempo, fornecendo diretrizes ou formatos reutilizáveis.

Um template de markdown é um arquivo pré-formatado que serve como um modelo base para criar documentos com cabeçalhos, listas, tabelas e outros elementos de formatação, permitindo que os usuários preencham apenas os dados necessários sem precisar reformatar o texto. Neste tutorial, será apresentada uma solução para a criação de templates para markdown utilizando o componente Editor de Texto Rico e funções de blocos de programação.

Pré-requisitos

Antes de começar a seguir os passos do tutorial é preciso ter certeza de que se tem um ambiente minimamente preparado para reproduzir o exemplo. Abaixo estão os requisitos principais.

  1. Projeto do tipo web e mobile criado. Caso haja dúvidas de como criar esse tipo de projeto, acesse a documentação Criar projeto.
  2. Utilizar as funcionalidades do diagrama, como criar classes e gerar persistência. Caso haja dúvidas, acesse a documentação Diagrama.
  3. Criar blocos de programação. Caso haja dúvidas, acesse as documentações Bloco de programação e Criando blocos cliente customizados.

Passos

Configurando o diagrama

Vamos dar início ao nosso tutorial criando duas novas classes no Diagrama de dados, que serão utilizadas para armazenar o template no formato de texto rico (HTML), juntamente com os campos disponíveis que poderão ser utilizados diretamente no Editor de Texto Rico. Para começar, siga essas etapas: primeiro expanda o menu do tópico Diagrama de Dados e clique duas vezes no arquivo app (destaque 1 da Figura 1).

Criaremos duas classes com os seguintes atributos: a classe Template deve conter os atributos id, name e templateHTML, todos do tipo Texto, enquanto a classe TemplateField deve conter os atributos, id, name e fieldName, também do tipo Texto. Após a criação das classes, gere a camada de persistência (destaque 2).


Figura 1 - Classes "Template" e "TemplateField" no Diagrama de Dados

Criando as views 

Agora vamos criar as views dessas classes clicando com o botão direito do mouse sobre cada uma delas e selecionando a opção "Criar visão para a entidade" (destaque 3 da Figura 1). Ao gerar a view da classe Template, na tela "Campos da Grid" selecione apenas o campo name e, na tela "Campos do Formulário", marque os campos name e templateHTML. Já para a classe TemplateField, em ambas as telas, selecione os campos name e fieldName.

Após a criar a visão da classe "Template", realizaremos algumas edições na view criada. Inicialmente adicione, abaixo do componente entrada de texto "Name" (destaque 1 da Figura 2), o Editor de Texto Rico (destaque 2). Em seguida, ajuste a propriedade "Valor" do Editor para Template.active.templateHTML (3). Este componente permitirá a criação e edição dos templates de forma personalizada.

Por fim, adicione um componente Grade (4) acima do Editor de Texto Rico. Essa grade deve estar vinculada à fonte de dados "TemplateField" e configurada para exibir apenas o campo name, que pode ser renomeado para "Campos". Além disso, a grade deve conter um botão de ação customizado, que será responsável por inserir o campo markdown desejado diretamente no Editor de Texto Rico. Para esse botão, utilize a função e a descrição apresentada na Figura 2.1. Para detalhes de configuração do botão, consulte o tópico "Botões customizados" da documentação Grade.


Figura 2 - Edição da view "template"

Criando os blocos de programação

No botão customizado da Grade apresentada no destaque 4 da Figura 2, utilizamos a função cliente "addField" da imagem abaixo (Figura 3). Inicialmente, adicionamos o parâmetro "rowData" como entrada da função. Ela foi configurada utilizando o bloco Executa javascript, que recebe como entrada o bloco criar texto com. Este bloco é composto por três entradas:

  • Na primeira, é passado o texto "tinymce.activeEditor.execCommand('mceInsertContent', false,'${".
  • A segunda recebe o bloco Obter campo do, utilizado para obter o valor do campo desejado.
  • A terceira recebe recebe o texto "}');".

Essa função insere, de forma simples, o valor do campo fieldName da linha selecionada no Editor de Texto Rico. Ela também adiciona uma marcação no formato ${fieldName}, que poderá ser substituída posteriormente pelos valores desejados ao processar o template. Ao adicionar a função no botão customizado da Grade, na janela de configuração de eventos, o parâmetro "rowData" será exibido na coluna "Campo" e, na coluna "Valor do campo", selecione a opção "selectedRow".


Figura 3 - Função utilizada no botão "Adicionar campo" da Grade da view "template"


A segunda função, nomeada como "ProcessarTemplate", será utilizada no botão customizada da Grade da view de impressão dos templates. Esta função realiza, de forma simplificada, a substituição dinâmica no campo "templateHTML" fornecido, utilizando os valores associados às chaves de um objeto especificado (JSON, Map, ou Fonte de Dados). Ela percorre todas as chaves do objeto e, para cada uma, utiliza expressões regulares (Regex) para substituir os marcadores no formato ${chave} no template pelos valores correspondentes do objeto. Para configurá-la, siga os passos apresentados na imagem a seguir. 


Figura 3.1 - Função utilizada no botão "Imprimir Template" da Grade da view de impressão dos templates


Destaques da Figura 3.1:

  1. Definimos na variável "fields" um objeto JSON vazio utilizando o bloco Criar objeto Json.
  2. Utilizando o bloco Atribuir Valor, adicionaremos ao objeto JSON criado o valor "João Santiago" no campo "nome" do template utilizado.

  3. Na variável "templateProcessado", utilizamos o bloco cliente customizado "Processar Template" disponível na categoria "Minhas Funções" após a criação do bloco. Para mais detalhes de como criar um bloco customizado, consulte a documentação Criando blocos cliente customizados. O código utilizado pode ser visualizado abaixo:

    (function() {
  'use strict';

  this.cronapi = this.cronapi || {};

   /**
   * @categoryName Minhas Funções
   */
  this.cronapi.myfunctions = this.cronapi.myfunctions || {};
  
  /**
   * @type function
   * @name Processar Template
   * @description Processar Template
   * @multilayer false
   * @param {ObjectType.STRING} template Param Description
   * @param {ObjectType.OBJECT} values Param Description
   * @returns {ObjectType.STRING}
   */
  this.cronapi.myfunctions.processTemplate = function(/** @type {ObjectType.STRING} @description Template: Template a ser processado */template,  /** @type {ObjectType.OBJECT} @description Data: Dados para processamento do template */values) {
    return (template || '').replace(/\$\{([^}]+)\}/g, (match, key) => {
      return key in values ? values[key] : match;
    });
  };
  

}).bind(window)();
  4. O bloco Executa javascript recebe o comando "tinymce.activeEditor.setContent('')" utilizado para limpar o conteúdo do editor ativo.
  5. Por fim, o bloco Executa javascript recebe o bloco criar texto com composto por três entradas:
    • Na primeira, é passado o texto "tinymce.activeEditor.insertContent(`".
    • A segunda recebe o bloco Obter campo do, utilizado para obter o valor do campo desejado.
    • A terceira recebe recebe o texto "`);".

Utilizando os templates

Para utilizar os templates criados utilizaremos a view "home". Nela, adicionamos os componentes Grade e Editor de Texto Rico (Figura 4). O componente Grade deve estar vinculado à fonte de dados "Template" e configurado para exibir apenas o campo name e um botão customizado, semelhante à grade da view "template". Este botão de ação customizado, responsável por inserir o template desejado diretamente no Editor, deve estar associado à função apresentada na Figura 3.1. Para detalhes de configuração do botão, consulte o tópico "Botões customizados" da documentação Grade.


Figura 4 - Edição da view home para impressão dos templates

Executando o projeto

Após completar os passos anteriores, salve as alterações e execute o projeto. Na view "template", criaremos um template de formulário de cadastro (Figura 5). Conforme apresentado na imagem abaixo, a grade "Campos disponíveis" exibe os campos adicionados na view "templatefield". No Editor de Texto Rico, criamos o modelo de formulário e, ao final, adicionamos o campo "Nome do responsável" utilizando o botão "Adicionar campo" (destaque 1 da Figura 5).


Figura 5 - Criando um template 


Por fim, utilizaremos o template "Formulário de Cadastro" criado na view "home". Para isso, clique no botão "Imprimir Template" para exibir o conteúdo do template no Editor de Texto Rico (destaque 1 da Figura 5.1). Observe que o campo formatado durante a criação do template (destaque 1 da Figura 5) foi substituído pelo valor definido no destaque 2 da função apresentada na Figura 3.1.

Com esses passos concluídos, o sistema agora está preparado para utilizar templates personalizados, proporcionando maior flexibilidade e eficiência na criação e gerenciamento de documentos dinâmicos.


Figura 5.1 - Uso do template "Formulário de Cadastro"

Nesta página

  • Sem rótulos