447 lines
21 KiB
Markdown
447 lines
21 KiB
Markdown
|
---
|
|||
|
|
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.**
|
|||
|
|
|
|||
|
|
|
|||
|
|
|
|||
|
|
## 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):
|
|||
|
|
|
|||
|
|
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):
|
|||
|
|
|
|||
|
|
```
|
|||
|
|
<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](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 `<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!
|