--- title: Primeiros passos no desenvolvimento de widgets source: https://tdn.totvs.com/display/fluig/Primeiros+passos+no+desenvolvimento+de+widgets path: \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](#Primeirospassosnodesenvolvimentodewidgets-Pré-requisitosdoambiente) - [Kit de desenvolvimento Java (JDK)](#Primeirospassosnodesenvolvimentodewidgets-KitdedesenvolvimentoJava(JDK)) - [IDE Eclipse e plugin Fluig Studio](#Primeirospassosnodesenvolvimentodewidgets-IDEEclipseepluginFluigStudio) - [Configuração do servidor e criação do projeto](#Primeirospassosnodesenvolvimentodewidgets-Configuraçãodoservidorecriaçãodoprojeto) - [Passo 1: selecionar a Perspectiva Fluig](#Primeirospassosnodesenvolvimentodewidgets-Passo1:selecionaraPerspectivaFluig) - [Passo 2: configurando o servidor (Fluig Server)](#Primeirospassosnodesenvolvimentodewidgets-Passo2:configurandooservidor(FluigServer)) - [Passo 3: criando o projeto](#Primeirospassosnodesenvolvimentodewidgets-Passo3:criandooprojeto) - [Criando a widget: primeiros passos](#Primeirospassosnodesenvolvimentodewidgets-Criandoawidget:primeirospassos) - [Deploy para o TOTVS Fluig](#Primeirospassosnodesenvolvimentodewidgets-DeployparaoTOTVSFluig) - [Testando sua widget](#Primeirospassosnodesenvolvimentodewidgets-Testandosuawidget) - [Visualizar sua widget](#Primeirospassosnodesenvolvimentodewidgets-Visualizarsuawidget) - [Acessar o TOTVS Fluig e a página:](#Primeirospassosnodesenvolvimentodewidgets-AcessaroTOTVSFluigeapágina:) - [Adicionar a widget](#Primeirospassosnodesenvolvimentodewidgets-Adicionarawidget) - [Publicar a página](#Primeirospassosnodesenvolvimentodewidgets-Publicarapágina) - [4 Dicas para dominar as widgets no TOTVS Fluig](#Primeirospassosnodesenvolvimentodewidgets-4DicasparadominaraswidgetsnoTOTVSFluig) - [Dica 1: domine o ciclo de vida](#Primeirospassosnodesenvolvimentodewidgets-Dica1:domineociclodevida) - [Dica 2: use o "i18n" no seu código](#Primeirospassosnodesenvolvimentodewidgets-Dica2:useo"i18n"noseucódigo) - [Dica 3: isole suas instâncias](#Primeirospassosnodesenvolvimentodewidgets-Dica3:isolesuasinstâncias) - [Dica 4: renomear arquivos](#Primeirospassosnodesenvolvimentodewidgets-Dica4:renomeararquivos) - [Sua widget com WCMAPI](#Primeirospassosnodesenvolvimentodewidgets-SuawidgetcomWCMAPI) - [Obtendo o contexto do usuário logado](#Primeirospassosnodesenvolvimentodewidgets-Obtendoocontextodousuáriologado) - [Consumindo datasets](#Primeirospassosnodesenvolvimentodewidgets-Consumindodatasets) - [Integração com serviços REST](#Primeirospassosnodesenvolvimentodewidgets-IntegraçãocomserviçosREST) # 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](https://academy.fluig.com/theme/totvs_fluig_academy/landpage.php?course=95) 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.** ![](..\..\..\images\Passo%201.png) ## 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**. ![](..\..\..\images\Passo%203.png) - **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. **![](..\..\..\images\Passo%204.png)** - Clique **duas vezes** no servidor para validar a configuração. **![](..\..\..\images\Passo%205.png)** ## 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**. **![](..\..\..\images\c1.png)** - **Nome do projeto:** digite o nome do seu projeto. Ex.: `Projeto_Treinamento_Widgets, fluig, etc`. - Clique em **Finish**. ![](..\..\..\images\c2.png) 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): 1. Abra a pasta do seu projeto, localize a pasta **WCM** e, dentro dela, a pasta **Widget**. 2. Clique com o botão direito sobre a pasta **Widget** e selecione **New > Widget**. 3. Uma janela de configuração será aberta: 1. **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`. 2. **Nome:** o nome amigável que o usuário verá no catálogo de *widgets* ao editar uma página. Ex.: "Minha primeira *widget*". 3. **Descrição:** explique brevemente o propósito dela. 4. Na mesma tela de criação, haverá a opção de escolher um ***Template***. 1. Selecione a opção **"Nenhum".** 2. Ao escolher **"Nenhum"**, clique em **Next**. 3. Uma nova janela de configuração será aberta: 1. **Código/Nome/URL do desenvolvedor:** preencha com seus dados ou os da sua empresa. 2. **Categoria:** fundamental! É a "pasta" onde sua *widget* vai aparecer no menu do Fluig. Anote o nome exato. 3. **Renderizador:** mantenha **Freemarker**. É o motor de templates oficial do Fluig. 4. **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): ```

${i18n.getTranslation('widget.title')}

${i18n.getTranslation('widget.description')}

``` - **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](https://tdn.totvs.com/pages/viewpage.action?pageId=185735401#Comocriarumwidgetquebusqueconte%C3%BAdo-Armazenamento).* - 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 *widge*t, 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.info` do 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 *widge*t 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, como `id="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*](https://academy.fluig.com/theme/totvs_fluig_academy/landpage.php?course=97). ## 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 w*idget* é 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 `` 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!