rodolpho
21 KiB
title, source, path
| title | source | path |
|---|---|---|
| Primeiros passos no desenvolvimento de widgets | https://tdn.totvs.com/display/fluig/Primeiros+passos+no+desenvolvimento+de+widgets | \Plataforma Documentação técnica\Desenvolvimento sobre a plataforma\Desenvolvimento de PáginasWidgets (WCM)\Primeiros passos no desenvolvimento de widgets.md |
- Pré-requisitos do ambiente
- Configuração do servidor e criação do projeto
- 4 Dicas para dominar as widgets no TOTVS Fluig
- Sua widget com WCMAPI
Pré-requisitos do ambiente
Antes de iniciar a criação de uma widget, certifique-se de que sua máquina atende aos requisitos técnicos abaixo. Estes componentes são essenciais para que o desenvolvimento e a comunicação com o TOTVS Fluig ocorram sem falhas.
Kit de desenvolvimento Java (JDK)
O que é: ferramenta necessária para compilar e desenvolver código Java.
Atenção!
Certifique-se de instalar o JDK da Oracle. É obrigatório ter o JDK completo e não apenas o JRE, visto que o JRE serve exclusivamente para executar os programas, e não para criá-los.
IDE Eclipse e plugin Fluig Studio
Para desenvolver para a plataforma, utilizamos o Eclipse com ferramenta específica da TOTVS.
- Versões suportadas: é necessário utilizar o Eclipse 2019-R9 (2019-09) ou o Eclipse Luna, pois atualmente são as únicas versões homologadas pela TOTVS.
- Extensão: o plugin Fluig Studio deve estar instalado e configurado. É fundamental garantir que o plugin esteja exatamente na mesma versão do servidor Fluig do seu ambiente.
Caso haja divergência entre a versão do seu plugin e a do servidor, consulte a documentação de Instalação do Fluig Studio para realizar o downgrade ou upgrade de versão do plugin.
Dica!
Consulte o [Guia de instalação Fluig Studio](../../Instalação e Atualização/Guia de instalação Fluig Studio.md) e Como fazer - Instalar Eclipse 2019-R9 + Fluig Studio para o passo a passo detalhado.
Para a boa utilização do Fluig Studio, algumas configurações são necessárias [Configuração para uso inicial do Fluig Studio](../Fluig Studio/Configuração para uso inicial do Fluig Studio.md).
Atenção!
O Eclipse Luna não é compatível com a atualização Voyager 2.0 do Fluig.
Configuração do servidor e criação do projeto
Para iniciar o desenvolvimento no TOTVS Fluig, o primeiro passo prático é configurar a comunicação com o seu ambiente e criar um projeto no Eclipse para organizar os seus arquivos.
Dica!
Consulte [Criando um projeto Fluig no Studio](../Fluig Studio/Criando um projeto fluig no Studio.md) para o passo a passo detalhado.
Passo 1: selecionar a Perspectiva Fluig
Antes de clicar em qualquer menu, certifique-se de que você está na Perspectiva Fluig. No canto superior direito do Eclipse, verifique se o ícone do Fluig está selecionado. Isso habilita os menus específicos da plataforma.
- Selecione a perspectiva do Fluig.
Passo 2: configurando o servidor (Fluig Server)
O Eclipse precisa saber para onde enviar os arquivos.
-
Criar um novo servidor.
- Procure a aba Servers. Se não encontrar, vá em Window > Show View > Other... > Fluig > Fluig Servers.
- Clique com o botão direito sobre Servers e selecione Novo*>*Fluig Server.
-
Autenticação e definição do ambiente. Nesta tela, insira as credenciais essenciais para o "deploy":
-
Nome servidor: um nome para você identificar o servidor. Ex.: "Servidor Produção".
-
Host: o endereço completo. Ex.:
http://lab.fluig.com. -
Usuário e Senha: devem ser de um usuário com perfil de Administrador no TOTVS Fluig.
Dica!
Em ambientes integrados com Identity, utilize as credenciais de login do Identity.
-
Clique em Finish para concluir a criação do servidor.
-
- Clique duas vezes no servidor para validar a configuração.
Passo 3: criando o projeto
O projeto funciona como uma pasta raiz que conterá todos os seus componentes: widgets, layouts, datasets.
- Vá em Arquivo > Novo > Projeto Fluig.
- Nome do projeto: digite o nome do seu projeto. Ex.:
Projeto_Treinamento_Widgets, fluig, etc. - Clique em Finish.
Importante!
O Eclipse criará uma estrutura de pastas. A pasta que nos interessa é a WCM, onde ficam os componentes de Web Content Management.
Criando a widget: primeiros passos
Criar uma widget no Fluig é como construir uma peça de Lego inteligente. Ela terá um visual (HTML), um comportamento (JavaScript), um estilo próprio (CSS) e poderá falar vários idiomas (i18n). Vamos ao passo a passo no seu ambiente de desenvolvimento (Eclipse com plugin Fluig Studio):
- Abra a pasta do seu projeto, localize a pasta WCM e, dentro dela, a pasta Widget.
- Clique com o botão direito sobre a pasta Widget e selecione New > Widget.
- Uma janela de configuração será aberta:
- Código: o ID único da sua widget no banco de dados. Regra: use apenas letras minúsculas, números e underline. Ex.:
minha_primeira_widget. - Nome: o nome amigável que o usuário verá no catálogo de widgets ao editar uma página. Ex.: "Minha primeira widget".
- Descrição: explique brevemente o propósito dela.
- Código: o ID único da sua widget no banco de dados. Regra: use apenas letras minúsculas, números e underline. Ex.:
- Na mesma tela de criação, haverá a opção de escolher um Template.
- Selecione a opção "Nenhum".
- Ao escolher "Nenhum", clique em Next.
- Uma nova janela de configuração será aberta:
- Código/Nome/URL do desenvolvedor: preencha com seus dados ou os da sua empresa.
- Categoria: fundamental! É a "pasta" onde sua widget vai aparecer no menu do Fluig. Anote o nome exato.
- Renderizador: mantenha Freemarker. É o motor de templates oficial do Fluig.
- Suporte mobile: marque se a widget terá suporte ao aplicativo mobile Fluig.
Ao finalizar, o Fluig Studio gerará a seguinte estrutura limpa. É crucial entender o papel de cada arquivo:
minha_primeira_widget/
├── src/main/resources/
│ ├── view.ftl ➔ (O Rosto) O que o usuário final vê.
│ ├── edit.ftl ➔ (Os bastidores) Onde o administrador configura a widget.
│ ├── application.info ➔ (O RG) O documento de identidade e configurações da widget.
│ ├── minha_primeira_widget_pt_BR.properties ➔ Dicionário em Português.
│ ├── minha_primeira_widget_en_US.properties ➔ Dicionário em Inglês.
│ └── minha_primeira_widget_es.properties ➔ Dicionário em Espanhol.
│
└── src/main/webapp/resources/
├── css/
│ └── minha_primeira_widget.css ➔ (A Roupa) Estilos customizados (se os do Style Guide não bastarem).
└── js/
└── minha_primeira_widget.js ➔ (O Cérebro) Lógica, SuperWidget, chamadas de API.
Detalhando os arquivos na prática:
- application.info?:guarda tudo o que você preencheu na criação. Se você precisar mudar o ícone (
application.icon) ou a categoria, é aqui que fará a alteração.
Curiosidade!
Se você precisar mudar o ícone da widget ou a categoria dela no futuro, é neste arquivo que você fará a alteração.
- view.ftl (interface visual): é o HTML processado pelo Freemarker. Aqui, aplicamos o Fluig Style Guide.
Dica!
Evite usar estilos inline ou cores hardcoded. Use painéis, a grade do Style Guide (row, col-md-*) e os utilitários de espaçamento do Fluig (fs-mt-16, etc.).
Exemplo prático (view.ftl):
<div id="MyWidget_${instanceId}" class="super-widget wcm-widget-class fluig-style-guide" data-params="MyWidget.instance()">
<div class="panel panel-default fs-mt-16">
<div class="panel-heading">
<h3 class="panel-title fs-no-margin">
<span class="fluigicon fluigicon-info-sign fluigicon-sm"></span>
${i18n.getTranslation('widget.title')}
</h3>
</div>
<div class="panel-body">
<div class="row">
<div class="col-md-12">
<p class="fs-color-info-text">${i18n.getTranslation('widget.description')}</p>
<input type="text" class="form-control" placeholder="${i18n.getTranslation("widget.placeholder")}">
</div>
</div>
</div>
</div>
</div>
- edit.ftl (menu de parametrização): exibido apenas quando um administrador entra no modo de edição de página. É aqui que você coloca os inputs para o cliente mudar título, cor principal ou URL de integração, sem precisar alterar código.
Dica!
Salvando preferências: para que configurações feitas no edit.ftl (como a escolha em um Color Picker) tenham efeito no view.ftl, os valores não são salvos automaticamente . Você deve usar a seguinte técnica: WCMSpaceAPI.PageService.UPDATEPREFERENCES.
- Arquivos .properties (a internacionalização - i18n): os arquivos .properties guardam chaves e valores. Exemplo no arquivo pt_BR.properties:
widget.title=Minha Primeira Widget
widget.description=Olá! Esta é uma widget construída com as melhores práticas do TOTVS Fluig.
widget.placeholder=Digite seu nome aqui...
- JavaScript e preferências (a lógica): no arquivo JS da pasta webapp, criamos o objeto inteligente baseado na SuperWidget.
Deploy para o TOTVS Fluig
Com o servidor configurado, você enviará a widget para o TOTVS Fluig:
-
No Eclipse, clique com o botão direito exclusivamente sobre a pasta da sua widget (dentro de WCM/widget). Nunca exporte pela pasta raiz do projeto inteiro.
-
Selecione Fluig > Exportar para o servidor Fluig.
-
Escolha o servidor que você acabou de configurar e clique em Finish.
Testando sua widget
Para testar a sua widget, siga os passos abaixo.
Visualizar sua widget
Após realizar a exportação (deploy) no Eclipse, sua widget já estará disponível no servidor TOTVS Fluig. Para visualizá-la, siga os passos abaixo:
Acessar o TOTVS Fluig e a página:
Para ver sua widget, siga os passos abaixo:
-
**Passo 1:**acesse o endereço do servidor TOTVS Fluig no seu navegador e faça o login com credenciais de administrador.
-
Passo 2: no menu lateral, vá em Painel de Controle > Minhas páginas .
-
Passo 3: clique em Criar página;
- selecione qualquer layout de página e clique em Avançar;
- preencha os campos Nome da página e Descrição como quiser. Ex.: Primeira página;
- o Identificador único preencha como: primeira_pagina.
-
Passo 4: clique em Concluir.
Nota:
Você pode adicionar em uma página existente também caso queira, não precisa criar uma nova página.
Adicionar a widget
Com a página em modo de edição, siga os passos abaixo:
- Passo 1: com a página em modo de edição, localize o menu lateral de widgets.
- Passo 2: navegue pelas pastas até encontrar a Categoria que você definiu no arquivo
application.infodo seu projeto no Eclipse. - Passo 3: clique sobre a sua widget (identificada pelo Widget Title, ex.: "Minha Primeira Widget") e faça um drag-and-drop (arrastar e soltar) diretamente para o slot ou coluna desejada na página.
Publicar a página
Após arrastar a widget, você verá apenas o conteúdo que escreveu no edit.ftl.
- Passo 1: na barra superior, clique em Publicar e dê um nome à versão. Ex.: "Versão inicial".
Dica!
Se você fizer uma alteração no código dentro do Eclipse e exportar novamente, basta fazer um "F5" (refresh) na página do navegador para ver a mudança . Não é necessário remover e adicionar a widget de novo toda vez que mudar uma linha de código .
4 Dicas para dominar as widgets no TOTVS Fluig
Dica 1: domine o ciclo de vida
Toda widget é uma extensão da SuperWidget. O segredo para um código organizado é entender que o arquivo .js controla o que acontece em cada momento. Use sempre a função init, que é o gatilho automático . É nela que você deve usar a propriedade this.isEditMode para decidir se o código deve carregar as configurações do arquivo (edit.ftl) ou (view.ftl).
Dica 2: use o "i18n" no seu código
Evite escrever textos diretamente no HTML (view.ftl ou edit.ftl).Utilize os arquivos .properties. Ao usar ${i18n.getTranslation('sua.chave')} no HTML, você garante que sua widget seja internacionalizável.
Dica 3: isole suas instâncias
- No HTML (
view.ftl): utilize a variável${instanceId}fornecida pela plataforma para criar IDs dinâmicos, comoid="meu-grafico_${instanceId}". - No JavaScript: para manipular esse elemento, concatene a propriedade da SuperWidget na sua busca:
const meuGrafico = document.querySelector("#meu-grafico_" + this.instanceId);.Isso garante que cada widget na página seja única e independente .
Atenção!
Cuidado com o contexto em chamadas Assíncronas (AJAX): se você fizer uma requisição AJAX ou usar um callback, o contexto do this muda, e o this.instanceId ficará undefined. Para não perder essa referência, declare uma variável recebendo o this no início do seu escopo.
Dica para os desenvolvedores
Para mais informações, acesse o curso Iniciando o desenvolvimento de widgets.
Dica 4: renomear arquivos
Ao criar uma widget, o Fluig Studio gera os arquivos baseados no Código da widget informado. Se você renomear o arquivo JavaScript principal (Ex.: de xpto.js para portal_cotacao.js), a widget irá quebrar.
A plataforma amarra a identidade do componente através do arquivo application.info. Se precisar renomear a widget no futuro, certifique-se de alterar também a propriedade application.code dentro do application.info, além de renomear os arquivos .properties para que tudo continue conversando perfeitamente.
Sua widget com WCMAPI
Sua widget tem apenas uma interface estática. Para torná-la dinâmica, o Fluig disponibiliza um objeto global e muito poderoso chamado WCMAPI. Ele é a ponte entre o Front-end da sua widget e os serviços do servidor Fluig. Aqui estão os três recursos essenciais da WCMAPI.
Obtendo o contexto do usuário logado
Você não precisa criar serviços complexos para saber quem está acessando a página. O WCMAPI já traz essas informações prontas no momento em que a widget é carregada:
WCMAPI.user: retorna o nome completo do usuário logado.WCMAPI.userCode: retorna a matrícula/código interno do usuário.WCMAPI.userId: retorna o login de acesso do usuário.WCMAPI.serverURL: retorna a URL base do seu servidor Fluig, ideal para montar links de arquivos e chamadas.
Consumindo datasets
Para buscar informações de formulários ou tabelas internas do Fluig dentro do application.js da sua widget, a melhor prática é utilizar a DatasetFactory nativa:
// Exemplo de busca de dados no JavaScript da Widget
var dataset = DatasetFactory.getDataset("colleague", null, null, null);
if (dataset != null && dataset.values.length > 0) {
console.log("Usuários encontrados: " + dataset.values.length);
}
Importante!
Para que o objeto DatasetFactory fique disponível no JavaScript da sua página, certifique-se de importar a biblioteca <script src="/webdesk/vcXMLRPC.js"></script> no seu view.ftl.
Integração com serviços REST
Se a sua widget precisa buscar ou enviar dados para fontes externas, APIs REST customizadas ou serviços internos do próprio TOTVS Fluig, a forma mais moderna, performática e segura de fazer essa requisição é utilizando a API nativa fetch do JavaScript em conjunto com métodos assíncronos (async/await).
Para garantir que a sua widget não quebre ao ser migrada de um ambiente de Homologação para Produção, sempre utilize o método WCMAPI.getServerURL() para montar o caminho base das chamadas internas. Ele já herda a autenticação do usuário logado na plataforma!
Veja abaixo o "esqueleto universal" para consumir qualquer API:
var MyWidget = SuperWidget.extend({
// Variáveis da widget
variavelNumerica: null,
// Método iniciado quando a widget é carregada no DOM
init: function() {
this.consumirApiRest();
},
// BIND de eventos de clique, alteração, etc.
bindings: {
local: {
'atualizar-dados': ['click_consumirApiRest']
}
},
/**
* Padrão Universal para requisições REST (Internas ou Externas)
*/
consumirApiRest: async function() {
try {
// 1. Definição da URL
// Exemplo A (API pública do Fluig):
const url = `${WCMAPI.getServerURL()}/api/public/ecm/document/listDocument/2`;
// Exemplo B (API Externa ):
// const url = 'https://sua-api-externa.com.br/v1/dados';
// 2. Realiza a requisição assíncrona
const response = await fetch(url, {
method: 'GET', // Pode ser alterado para POST, PUT, DELETE, etc.
headers: {
'Accept': 'application/json',
'Content-Type': 'application/json'
}
// Se for POST ou PUT, adicione o corpo da requisição:
// body: JSON.stringify({ chave: "valor" })
});
// 3. Validação de sucesso HTTP
if (!response.ok) {
throw new Error(`Erro HTTP: ${response.status} - ${response.statusText}`);
}
// 4. Conversão da resposta para JSON
const data = await response.json();
console.log("Sucesso ao consultar a API:", data);
} catch (error) {
console.error("Algo inesperado ocorreu ao chamar a API:", error);
// Exibe um alerta visual nativo da plataforma em caso de falha
FLUIGC.toast({
title: 'Atenção: ',
message: 'Não foi possível carregar os dados da integração.',
type: 'warning'
});
}
}
});
Dica!
O método WCMAPI.getServerURL() traz a URL exata do servidor para você montar o caminho da sua chamada REST com segurança, evitando que a sua widget quebre caso a empresa mude o endereço do Fluig no futuro!