rodolpho
1626 lines
59 KiB
Markdown
1626 lines
59 KiB
Markdown
---
|
||
title: WCMAPI
|
||
source: https://tdn.totvs.com/display/fluig/WCMAPI
|
||
path: \Plataforma Documentação técnica\Recurso de Páginas e Widgets (WCM)\WCMAPI.md
|
||
---
|
||
|
||
- 1 [Visão Geral](#WCMAPI-VisãoGeral)
|
||
- 1.1 [Como Começar](#WCMAPI-ComoComeçar)
|
||
- 1.2 [Contexto de Dados (Tenant e Página)](#WCMAPI-ContextodeDados(TenantePágina))
|
||
- 1.3 [Contexto da Página](#WCMAPI-ContextodaPágina)
|
||
- 1.4 [Usuário Atual](#WCMAPI-UsuárioAtual)
|
||
- 1.5 [Contexto do Usuário](#WCMAPI-ContextodoUsuário)
|
||
- 1.6 [Sessão e Autenticação](#WCMAPI-SessãoeAutenticação)
|
||
- 1.7 [Ambiente](#WCMAPI-Ambiente)
|
||
- 1.8 [Interface (UI)](#WCMAPI-Interface(UI))
|
||
- 1.9 [Carregamento de Recursos (CSS e JS)](#WCMAPI-CarregamentodeRecursos(CSSeJS))
|
||
- 1.10 [Renderização de Templates FTL](#WCMAPI-RenderizaçãodeTemplatesFTL)
|
||
- 1.11 [Ciclo de Vida de Widgets](#WCMAPI-CiclodeVidadeWidgets)
|
||
- 1.12 [Sistema de Eventos](#WCMAPI-SistemadeEventos)
|
||
- 1.13 [Requisições AJAX](#WCMAPI-RequisiçõesAJAX)
|
||
- 1.14 [OAuth](#WCMAPI-OAuth)
|
||
- 1.15 [Atributos de Sessão no Servidor](#WCMAPI-AtributosdeSessãonoServidor)
|
||
- 1.16 [Utilitários JavaScript](#WCMAPI-UtilitáriosJavaScript)
|
||
- 1.17 [Utilitários de URL](#WCMAPI-UtilitáriosdeURL)
|
||
- 1.18 [Configurações Globais jQuery](#WCMAPI-ConfiguraçõesGlobaisjQuery)
|
||
- 1.19 [Namespace WCM](#WCMAPI-NamespaceWCM)
|
||
- 1.20 [Boas Práticas](#WCMAPI-BoasPráticas)
|
||
- 1.21 [Erros Comuns](#WCMAPI-ErrosComuns)
|
||
- 1.22 [Dicas de Performance](#WCMAPI-DicasdePerformance)
|
||
|
||
# Visão Geral
|
||
|
||
---
|
||
|
||
O `WCMAPI` é a **API JavaScript central da plataforma Fluig WCM**. Ele expõe um objeto singleton global disponível em todos os widgets, temas e formulários da plataforma.
|
||
Por meio do `WCMAPI` você consegue:
|
||
|
||
- Saber quem é o usuário logado e qual é o tenant (empresa) ativo
|
||
- Ler o contexto da página atual (código, tipo, layout)
|
||
- Carregar dinamicamente arquivos CSS e JavaScript
|
||
- Renderizar templates FreeMarker (`.ftl`) de forma síncrona ou assíncrona
|
||
- Instanciar widgets via `loadWidgets()`
|
||
- Publicar e assinar eventos entre widgets (pub/sub)
|
||
- Realizar chamadas AJAX com autenticação JWT automática
|
||
- Validar tokens OAuth de integrações externas
|
||
- O objeto é acessível em **qualquer script carregado após este arquivo**:
|
||
|
||
```
|
||
// Sempre use o singleton - nunca instancie o WCMAPI diretamente
|
||
const usuarioLogado = WCMAPI.getUserLogin();
|
||
const tenant = WCMAPI.getTenantCode();
|
||
```
|
||
|
||
## Como Começar
|
||
|
||
---
|
||
|
||
O `WCMAPI` já estará disponível como variável global no momento em que seu widget ou tema for executado. **Não é necessário importar, instanciar ou configurar nada.**
|
||
|
||
### Dentro de um widget Fluig
|
||
|
||
```
|
||
// Verificar se o usuário está logado antes de fazer qualquer operação
|
||
if (WCMAPI.getUserIsLogged()) {
|
||
const login = WCMAPI.getUserLogin();
|
||
const nome = `${WCMAPI.getUserFirstName()} ${WCMAPI.getUserLastName()}`;
|
||
console.log(`Bem-vindo, ${nome}!`);
|
||
}
|
||
```
|
||
|
||
### Renderizando um template FTL no widget
|
||
|
||
```
|
||
// Renderizar o template view.ftl do app "meuWidget" e injetar no elemento #conteudo
|
||
WCMAPI.convertFtlAsync('meuWidget', 'view.ftl', { filtro: 'ativo' }, (html) => {
|
||
$('#conteudo').html(html);
|
||
WCMAPI.loadWidgets();
|
||
});
|
||
```
|
||
|
||
### Verificando feature flags
|
||
|
||
```
|
||
if (WCMAPI.isFeatureEnabled('NOVO_PAINEL')) {
|
||
carregarNovoPainel();
|
||
} else {
|
||
carregarPainelLegado();
|
||
}
|
||
```
|
||
|
||
## Contexto de Dados (Tenant e Página)
|
||
|
||
---
|
||
|
||
Estes valores são fornecidos automaticamente pela plataforma antes de qualquer widget ser inicializado.
|
||
|
||
**Regra fundamental:** nunca acesse ou modifique propriedades do `WCMAPI` diretamente (ex.: `WCMAPI.tenantCode`). Utilize **sempre** os métodos getter/setter correspondentes. O acesso direto às propriedades é considerado legado e pode ser removido em versões futuras.
|
||
|
||
### getTenantCode() / setTenantCode(value)
|
||
|
||
**Descrição:** Retorna ou define o código único que identifica o tenant (empresa) ativo. Preenchido automaticamente pela plataforma; raramente é necessário usar o setter em widgets.
|
||
**Retorno de `getTenantCode()`:** `string` — ex.: `'minhaempresa'`
|
||
**Parâmetros de `setTenantCode()`:**
|
||
|
||
- `value` (`string`): novo código do tenant
|
||
|
||
```
|
||
const tenant = WCMAPI.getTenantCode();
|
||
const url = `/api/public/2.0/${tenant}/users`;
|
||
```
|
||
|
||
### getTenantId() / getOrganizationId() / setOrganizationId(value)
|
||
|
||
**Descrição:** Retorna ou define o identificador numérico do tenant. `getTenantId()` é um alias para `getOrganizationId()`. Use `setOrganizationId()` para definir o valor — não existe `setTenantId()`.
|
||
**Retorno:** `number` — valor padrão `-1` quando não há tenant carregado.
|
||
**Parâmetros de `setOrganizationId()`:**
|
||
|
||
- `value` (`number`): identificador numérico do tenant
|
||
|
||
```
|
||
const idTenant = WCMAPI.getTenantId();
|
||
```
|
||
|
||
### getTenantURI() / setTenantURI(value)
|
||
|
||
**Descrição:** Retorna ou define o segmento de URI do tenant usado nas URLs de páginas da plataforma.
|
||
**Retorno de `getTenantURI()`:** `string` — ex.: `'/portal/p/minhaempresa'`
|
||
|
||
```
|
||
// Redirecionar para a home do tenant
|
||
window.location.href = `${WCMAPI.getTenantURI()}/home`;
|
||
```
|
||
|
||
### getTenantURL() / setTenantURL(value)
|
||
|
||
**Descrição:** Retorna ou define a URL completa do tenant (esquema + host + caminho do tenant).
|
||
**Retorno de `getTenantURL()`:** `string` — ex.: `'https://minhaempresa.fluig.com/minhaempresa'`
|
||
|
||
### getTenantPATH() / setTenantPATH(value)
|
||
|
||
**Descrição:** Retorna ou define apenas o segmento de caminho do tenant (sem esquema e host).
|
||
**Retorno de `getTenantPATH()`:** `string` — ex.: `'/minhaempresa'`
|
||
|
||
### getServerURL() / setServerURL(value)
|
||
|
||
**Descrição:** Retorna ou define a URL base do servidor (esquema + host), sem nenhum caminho adicional.
|
||
**Retorno de `getServerURL()`:** `string` — ex.: `'https://minhaempresa.fluig.com'`
|
||
|
||
### getServerContextURL() / setServerContextURL(value)
|
||
|
||
**Descrição:** Retorna ou define a URL completa do contexto do servidor (esquema + host + context path do portal).
|
||
**Retorno de `getServerContextURL()`:** `string`
|
||
|
||
### getContextPath() / setContextPath(value)
|
||
|
||
**Descrição:** Retorna ou define o context path do portal no servidor de aplicação.
|
||
**Retorno de `getContextPath()`:** `string` — ex.: `'/portal'`
|
||
|
||
### getHomePage()
|
||
|
||
**Descrição:** Monta e retorna a URL completa da página inicial do tenant.
|
||
**Retorno:** `string` — equivale a `getTenantURI() + '/' + getHomePageCode()`
|
||
|
||
```
|
||
// Redirecionar o usuário para a home
|
||
window.location.href = WCMAPI.getHomePage();
|
||
```
|
||
|
||
### getPageCode() / setPageCode(code) / getPageId() / setPageId(id) / getPageType() / setPageType(type) / getPageLayout() / setPageLayout(layoutId)
|
||
|
||
**Descrição:** Retornam ou definem informações sobre a página WCM atualmente renderizada. Os setters são utilizados internamente pela plataforma; em widgets, utilize apenas os getters.
|
||
|
||
| | | | |
|
||
| --- | --- | --- | --- |
|
||
| Getter | Setter | Retorno | Exemplo |
|
||
| `getPageCode()` | `setPageCode(code)` | `string|null` | `'home'` |
|
||
| `getPageId()` | `setPageId(id)` | `number|null` | `42` |
|
||
| `getPageType()` | `setPageType(type)` | `string|null` | `'public'` |
|
||
| `getPageLayout()` | `setPageLayout(layoutId)` | `number|null` | `3` |
|
||
| `getPageTitle()` | `setPageTitle(title)` | `string|null` | `'Início'` |
|
||
| `getParentPageCode()` | `setParentPageCode(code)` | `string|null` | `'portal'` |
|
||
| `getFriendlyURL()` | `setFriendlyURL(url)` | `string|null` | `'/inicio'` |
|
||
|
||
```
|
||
// Evitar exibir avisos na página de boas-vindas
|
||
if (WCMAPI.getPageCode() !== 'welcome') {
|
||
mostrarAvisoImportante();
|
||
}
|
||
```
|
||
|
||
### getSpaceAlias() / setSpaceAlias(value)
|
||
|
||
**Descrição:** Retorna ou define o alias (identificador curto) do espaço Fluig atual.
|
||
**Retorno de `getSpaceAlias()`:** `string` — ex.: `'default'`
|
||
|
||
```
|
||
const alias = WCMAPI.getSpaceAlias();
|
||
```
|
||
|
||
### getSpaceId() / setSpaceId(id)
|
||
|
||
**Descrição:** Retorna ou define o identificador numérico do espaço Fluig atual.
|
||
**Retorno de `getSpaceId()`:** `number|null`
|
||
|
||
```
|
||
const spaceId = WCMAPI.getSpaceId();
|
||
```
|
||
|
||
### getHomePageCode() / setHomePageCode(value)
|
||
|
||
**Descrição:** Retorna ou define o código da página configurada como home/landing page do tenant. Usado por `getHomePage()` para montar a URL completa.
|
||
**Retorno de `getHomePageCode()`:** `string` — padrão `'home'`
|
||
|
||
```
|
||
const homeCode = WCMAPI.getHomePageCode(); // 'home'
|
||
window.location.href = WCMAPI.getHomePage();
|
||
```
|
||
|
||
### getUploadURL() / setUploadURL(value)
|
||
|
||
**Descrição:** Retorna ou define a URL utilizada para operações de upload de arquivos na plataforma.
|
||
**Retorno de `getUploadURL()`:** `string`
|
||
|
||
```
|
||
const uploadEndpoint = WCMAPI.getUploadURL();
|
||
```
|
||
|
||
### getProtectedContextPath() / setProtectedContextPath(value)
|
||
|
||
**Descrição:** Retorna ou define o context path para recursos protegidos (que requerem autenticação).
|
||
**Retorno de `getProtectedContextPath()`:** `string`
|
||
|
||
```
|
||
const protectedPath = WCMAPI.getProtectedContextPath();
|
||
```
|
||
|
||
### getDomainId() / setDomainId(value) / getDomainName() / setDomainName(value)
|
||
|
||
**Descrição:** Retornam ou definem o identificador numérico e o nome legível do domínio atual, preenchidos pela plataforma no carregamento da página.
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| Getter | Setter | Retorno |
|
||
| `getDomainId()` | `setDomainId(id)` | `number|null` |
|
||
| `getDomainName()` | `setDomainName(name)` | `string|null` |
|
||
|
||
```
|
||
const domainId = WCMAPI.getDomainId();
|
||
const domainName = WCMAPI.getDomainName();
|
||
```
|
||
|
||
### getDefaultDomainURL() / setDefaultDomainURL(value)
|
||
|
||
**Descrição:** Retorna ou define a URL base padrão do domínio atual.
|
||
**Retorno de `getDefaultDomainURL()`:** `string|null`
|
||
|
||
```
|
||
const domainUrl = WCMAPI.getDefaultDomainURL();
|
||
```
|
||
|
||
### getIsSAMLEnabled() / setIsSAMLEnabled(value)
|
||
|
||
**Descrição:** Indica se a autenticação SAML/SSO está habilitada para o tenant. Quando `true`, o login é delegado ao Identity Provider configurado. Use `getIsSAMLEnabled()` no lugar do acesso à propriedade `isSAMLEnabled` diretamente.
|
||
|
||
> Veja também `isIdentityEnabled()`, que é um alias para `getIsSAMLEnabled()`.
|
||
> **Retorno de `getIsSAMLEnabled()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getIsSAMLEnabled()) {
|
||
// exibir botão "Entrar com SSO"
|
||
}
|
||
```
|
||
|
||
### getIdpHomePageURL() / setIdpHomePageURL(value)
|
||
|
||
**Descrição:** Retorna ou define a URL da página inicial do Identity Provider (IdP), usada nos fluxos de logout com SAML ativo.
|
||
**Retorno de `getIdpHomePageURL()`:** `string`
|
||
|
||
```
|
||
const idpUrl = WCMAPI.getIdpHomePageURL();
|
||
```
|
||
|
||
### getFluigPaas() / setFluigPaas(value)
|
||
|
||
**Descrição:** Indica se a plataforma está rodando em modo PaaS (Fluig em nuvem). Quando `true`, certos recursos e caminhos específicos de PaaS são ativados.
|
||
**Retorno de `getFluigPaas()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getFluigPaas()) {
|
||
usarRecursosDePaas();
|
||
}
|
||
```
|
||
|
||
### getApplicationCode() / setApplicationCode(value)
|
||
|
||
**Descrição:** Retorna ou define o código de aplicação usado para escopo de caminhos de recursos estáticos. Padrão: `'fluig'`.
|
||
**Retorno de `getApplicationCode()`:** `string`
|
||
|
||
```
|
||
const appCode = WCMAPI.getApplicationCode(); // 'fluig'
|
||
```
|
||
|
||
### getEnvType() / setEnvType(value)
|
||
|
||
**Descrição:** Retorna ou define o identificador do ambiente de implantação, como `'production'` ou `'staging'`.
|
||
**Retorno de `getEnvType()`:** `string`
|
||
|
||
```
|
||
if (WCMAPI.getEnvType() !== 'production') {
|
||
console.log('[DEV] Modo de diagnóstico ativo');
|
||
}
|
||
```
|
||
|
||
### getTenantLocales() / setTenantLocales(value)
|
||
|
||
**Descrição:** Retorna ou define a lista de códigos de idioma disponíveis para o tenant. Útil para renderizar seletores de idioma em widgets.
|
||
**Retorno de `getTenantLocales()`:** `string[]` — ex.: `'pt_BR', 'en_US'.`
|
||
|
||
```
|
||
const locales = WCMAPI.getTenantLocales();
|
||
locales.forEach((locale) => adicionarOpcaoDeIdioma(locale));
|
||
```
|
||
|
||
### isFeatureEnabled(featureFlag)
|
||
|
||
**Parâmetros:**
|
||
|
||
- `featureFlag` (`string`): identificador da feature a verificar
|
||
|
||
**Retorno:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.isFeatureEnabled('EXPORTAR_RELATORIO_PDF')) {
|
||
$('#btn-exportar-pdf').show();
|
||
}
|
||
```
|
||
|
||
### getIsEditMode() / setIsEditMode(value)
|
||
|
||
**Descrição:** Indica se a página está atualmente em modo de edição WCM. Quando `true`, a plataforma exibe controles de edição e a engrenagem dos widgets.
|
||
|
||
**Não acesse `WCMAPI.isEditMode` diretamente.** Use `getIsEditMode()` para leitura e `setIsEditMode()` para escrita.
|
||
**Retorno de `getIsEditMode()`:** `boolean`
|
||
**Parâmetros de `setIsEditMode()`:**
|
||
|
||
- `value` (`boolean`): `true` para ativar o modo de edição
|
||
|
||
```
|
||
if (WCMAPI.getIsEditMode()) {
|
||
mostrarControlesDeEdicao();
|
||
}
|
||
// Ativar programaticamente (raramente necessário em widgets):
|
||
WCMAPI.setIsEditMode(true);
|
||
```
|
||
|
||
## Contexto da Página
|
||
|
||
---
|
||
|
||
Essas informações são fornecidas automaticamente pela plataforma no carregamento da página e devem ser tratadas como somente leitura. O uso dos setters não tem efeito no comportamento da plataforma.
|
||
|
||
### getIsPreviewMode() / setIsPreviewMode(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se a página está sendo renderizada em modo de pré-visualização. Neste modo, as alterações ainda não foram publicadas e a URL geralmente contém o parâmetro `?preview=true`.
|
||
**Retorno de `getIsPreviewMode()`:** `string` — `'true'` ou `'false'` (chega como string do FreeMarker, não como boolean nativo).
|
||
|
||
```
|
||
if (WCMAPI.getIsPreviewMode() === 'true') {
|
||
mostrarAvisoPreVisualizacao();
|
||
}
|
||
```
|
||
|
||
### getPageAuthType() / setPageAuthType(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica o tipo de autenticação exigido para acesso à página atual.
|
||
**Retorno de `getPageAuthType()`:** `string` — ex.: `'PUBLIC'`, `'PRIVATE'`
|
||
|
||
```
|
||
if (WCMAPI.getPageAuthType() === 'PUBLIC') {
|
||
exibirConteudoPublico();
|
||
}
|
||
```
|
||
|
||
### getIsResponsiveLayout() / setIsResponsiveLayout(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se o layout da página atual é responsivo (adapta-se a diferentes tamanhos de tela).
|
||
**Retorno de `getIsResponsiveLayout()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getIsResponsiveLayout()) {
|
||
aplicarEstilosResponsivos();
|
||
}
|
||
```
|
||
|
||
### getIsNewBuilder() / setIsNewBuilder(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se a página foi construída com o editor New Builder da plataforma Fluig. Pode ser usado para ativar funcionalidades exclusivas do New Builder.
|
||
**Retorno de `getIsNewBuilder()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getIsNewBuilder()) {
|
||
habilitarRecursosNewBuilder();
|
||
}
|
||
```
|
||
|
||
### getPageIsInternal() / setPageIsInternal(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se a página está marcada como interna, ou seja, visível apenas para usuários autenticados. Quando `true`, o acesso anônimo deve ser bloqueado. Padrão `false` quando a variável não está presente no modelo do servidor.
|
||
**Retorno de `getPageIsInternal()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getPageIsInternal() && !WCMAPI.getUserIsLogged()) {
|
||
window.location.href = WCMAPI.getContextPath() + '/login';
|
||
}
|
||
```
|
||
|
||
## Usuário Atual
|
||
|
||
---
|
||
|
||
### getUserLogin() / setUserLogin(login)
|
||
|
||
**Descrição:** Retorna ou define o login (identificador único) do usuário autenticado.
|
||
**Retorno de `getUserLogin()`:** `string|null` — `null` se o usuário não estiver autenticado.
|
||
|
||
```
|
||
const login = WCMAPI.getUserLogin();
|
||
if (login) {
|
||
buscarPerfilUsuario(login);
|
||
}
|
||
```
|
||
|
||
### getUserId() / setUserId(id)
|
||
|
||
**Descrição:** Retorna ou define o identificador numérico do usuário autenticado.
|
||
**Retorno de `getUserId()`:** `number|null`
|
||
|
||
```
|
||
const idUsuario = WCMAPI.getUserId();
|
||
```
|
||
|
||
### getUserCode() / setUserCode(code)
|
||
|
||
**Descrição:** Retorna ou define o código do usuário (equivalente ao login na maioria dos casos).
|
||
**Retorno de `getUserCode()`:** `string`
|
||
|
||
### getUserFirstName() / setUserFirstName(value) / getUserLastName() / setUserLastName(value) / getUser() / setUser(value)
|
||
|
||
**Descrição:** Retornam ou definem as partes do nome do usuário autenticado.
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| Getter | Setter |
|
||
| `getUserFirstName()` | `setUserFirstName(value)` |
|
||
| `getUserLastName()` | `setUserLastName(value)` |
|
||
| `getUser()` | `setUser(value)` |
|
||
|
||
```
|
||
const nomeCompleto = `${WCMAPI.getUserFirstName()} ${WCMAPI.getUserLastName()}`;
|
||
$('#saudacao').text(`Olá, ${nomeCompleto}!`);
|
||
```
|
||
|
||
### getUserEmail() / setUserEmail(email)
|
||
|
||
**Descrição:** Retorna ou define o e-mail do usuário autenticado.
|
||
**Retorno de `getUserEmail()`:** `string`
|
||
|
||
### getUserLocationId() / setUserLocationId(id) / getUserLocationCode() / setUserLocationCode(code) / getUserLocationUrl() / setUserLocationUrl(url)
|
||
|
||
**Descrição:** Retornam ou definem informações sobre a localização (unidade/empresa) associada ao usuário.
|
||
|
||
```
|
||
const codigoFilial = WCMAPI.getUserLocationCode();
|
||
const idFilial = WCMAPI.getUserLocationId();
|
||
```
|
||
|
||
### getLocale() / setLocale(value) / getLocaleDisplayName() / setLocaleDisplayName(value)
|
||
|
||
**Descrição:** Retornam ou definem informações sobre o idioma configurado para o usuário.
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| Getter | Setter | Exemplo |
|
||
| `getLocale()` | `setLocale(value)` | `'pt_BR'` |
|
||
| `getLocaleDisplayName()` | `setLocaleDisplayName(value)` | `'português (Brasil)'` |
|
||
|
||
```
|
||
const locale = WCMAPI.getLocale(); // 'pt_BR'
|
||
```
|
||
|
||
### getTimezone() / setTimezone(value)
|
||
|
||
**Descrição:** Retorna ou define o identificador de fuso horário IANA configurado para o usuário.
|
||
**Retorno de `getTimezone()`:** `string|null` — ex.: `'America/Sao_Paulo'`
|
||
|
||
```
|
||
const tz = WCMAPI.getTimezone(); // 'America/Sao_Paulo'
|
||
```
|
||
|
||
### isAdmin()
|
||
|
||
**Descrição:** Verifica se o usuário atual possui privilégios de administrador da plataforma Fluig.
|
||
**Retorno:** `boolean`
|
||
|
||
> **Atenção:** Esta operação é **síncrona** e faz uma chamada ao servidor. Evite utilizá-la em loops ou em caminhos críticos de renderização.
|
||
|
||
```
|
||
if (WCMAPI.isAdmin()) {
|
||
$('#painel-admin').show();
|
||
}
|
||
```
|
||
|
||
### isIdentityEnabled()
|
||
|
||
**Descrição:** Indica se a autenticação SAML/SSO está habilitada para o tenant.
|
||
**Retorno:** `boolean`
|
||
|
||
## Contexto do Usuário
|
||
|
||
---
|
||
|
||
Essas informações são fornecidas automaticamente pela plataforma no carregamento da página e devem ser tratadas como somente leitura.
|
||
|
||
> Disponíveis apenas quando `WCMAPI.getUserIsLogged()` retorna `true`.
|
||
> Para os métodos completos de acesso aos dados do usuário (login, email, nome etc.), consulte a seção [Usuário Atual](https://tdn.totvs.com/pages/viewpage.action?pageId=1060213081#WCMAPIAtualiza%C3%A7%C3%A3odadocumenta%C3%A7%C3%A3o-usu%C3%A1rio-atual).
|
||
|
||
### getUserType() / setUserType(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Retorna o tipo de conta do usuário autenticado, conforme cadastrado na plataforma.
|
||
**Retorno de `getUserType()`:** `string` — ex.: `'interno'`, `'externo'`
|
||
|
||
```
|
||
const tipo = WCMAPI.getUserType();
|
||
if (tipo === 'externo') {
|
||
ocultarMenusInternos();
|
||
}
|
||
```
|
||
|
||
### getIsMobileAppMode()
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se a plataforma está sendo executada dentro de um aplicativo móvel Fluig. O valor é determinado em tempo de renderização pelo servidor e não muda após o carregamento da página.
|
||
**Retorno:** `boolean` — `true` se executando dentro do app móvel
|
||
|
||
```
|
||
if (WCMAPI.getIsMobileAppMode()) {
|
||
ocultarFuncionalidadesDesktop();
|
||
ativarInterfaceMobile();
|
||
}
|
||
```
|
||
|
||
## Sessão e Autenticação
|
||
|
||
---
|
||
|
||
### getUserIsLogged() / setUserIsLogged(value)
|
||
|
||
**Descrição:** Retorna ou define se o usuário está autenticado na sessão atual. O setter aceita `boolean` ou as strings `'true'`/`'false'` para compatibilidade com valores vindos de templates JSP/FreeMarker.
|
||
**Retorno de `getUserIsLogged()`:** `boolean`
|
||
|
||
```
|
||
if (!WCMAPI.getUserIsLogged()) {
|
||
window.location.href = `${WCMAPI.getContextPath()}/login`;
|
||
}
|
||
```
|
||
|
||
### getIsStateless() / setIsStateless(value)
|
||
|
||
**Descrição:** Indica ou define se a plataforma está operando em modo stateless (sem sessão HTTP, apenas JWT). Nesse modo, as verificações de sessão e o ping de keep-alive são desativados automaticamente.
|
||
**Retorno de `getIsStateless()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getIsStateless()) {
|
||
// autenticação baseada apenas em JWT
|
||
}
|
||
```
|
||
|
||
### extendSession()
|
||
|
||
**Descrição:** Reinicia os contadores de expiração da sessão. Deve ser chamado em resposta a interações do usuário para evitar logout por inatividade.
|
||
Internamente, agenda:
|
||
|
||
- Um aviso após **28 minutos** de inatividade
|
||
- O logout forçado após **29 minutos** de inatividade
|
||
- Não tem efeito no modo stateless ou quando cookies SAML estão presentes.
|
||
|
||
```
|
||
$(document).on('mousemove keydown click', () => {
|
||
WCMAPI.extendSession();
|
||
});
|
||
```
|
||
|
||
### login(user, password)
|
||
|
||
**Descrição:** Autentica o usuário com login e senha. Em caso de sucesso, recarrega a página; em caso de falha, exibe um alerta nativo do navegador.
|
||
**Parâmetros:**
|
||
|
||
- `user` (`string`): login do usuário
|
||
- `password` (`string`): senha em texto plano
|
||
|
||
**Retorno:** `boolean|*` — `true` em caso de sucesso
|
||
|
||
> A senha é transmitida em texto plano para o `WCMSpaceAPI`. Certifique-se de usar HTTPS.
|
||
|
||
```
|
||
var ok = WCMAPI.login('admin', 'minhasenha');
|
||
```
|
||
|
||
### logoff()
|
||
|
||
**Descrição:** Encerra a sessão do usuário e redireciona para o endpoint de logout da plataforma. A operação é imediata e irrecuperável — o usuário será redirecionado para a tela de login.
|
||
|
||
```
|
||
$('#btn-sair').on('click', () => WCMAPI.logoff());
|
||
```
|
||
|
||
### hasPermissionToChangePermission(callback)
|
||
|
||
**Descrição:** Verifica de forma assíncrona se o usuário logado tem o direito de gerenciar permissões na plataforma (recurso `PermissionsAdmin` com ação `execute`).
|
||
**Parâmetros:**
|
||
|
||
- `callback` (`Function`): chamado com `(err, result)` onde `result.content` é `boolean`
|
||
|
||
**Retorno:** `jqXHR` — o objeto de deferred do jQuery
|
||
|
||
```
|
||
WCMAPI.hasPermissionToChangePermission((err, result) => {
|
||
if (result?.content) {
|
||
$('#btn-gerenciar-permissoes').show();
|
||
}
|
||
});
|
||
```
|
||
|
||
## Ambiente
|
||
|
||
---
|
||
|
||
Essas informações são fornecidas automaticamente pela plataforma no carregamento da página e devem ser tratadas como somente leitura. Elas refletem a configuração da instância no momento da renderização.
|
||
|
||
### getVersion() / setVersion(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Retorna a versão da plataforma Fluig. Útil para lógica condicional baseada em versão ou para exibição em painéis de diagnóstico.
|
||
**Retorno de `getVersion()`:** `string` — ex.: `'1.7.0'`
|
||
|
||
```
|
||
const versao = WCMAPI.getVersion(); // '1.7.0'
|
||
```
|
||
|
||
### getFluigVersion() / setFluigVersion(value) / getFluigInstanceVersionName() / setFluigInstanceVersionName(value) / getFluigVersionBuild() / setFluigVersionBuild(value) / getFluigVersionStatus() / setFluigVersionStatus(value) / getFluigVersionStatusInfo() / setFluigVersionStatusInfo(value)
|
||
|
||
**Somente leitura** — disponível apenas quando informações detalhadas de versão estiverem configuradas na plataforma.
|
||
**Descrição:** Informações detalhadas da versão da instância WCM, mais granulares do que `getVersion()`. Se não estiverem configuradas, os métodos retornam string vazia.
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| Getter | Setter | Exemplo de retorno |
|
||
| `getFluigVersion()` | `setFluigVersion(value)` | `'2.0.0-260417'` |
|
||
| `getFluigInstanceVersionName()` | `setFluigInstanceVersionName(value)` | `'Voyager'` |
|
||
| `getFluigVersionBuild()` | `setFluigVersionBuild(value)` | `'788'` |
|
||
| `getFluigVersionStatus()` | `setFluigVersionStatus(value)` | `'0'`, `'1'` |
|
||
| `getFluigVersionStatusInfo()` | `setFluigVersionStatusInfo(value)` | texto descritivo |
|
||
|
||
```
|
||
const ver = WCMAPI.getFluigVersion(); // '2.0.0-260417'
|
||
const build = WCMAPI.getFluigVersionBuild(); // '6727'
|
||
const status = WCMAPI.getFluigVersionStatus(); // '0'
|
||
```
|
||
|
||
### getNocodeActive() / setNocodeActive(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se o módulo No-Code está ativo para o tenant atual. Quando `true`, funcionalidades de criação de aplicações sem código estão habilitadas. Padrão `false` quando a variável não estiver presente no modelo do servidor.
|
||
**Retorno de `getNocodeActive()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getNocodeActive()) {
|
||
habilitarMenuNoCode();
|
||
}
|
||
```
|
||
|
||
### getGoogleAnalyticsEnabled() / setGoogleAnalyticsEnabled(value) / getGoogleAnalyticsAccount() / setGoogleAnalyticsAccount(value)
|
||
|
||
**Somente leitura** — fornecidos automaticamente pela plataforma.
|
||
**Descrição:** Indicam se o Google Analytics está ativo e qual é o ID da conta configurada para o tenant. Use em conjunto para inicializar o rastreamento.
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| Getter | Setter | Retorno |
|
||
| `getGoogleAnalyticsEnabled()` | `setGoogleAnalyticsEnabled(value)` | `boolean` |
|
||
| `getGoogleAnalyticsAccount()` | `setGoogleAnalyticsAccount(value)` | `string`, ex.: `'UA-XXXXX-Y'` |
|
||
|
||
```
|
||
if (WCMAPI.getGoogleAnalyticsEnabled()) {
|
||
inicializarGoogleAnalytics(WCMAPI.getGoogleAnalyticsAccount());
|
||
}
|
||
```
|
||
|
||
## Interface (UI)
|
||
|
||
---
|
||
|
||
Essas informações são fornecidas automaticamente pela plataforma no carregamento da página e devem ser tratadas como somente leitura. Refletem a configuração visual do tema ativo e as funcionalidades de edição de texto do tenant.
|
||
|
||
### getThemeId() / setThemeId(id)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Retorna o identificador numérico do tema aplicado à página atual. Chega como string do FreeMarker; converta com `parseInt()` se necessário.
|
||
**Retorno de `getThemeId()`:** `string` (número como string) — ex.: `'3'`
|
||
|
||
```
|
||
const themeId = parseInt(WCMAPI.getThemeId(), 10);
|
||
```
|
||
|
||
### getColorMenu() / setColorMenu(value) / getColorBackground() / setColorBackground(value)
|
||
|
||
**Somente leitura** — fornecidos automaticamente pela plataforma.
|
||
**Descrição:** Retornam as cores definidas pelo tema ativo — a cor do menu de navegação e a cor de fundo da página, respectivamente. Úteis para personalização dinâmica de componentes que precisam combinar com o tema.
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| Getter | Setter | Descrição |
|
||
| `getColorMenu()` | `setColorMenu(value)` | Cor do menu de navegação, ex.: `'#003366'` |
|
||
| `getColorBackground()` | `setColorBackground(value)` | Cor de fundo da página, ex.: `'#f5f5f5'` |
|
||
|
||
```
|
||
const corMenu = WCMAPI.getColorMenu();
|
||
$('.meu-componente-header').css('background-color', corMenu);
|
||
```
|
||
|
||
### getImageBackground() / setImageBackground(value) / getImageLogo() / setImageLogo(value)
|
||
|
||
**Somente leitura** — fornecidos automaticamente pela plataforma.
|
||
**Descrição:** Retornam as URLs das imagens configuradas no tema ativo — imagem de fundo da página e logotipo exibido no cabeçalho. Vazios quando não configurados.
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| Getter | Setter | Descrição |
|
||
| `getImageBackground()` | `setImageBackground(value)` | URL da imagem de fundo da página |
|
||
| `getImageLogo()` | `setImageLogo(value)` | URL do logotipo do cabeçalho |
|
||
|
||
```
|
||
const logo = WCMAPI.getImageLogo();
|
||
if (logo) {
|
||
$('#logo-customizado').attr('src', logo);
|
||
}
|
||
```
|
||
|
||
### getIsDisabledRichEditor() / setIsDisabledRichEditor(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se o editor de texto rico (rich editor) foi substituído pelo editor simples (simple editor) para o tenant. Quando `true`, o `loadJS` troca automaticamente caminhos contendo `'richeditor'` por `'simpleeditor'`.
|
||
**Retorno de `getIsDisabledRichEditor()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getIsDisabledRichEditor()) {
|
||
inicializarEditorSimples();
|
||
} else {
|
||
inicializarEditorRico();
|
||
}
|
||
```
|
||
|
||
### getEnableRichEditorSanitizer() / setEnableRichEditorSanitizer(value)
|
||
|
||
**Somente leitura** — fornecido automaticamente pela plataforma.
|
||
**Descrição:** Indica se a sanitização XSS está ativa no editor de texto rico. Quando `true`, o conteúdo gerado pelo usuário passa por sanitização antes de ser salvo, prevenindo a injeção de scripts maliciosos.
|
||
**Retorno de `getEnableRichEditorSanitizer()`:** `boolean`
|
||
|
||
```
|
||
if (WCMAPI.getEnableRichEditorSanitizer()) {
|
||
// sanitização XSS já está ativa no editor rico do tenant
|
||
console.log('XSS sanitizer habilitado');
|
||
}
|
||
```
|
||
|
||
## Carregamento de Recursos (CSS e JS)
|
||
|
||
### loadCSS(path)
|
||
|
||
**Descrição:** Injeta dinamicamente um arquivo CSS no `<head>` da página, evitando duplicatas.
|
||
**Quando usar:** sempre que um widget ou componente precisar de um arquivo CSS específico.
|
||
**Parâmetros:**
|
||
|
||
- `path` (`string`): URL ou caminho do arquivo CSS
|
||
|
||
```
|
||
WCMAPI.loadCSS('/wcm/resources/css/meu-widget.css');
|
||
```
|
||
|
||
### loadJS(path, callback)
|
||
|
||
**Descrição:** Carrega dinamicamente um arquivo JavaScript com cache habilitado, evitando carregamentos duplicados.
|
||
**Quando usar:** sempre que um widget precisar de um script externo. Prefira sempre `WCMAPI.loadJS()` em vez de `$.getScript()` dentro da plataforma — o WCMAPI garante controle de duplicatas e cache correto.
|
||
**Parâmetros:**
|
||
|
||
- `path` (`string`): URL ou caminho do arquivo JavaScript
|
||
- `callback` (`Function`, opcional): executado após o carregamento
|
||
|
||
```
|
||
WCMAPI.loadJS('/my_custom_path/resources/js/meu-script.js', () => {
|
||
// faça algo
|
||
});
|
||
```
|
||
|
||
### jsBasePath()
|
||
|
||
**Descrição:** Retorna o diretório base da última tag `<script>` adicionada à página no momento da chamada. Útil para resolver caminhos relativos dentro de scripts inline de widgets que não possuem acesso a um sistema de módulos.
|
||
**Retorno:** `string`
|
||
|
||
```
|
||
const base = WCMAPI.jsBasePath();
|
||
WCMAPI.loadJS(`${base}/helpers.js`);
|
||
```
|
||
|
||
## Renderização de Templates FTL
|
||
|
||
---
|
||
|
||
### convertFtlAsync(appCode, fileNameFtl, pars, callback, errorCallback)
|
||
|
||
**Descrição:** Renderiza um template FreeMarker (`.ftl`) de um aplicativo Fluig de forma **assíncrona** (não bloqueante) e entrega o HTML resultante por meio de um callback.
|
||
CSS e JS declarados pelo template são carregados automaticamente após a resposta.
|
||
**Parâmetros:**
|
||
|
||
- `appCode` (`string`): código do aplicativo Fluig, ex.: `'wcm_meupainel'`
|
||
- `fileNameFtl` (`string`): nome do arquivo FTL, ex.: `'view.ftl'`
|
||
- `pars` (`Object|string`): parâmetros passados ao template (serializado automaticamente se for objeto)
|
||
- `callback` (`Function`): chamado com o HTML renderizado — `callback(html)`
|
||
- `errorCallback` (`Function`, opcional): chamado em caso de erro — `errorCallback(err)`
|
||
|
||
```
|
||
WCMAPI.convertFtlAsync(
|
||
'meuApp',
|
||
'view.ftl',
|
||
{ usuarioId: WCMAPI.getUserId(), filtro: 'ativo' },
|
||
(html) => {
|
||
$('#meu-container').html(html);
|
||
WCMAPI.loadWidgets();
|
||
},
|
||
(erro) => {
|
||
console.error('Falha ao renderizar o template', erro);
|
||
}
|
||
);
|
||
```
|
||
|
||
> ✅ **Prefira este método** ao `convertFtl()` em qualquer situação onde o bloqueio da thread do navegador seja indesejável.
|
||
|
||
### convertFtl(appCode, fileNameFtl, pars, component, callback)
|
||
|
||
**Descrição:** Renderiza um template FTL de forma **síncrona** (bloqueante) e injeta o HTML resultante em um elemento da página. Também carrega os recursos CSS e JS declarados pelo template.
|
||
**Parâmetros:**
|
||
|
||
- `appCode` (`string`): código do aplicativo Fluig
|
||
- `fileNameFtl` (`string`): nome do arquivo FTL
|
||
- `pars` (`Object|string`): parâmetros para o template
|
||
- `component` (`string|jQuery`): ID do elemento ou objeto jQuery onde o HTML será injetado. Passe `undefined` para receber o HTML como string de retorno
|
||
- `callback` (`Function`, opcional): executado após todos os recursos JS serem carregados
|
||
|
||
**Retorno:** `string` — HTML renderizado quando `component` é `undefined`; caso contrário, `""`
|
||
|
||
```
|
||
WCMAPI.convertFtl('meuApp', 'edit.ftl', { id: 10 }, 'div-edicao', () => {
|
||
console.log('Widget em modo de edição pronto');
|
||
});
|
||
const html = WCMAPI.convertFtl('meuApp', 'partial.ftl', { id: 10 });
|
||
$('#lista').append(html);
|
||
```
|
||
|
||
> **Atenção:** Esta versão bloqueia o navegador durante o round-trip ao servidor. Use `convertFtlAsync()` sempre que possível.
|
||
|
||
### extractHtmlContentAndResources(html, appCode) *(interno)*
|
||
|
||
**Descrição:** Método interno utilizado por `convertFtl` e `convertFtlAsync` para separar o HTML renderizado em nós de conteúdo DOM e descritores de recursos (CSS/JS). Não deve ser chamado diretamente por widgets.
|
||
|
||
## Ciclo de Vida de Widgets
|
||
|
||
---
|
||
|
||
### loadWidgets()
|
||
|
||
**Descrição:** Inicializa os widgets presentes na página. Chamado automaticamente pela plataforma no carregamento da página e ao final de `convertFtl` / `convertFtlAsync`.
|
||
**Quando usar:** sempre que widgets forem carregados dinamicamente — por exemplo, após injetar HTML via `convertFtlAsync`, `convertFtl` ou uma requisição AJAX.
|
||
|
||
```
|
||
$.get('/minha-api/widget-html', (html) => {
|
||
$('#container').html(html);
|
||
WCMAPI.loadWidgets();
|
||
});
|
||
```
|
||
|
||
### openEditMode(instId, slot) / openViewMode(instId, slot)
|
||
|
||
**Descrição:** Re-renderizam sincronamente uma instância de widget em modo de edição ou visualização, substituindo o nó DOM atual.
|
||
**Parâmetros:**
|
||
|
||
- `instId` (`number`): ID numérico da instância do widget
|
||
- `slot` (`string`): ID do elemento slot container
|
||
|
||
```
|
||
// Abrir o widget de ID 42 em modo de edição
|
||
WCMAPI.openEditMode(42, 'slot-principal');
|
||
```
|
||
|
||
### editContent(control, instanceId)
|
||
|
||
**Descrição:** Re-renderiza um widget em modo de edição quando acionado pelo ícone de engrenagem no modo de visualização. Diferente de `openEditMode()`, este método também carrega os recursos CSS e JS declarados pelo template de edição antes de injetar o HTML.
|
||
**Parâmetros:**
|
||
|
||
- `control` (`Element|string`): elemento DOM clicado, usado para localizar o slot pai
|
||
- `instanceId` (`number`): ID numérico da instância
|
||
|
||
### updateWidgetPreferences(instanceId, prefs)
|
||
|
||
**Descrição:** Salva as preferências de um widget para **todos os usuários** e re-renderiza o widget em modo de edição imediatamente, para que o usuário veja o resultado da configuração.
|
||
**Parâmetros:**
|
||
|
||
- `instanceId` (`number`): ID numérico da instância do widget
|
||
- `prefs` (`Object`): pares chave/valor das preferências a salvar
|
||
|
||
**Retorno:** `boolean` — `true` em caso de sucesso, `false` em caso de falha
|
||
|
||
```
|
||
const salvo = WCMAPI.updateWidgetPreferences(12, {
|
||
cor: '#003366',
|
||
exibirCabecalho: true,
|
||
quantidadeItens: 5
|
||
});
|
||
if (!salvo) {
|
||
alert('Erro ao salvar as configurações. Tente novamente.');
|
||
}
|
||
```
|
||
|
||
### updateUserWidgetPreferences(instanceId, prefs)
|
||
|
||
**Descrição:** Idêntico a `updateWidgetPreferences()`, porém as preferências são salvas **apenas para o usuário logado**, permitindo personalização individual.
|
||
**Parâmetros:**
|
||
|
||
- `instanceId` (`number`): ID numérico da instância
|
||
- `prefs` (`Object`): pares chave/valor das preferências
|
||
|
||
**Retorno:** `boolean`
|
||
|
||
```
|
||
// Salvar preferência de idioma apenas para este usuário
|
||
WCMAPI.updateUserWidgetPreferences(12, { idioma: 'en_US' });
|
||
```
|
||
|
||
## Sistema de Eventos
|
||
|
||
---
|
||
|
||
O `WCMAPI` oferece um barramento de eventos pub/sub para comunicação desacoplada entre widgets e temas. Os nomes dos eventos padrão (como `WCMAPI.LISTENER_LOGIN`) são constantes injetadas pela plataforma.
|
||
|
||
### Eventos disponíveis
|
||
|
||
| | |
|
||
| --- | --- |
|
||
| Constante | Quando dispara |
|
||
| `WCMAPI.LISTENER_LOGIN` | Quando o usuário efetua login |
|
||
| `WCMAPI.LISTENER_LOGOUT` | Quando o usuário efetua logout |
|
||
| `WCMAPI.LISTENER_EDITMODEON` | Quando o modo de edição é ativado |
|
||
| `WCMAPI.LISTENER_EDITMODEOFF` | Quando o modo de edição é desativado |
|
||
| `WCMAPI.LISTENER_SAVEWIDGETPREFS_OPEN` | Quando o painel de preferências de widget é aberto |
|
||
| `WCMAPI.LISTENER_SAVEWIDGETPREFS_CLOSE` | Quando o painel de preferências de widget é fechado |
|
||
| `WCMAPI.LISTENER_BEFORE_SAVEWIDGETPREFS` | Antes de salvar as preferências de widget |
|
||
| `WCMAPI.LISTENER_AFTER_SAVEWIDGETPREFS` | Após salvar as preferências de widget |
|
||
|
||
### addListener(oObj, eventName, callback, listenerName)
|
||
|
||
**Descrição:** Registra uma função de callback para ser chamada quando o evento indicado for disparado. Se um listener com o mesmo `listenerName` já estiver registrado para o mesmo evento, ele será atualizado em vez de duplicado.
|
||
**Parâmetros:**
|
||
|
||
- `oObj` (`Object`): contexto (`this`) para o callback
|
||
- `eventName` (`string`): nome do evento (ex.: `WCMAPI.LISTENER_LOGIN`)
|
||
- `callback` (`Function`): função chamada com `(eventName, data)`
|
||
- `listenerName` (`string`, opcional): nome único do listener, padrão `'DEFAULT'`
|
||
|
||
**Retorno:** `boolean` — sempre `true`
|
||
|
||
```
|
||
WCMAPI.addListener(
|
||
this,
|
||
WCMAPI.LISTENER_EDITMODEON,
|
||
(eventName, data) => meuWidget.mostrarControlesDeEdicao(),
|
||
'meuWidget-editmode'
|
||
);
|
||
```
|
||
|
||
### removeListener(eventName, listenerName)
|
||
|
||
**Descrição:** Remove um listener registrado pelo nome.
|
||
**Parâmetros:**
|
||
|
||
- `eventName` (`string`): nome do evento
|
||
- `listenerName` (`string`, opcional): nome do listener a remover, padrão `'DEFAULT'`
|
||
|
||
```
|
||
// Remover o listener ao destruir o widget
|
||
WCMAPI.removeListener(WCMAPI.LISTENER_EDITMODEON, 'meuWidget-editmode');
|
||
```
|
||
|
||
### fireEvent(eventName, data)
|
||
|
||
**Descrição:** Dispara todos os listeners registrados para o evento informado. Erros dentro de callbacks individuais são silenciados para não impedir a notificação dos demais listeners.
|
||
**Parâmetros:**
|
||
|
||
- `eventName` (`string`): nome do evento a disparar
|
||
- `data` (`*`, opcional): payload enviado para todos os listeners
|
||
|
||
```
|
||
WCMAPI.fireEvent('DOCUMENTO_SELECIONADO', { id: 99, titulo: 'Contrato 2024' });
|
||
WCMAPI.addListener(this, 'DOCUMENTO_SELECIONADO', (evt, data) => {
|
||
console.log('Documento selecionado:', data.titulo);
|
||
}, 'visualizador-docs');
|
||
```
|
||
|
||
### containsListener(eventName, listener, varIdx)
|
||
|
||
**Descrição:** Verifica se um listener com o nome informado já está registrado para um evento. Método interno, raramente necessário em widgets.
|
||
**Retorno:** `boolean`
|
||
|
||
## Requisições AJAX
|
||
|
||
---
|
||
|
||
O `WCMAPI` oferece métodos CRUD padronizados que já aplicam as configurações padrão da plataforma (JSON content-type, tratamento de erros, serialização automática).
|
||
|
||
> **JWT Automático:** Todas as requisições jQuery feitas na plataforma recebem automaticamente o header `Authorization: Bearer <token>` via `$.ajaxSetup()`, desde que o cookie `jwt.token` esteja presente.
|
||
|
||
### Create(options) / Read(options) / Update(options) / Delete(options)
|
||
|
||
**Importante:** Os métodos WCMAPI.Create(), WCMAPI.Read(), WCMAPI.Update() e Delete(options) estão depreciados. Use FLUIGC.ajax() ou $.ajax() que fornece uma API mais robusta e moderna.
|
||
|
||
**Descrição:** Wrappers padronizados para chamadas AJAX com os verbos HTTP correspondentes (`POST`, `GET`, `PUT`, `DELETE`). Qualquer `options.data` que seja objeto ou array é automaticamente serializado para JSON antes do envio.
|
||
**Parâmetros:**
|
||
|
||
- `options` (`Object`): configuração jQuery.ajax. `url` é obrigatório.
|
||
- `options.data`: payload da requisição (auto-serializado se for objeto)
|
||
- `options.success`: callback de sucesso com a resposta parseada
|
||
|
||
```
|
||
WCMAPI.Create({
|
||
url: '/api/public/2.0/posts',
|
||
data: { titulo: 'Meu Post', conteudo: 'Texto aqui' },
|
||
success: (resposta) => {
|
||
console.log('Post criado com ID:', resposta.content.id);
|
||
}
|
||
});
|
||
WCMAPI.Read({
|
||
url: `/api/public/2.0/documents/${documentoId}`,
|
||
success: (resposta) => {
|
||
exibirDocumento(resposta.content);
|
||
}
|
||
});
|
||
WCMAPI.Update({
|
||
url: `/api/public/2.0/documents/${documentoId}`,
|
||
data: { titulo: 'Título Atualizado' },
|
||
success: () => mostrarMensagemSucesso()
|
||
});
|
||
WCMAPI.Delete({
|
||
url: `/api/public/2.0/documents/${documentoId}`,
|
||
success: () => removerDaLista(documentoId)
|
||
});
|
||
```
|
||
|
||
### callCommand(command, data, oObj, callback, errorCallback, dataType)
|
||
|
||
**Descrição:** Realiza uma requisição GET simples, prefixando o `command` com o valor retornado por `WCMAPI.getServerURL()`. O errorCallback é opcional; se omitido, erros são ignorados silenciosamente.
|
||
**Parâmetros:**
|
||
|
||
- `command` (`string`): caminho da URL (anexado ao valor de `getServerURL()`)
|
||
- `data` (`*`): dado repassado ao callback de sucesso e erro
|
||
- `oObj` (`Object`): contexto (`this`) para os callbacks
|
||
- `callback` (`Function`): `callback(response, data)`
|
||
- `errorCallback` (`Function`, opcional): `errorCallback(xhr, textStatus, errorThrown, data)`
|
||
- `dataType` (`string`, opcional): tipo de dado esperado, padrão `'json'`
|
||
|
||
```
|
||
WCMAPI.callCommand(
|
||
'/wcm/api/rest/wcm/usuario/atual',
|
||
null,
|
||
this,
|
||
(response) => console.log('Usuário:', response)
|
||
);
|
||
```
|
||
|
||
### readHtml(options)
|
||
|
||
**Descrição:** Atalho para fazer uma requisição AJAX com as configurações padrão da plataforma, mescladas com as opções fornecidas.
|
||
|
||
```
|
||
WCMAPI.readHtml({
|
||
url: '/wcm/api/rest/wcm/minha-rota',
|
||
dataType: 'html',
|
||
success: (html) => $('#container').html(html)
|
||
});
|
||
```
|
||
|
||
### syncAjax(url)
|
||
|
||
**Descrição:** Realiza uma requisição GET síncrona (bloqueante) e retorna o texto da resposta.
|
||
**Parâmetros:**
|
||
|
||
- `url` (`string`): URL da requisição
|
||
|
||
**Retorno:** `string|false` — texto da resposta, ou `false` se o objeto XHR não puder ser criado
|
||
|
||
> Use com extrema moderação
|
||
>
|
||
> Requisições síncronas bloqueiam completamente a thread do navegador e estão obsoletas nos padrões modernos. Este método é usado internamente apenas nos pings de keep-alive de sessão.
|
||
|
||
### failHandler(args, styleGuide) *(usado internamente)*
|
||
|
||
**Descrição:** Tratador centralizado de erros AJAX, chamado automaticamente pelo objeto padrão retornado por `ajaxRequestDefault()`. Inspeciona o Content-Type e o status HTTP da resposta para exibir a mensagem de erro correta.
|
||
|
||
- Quando `styleGuide = true`: usa componentes FLUIGC (modais e mensagens)
|
||
- Quando `styleGuide = false`: usa os componentes legados WCMC
|
||
- Raramente você precisará chamar este método diretamente.
|
||
|
||
```
|
||
$.ajax({
|
||
url: '/minha-api',
|
||
error: (xhr) => WCMAPI.failHandler(xhr, true)
|
||
});
|
||
```
|
||
|
||
## OAuth
|
||
|
||
---
|
||
|
||
### validateAndAuthenticateOAuth(consumerKey)
|
||
|
||
**Descrição:** Valida o token OAuth para uma chave de consumer e, caso o token esteja ausente ou inválido, inicia o fluxo de autorização abrindo a URL do provedor em uma nova aba.
|
||
Use este método antes de fazer chamadas a APIs de terceiros integradas via OAuth (ex: Google Drive, Dropbox).
|
||
**Parâmetros:**
|
||
|
||
- `consumerKey` (`string`): chave do consumer OAuth da integração
|
||
|
||
**Retorno:** `boolean` — `true` se o token é válido; `false` se o fluxo de autorização foi iniciado
|
||
|
||
```
|
||
// Verificar e autenticar antes de usar o Google Drive
|
||
if (WCMAPI.validateAndAuthenticateOAuth('google-drive')) {
|
||
carregarArquivosGoogleDrive();
|
||
} else {
|
||
// O usuário será redirecionado para autorizar o acesso
|
||
mostrarMensagem('Autorizando acesso ao Google Drive...');
|
||
}
|
||
```
|
||
|
||
### validateOAuth(consumerKey)
|
||
|
||
**Descrição:** Verifica a validade do token OAuth **sem iniciar o fluxo de autorização**. Use quando você precisa apenas verificar o status para, por exemplo, exibir um botão "Conectar".
|
||
**Parâmetros:**
|
||
|
||
- `consumerKey` (`string`): chave do consumer OAuth
|
||
|
||
**Retorno:** `boolean` — `true` se o token é válido
|
||
|
||
```
|
||
if (!WCMAPI.validateOAuth('minha-integracao')) {
|
||
$('#btn-conectar').show();
|
||
} else {
|
||
$('#btn-conectar').hide();
|
||
carregarDadosDaIntegracao();
|
||
}
|
||
```
|
||
|
||
## Atributos de Sessão no Servidor
|
||
|
||
---
|
||
|
||
### setSessionAttribute(name, value) / getSessionAttribute(name)
|
||
|
||
**Descrição:** Armazena e recupera atributos na sessão HTTP do servidor via chamadas síncronas ao `WCMSpaceAPI.SessionService`.
|
||
**Parâmetros:**
|
||
|
||
- `name` (`string`): chave do atributo de sessão
|
||
- `value` (`*`): valor a armazenar (somente para `setSessionAttribute`)
|
||
|
||
```
|
||
// Salvar o ID do último documento visualizado
|
||
WCMAPI.setSessionAttribute('ultimo-documento', 42);
|
||
// Recuperar o valor posteriormente (em outra página/widget)
|
||
var ultimoDoc = WCMAPI.getSessionAttribute('ultimo-documento');
|
||
if (ultimoDoc) {
|
||
reabrirDocumento(ultimoDoc);
|
||
}
|
||
```
|
||
|
||
> **Atenção:** Não funciona em modo stateless (`WCMAPI.getIsStateless() === true`).
|
||
|
||
## Utilitários JavaScript
|
||
|
||
---
|
||
|
||
### Verificação de tipos
|
||
|
||
**Legado.** Prefira os recursos nativos do JavaScript moderno: `typeof`, `Array.isArray()`, `=== null`, `=== undefined`, etc. Evite utilizar estes métodos em novos desenvolvimentos.
|
||
|
||
| | | |
|
||
| --- | --- | --- |
|
||
| Método | Equivalente nativo | Retorno |
|
||
| `isUndefined(o)` | `o === undefined` | `boolean` |
|
||
| `isNull(o)` | `o === null` | `boolean` |
|
||
| `isString(o)` | `typeof o === 'string'` | `boolean` |
|
||
| `isNumber(o)` | `typeof o === 'number'` | `boolean` |
|
||
| `isArray(obj)` | `Array.isArray(obj)` | `boolean` |
|
||
| `isObject(o)` | — | `boolean` |
|
||
| `isJSON(o)` | — | `boolean` |
|
||
| `isEmpty(o)` | — | `boolean` |
|
||
|
||
```
|
||
// Antes de serializar dados para envio ao servidor:
|
||
const payload = obterDados();
|
||
if (WCMAPI.isObject(payload)) {
|
||
WCMAPI.Create({ url: '/api/salvar', data: payload, success: cb });
|
||
} else {
|
||
console.error('Dados inválidos:', payload);
|
||
}
|
||
```
|
||
|
||
### cloneObject(source)
|
||
|
||
**Descrição:** Cria uma cópia profunda (deep clone) de um objeto ou array simples. Não copia propriedades chamadas `'clone'` para evitar referências circulares.
|
||
**Limitação:** Não clona corretamente `Date`, `RegExp`, `Map`, `Set` ou outras classes built-in complexas — esses são copiados por referência.
|
||
**Parâmetros:**
|
||
|
||
- `source` (`Object|Array`): objeto ou array a clonar
|
||
|
||
**Retorno:** `Object|Array`
|
||
|
||
```
|
||
const configuracaoOriginal = { cor: 'azul', icone: { nome: 'star', tamanho: 16 } };
|
||
const copia = WCMAPI.cloneObject(configuracaoOriginal);
|
||
copia.icone.tamanho = 32;
|
||
console.log(configuracaoOriginal.icone.tamanho); // 16 — intocado
|
||
```
|
||
|
||
### replaceAll(str, de, para)
|
||
|
||
**Descrição:** Substitui todas as ocorrências de uma substring por outra. Alternativa a `String.prototype.replaceAll()` para compatibilidade com ambientes legados. Usa abordagem iterativa em vez de regex global, evitando problemas com caracteres especiais.
|
||
|
||
```
|
||
var resultado = WCMAPI.replaceAll('a.b.c.d', '.', '/');
|
||
// 'a/b/c/d'
|
||
```
|
||
|
||
### stringify(o)
|
||
|
||
**Descrição:** Serializa para JSON e então aplica `encodeURI()`. Útil para passar objetos complexos como parâmetros de URL.
|
||
|
||
```
|
||
const dados = { filtro: 'ativo', pagina: 1 };
|
||
const url = `/minha-api?params=${WCMAPI.stringify(dados)}`;
|
||
```
|
||
|
||
### validateXSS(data, replace)
|
||
|
||
**Descrição:** Sanitiza um valor de string ou campo de formulário contra ataques XSS usando o utilitário `FLUIGC.utilities.preventXSS`.
|
||
Suporta dois modos:
|
||
|
||
- **String:** recebe e retorna uma string sanitizada
|
||
- **Elemento de formulário:** recebe um elemento DOM ou jQuery com `.value`, atualiza o valor no lugar e retorna o objeto jQuery
|
||
- O parâmetro `replace` quando `true` também remove as entidades `>` e `<` do resultado sanitizado.
|
||
|
||
```
|
||
// Modo string — sanitizar dados antes de exibir
|
||
var textoSeguro = WCMAPI.validateXSS(comentarioDoUsuario, false);
|
||
$('#area-comentario').text(textoSeguro);
|
||
// Modo input — sanitizar o campo diretamente ao perder o foco
|
||
$('#campo-titulo').on('blur', function() {
|
||
WCMAPI.validateXSS(this, false);
|
||
});
|
||
```
|
||
|
||
### emailIsValid(email)
|
||
|
||
**Descrição:** Valida se uma string é um endereço de e-mail sintaticamente válido. Não verifica a existência do domínio.
|
||
**Retorno:** `boolean`
|
||
|
||
```
|
||
const email = $('#campo-email').val();
|
||
if (!WCMAPI.emailIsValid(email)) {
|
||
mostrarErro('Informe um e-mail válido.');
|
||
return;
|
||
}
|
||
```
|
||
|
||
### formatDateUtc(date)
|
||
|
||
**Descrição:** Formata uma data como string localizada usando a meia-noite UTC para evitar que o deslocamento de fuso horário do cliente altere o dia exibido.
|
||
**Parâmetros:**
|
||
|
||
- `date` (`string|number|Date`): valor de data aceito por `new Date()`
|
||
|
||
**Retorno:** `string` — data formatada conforme o locale do navegador
|
||
|
||
```
|
||
// Em pt-BR: '15/06/2024'
|
||
var dataFormatada = WCMAPI.formatDateUtc('2024-06-15T00:00:00Z');
|
||
$('#data-publicacao').text(dataFormatada);
|
||
```
|
||
|
||
### generateId()
|
||
|
||
**Descrição:** Gera uma string de identificador DOM único e incremental no formato `'wcmid<n>'`. Útil ao criar elementos dinamicamente que precisam de um atributo `id` garantidamente único na página.
|
||
**Retorno:** `string` — ex.: `'wcmid2'`, `'wcmid3'`, ...
|
||
|
||
```
|
||
const id = WCMAPI.generateId();
|
||
const $div = $('<div>').attr('id', id).addClass('meu-componente');
|
||
$('body').append($div);
|
||
WCMAPI.loadJS('/meuapp/componente.js', () => {
|
||
new MeuComponente({ target: `#${id}` });
|
||
});
|
||
```
|
||
|
||
### getZIndex()
|
||
|
||
**Descrição:** Retorna o maior valor de `z-index` em uso por elementos absolutamente ou fixamente posicionados na página. Útil ao criar modais ou overlays que precisam aparecer acima de todo o conteúdo existente.
|
||
**Retorno:** `number` — mínimo `1`
|
||
|
||
```
|
||
const $meuModal = $('#meu-modal');
|
||
$meuModal.css('z-index', WCMAPI.getZIndex() + 10);
|
||
$meuModal.show();
|
||
```
|
||
|
||
### getSourceImage(imageSource, options, callback)
|
||
|
||
**Descrição:** Carrega uma imagem e corrige sua orientação com base nos metadados EXIF, entregando uma URL de dados (Base64) ao callback quando necessário. Se a imagem não tiver dados EXIF de orientação, a URL original é retornada sem processamento.
|
||
Requer a biblioteca `blueimp-load-image` carregada na página.
|
||
**Parâmetros:**
|
||
|
||
- `imageSource` (`string`): URL ou data URL da imagem
|
||
- `options` (`Object`): opções para `loadImage()`, ex.: {{
|
||
Unknown macro: { maxWidth}}}
|
||
- `callback` (`Function`): `callback(src)` onde `src` é a URL original ou o Base64 corrigido
|
||
|
||
```
|
||
WCMAPI.getSourceImage('/uploads/foto.jpg', { maxWidth: 400 }, function(src) {
|
||
$('img.foto-perfil').attr('src', src);
|
||
});
|
||
```
|
||
|
||
## Utilitários de URL
|
||
|
||
---
|
||
|
||
### \_get(name)
|
||
|
||
**Descrição:** Extrai o valor de um parâmetro de query string da URL da página atual. Retorna `null` quando o parâmetro não está presente.
|
||
|
||
```
|
||
// URL: https://exemplo.com/pagina?filtro=ativo&pagina=2
|
||
var filtro = WCMAPI._get('filtro'); // 'ativo'
|
||
var pagina = WCMAPI._get('pagina'); // '2'
|
||
var outro = WCMAPI._get('outro'); // null
|
||
```
|
||
|
||
### \_getParam(url, name)
|
||
|
||
**Descrição:** Extrai o valor de um parâmetro de query string de uma URL específica (não da URL atual). Usado internamente para verificar parâmetros de versão antes de adicioná-los.
|
||
|
||
```
|
||
var versao = WCMAPI._getParam('/recursos/script.js?v=1.7.1', 'v');
|
||
// '1.7.1'
|
||
```
|
||
|
||
### \_getAllParams(url)
|
||
|
||
**Descrição:** Extrai todos os parâmetros de uma URL e os retorna como objeto.
|
||
**Retorno:** `Object.<string, string>`
|
||
|
||
```
|
||
var params = WCMAPI._getAllParams('https://exemplo.com/p?a=1&b=hello');
|
||
// { a: '1', b: 'hello' }
|
||
```
|
||
|
||
### getURLParameter(name) *(função global)*
|
||
|
||
**Descrição:** Extrai o valor de um parâmetro da URL atual. Diferente de `WCMAPI._get()`, esta é uma **função global** (não método do WCMAPI).
|
||
|
||
> **Atenção:** Quando o parâmetro não existe, esta função retorna a **string** `'null'` (e não `null`). Prefira `WCMAPI._get()` em novo código para evitar comparações indevidas.
|
||
|
||
```
|
||
var modoEdicao = getURLParameter('edit');
|
||
// Se o parâmetro não existir: modoEdicao === 'null' (string!)
|
||
// Forma segura com WCMAPI._get():
|
||
var modoEdicao = WCMAPI._get('edit'); // null (tipo correto)
|
||
```
|
||
|
||
## Configurações Globais jQuery
|
||
|
||
---
|
||
|
||
### $.cachedScript(url, options)
|
||
|
||
**Descrição:** Extensão do jQuery que carrega um script com cache habilitado no navegador. Diferente do `$.getScript()` padrão (que desabilita o cache), este helper é essencial para performance em uma plataforma onde os mesmos scripts de widget podem ser solicitados em cada carregamento de página.
|
||
|
||
```
|
||
$.cachedScript('/wcm/recursos/js/minha-lib.js').done(function() {
|
||
// biblioteca disponível — instanciar componente
|
||
new MinhaLib({ target: '#app' });
|
||
});
|
||
```
|
||
|
||
## Namespace WCM
|
||
|
||
---
|
||
|
||
O objeto global `WCM` é um namespace legado mantido por compatibilidade retroativa. Ele expõe URLs de conveniência derivadas do contexto atual do `WCMAPI`.
|
||
|
||
```
|
||
// WCM.contextUrl — ex.: '/portal/wcm'
|
||
// WCM.restUrl — ex.: '/wcm/api/rest/wcm/'
|
||
$.get(WCM.restUrl + 'meu-endpoint', function(data) {
|
||
// ...
|
||
});
|
||
```
|
||
|
||
## Boas Práticas
|
||
|
||
---
|
||
|
||
### Use sempre getters e setters — nunca acesse propriedades diretamente
|
||
|
||
Todas as propriedades do `WCMAPI` devem ser acessadas e modificadas exclusivamente pelos métodos `get...()` e `set...()` correspondentes. O acesso direto às propriedades (ex.: `WCMAPI.userId`) é considerado **legado**, não está documentado como API pública e pode ser removido em versões futuras.
|
||
|
||
```
|
||
// ❌ Incorreto — acesso direto à propriedade (legado)
|
||
var id = WCMAPI.userId;
|
||
var login = WCMAPI.userLogin;
|
||
var tenant = WCMAPI.tenantCode;
|
||
// ✅ Correto — use sempre os métodos getter
|
||
var id = WCMAPI.getUserId();
|
||
var login = WCMAPI.getUserLogin();
|
||
var tenant = WCMAPI.getTenantCode();
|
||
// ✅ Correto — para modificar, use o setter
|
||
WCMAPI.setPageTitle('Minha Página Customizada');
|
||
```
|
||
|
||
### Use sempre o singleton `WCMAPI`
|
||
|
||
Nunca instancie `TLib` diretamente. O objeto `WCMAPI` é criado pela plataforma com uma guarda contra instanciação dupla.
|
||
|
||
```
|
||
// ✅ Correto
|
||
var login = WCMAPI.getUserLogin();
|
||
// ❌ Incorreto
|
||
var api = new TLib();
|
||
```
|
||
|
||
### Prefira `convertFtlAsync` ao `convertFtl`
|
||
|
||
A versão assíncrona não bloqueia a interface enquanto aguarda a resposta do servidor.
|
||
|
||
```
|
||
// ✅ Correto — não bloqueia o navegador
|
||
WCMAPI.convertFtlAsync('meuApp', 'view.ftl', params, function(html) {
|
||
$('#container').html(html);
|
||
WCMAPI.loadWidgets();
|
||
});
|
||
// Usar com cautela — bloqueia o navegador
|
||
var html = WCMAPI.convertFtl('meuApp', 'view.ftl', params);
|
||
```
|
||
|
||
### Sempre chame `loadWidgets()` após injetar HTML
|
||
|
||
Qualquer HTML que contenha elementos com a classe `wcm-widget-class` precisa que `loadWidgets()` seja chamado após a injeção para que os widgets sejam inicializados.
|
||
|
||
```
|
||
$('#container').html(htmlRenderizado);
|
||
WCMAPI.loadWidgets(); // não esqueça!
|
||
```
|
||
|
||
### Use nomes únicos para seus listeners de eventos
|
||
|
||
O sistema de eventos atualiza um listener existente quando o nome já está registrado. Nomes descritivos e únicos por widget evitam conflitos silenciosos.
|
||
|
||
```
|
||
// ✅ Nome específico para este widget
|
||
WCMAPI.addListener(this, WCMAPI.LISTENER_EDITMODEON, handler, 'widgetCalendario-editmode');
|
||
// ❌ Nome genérico pode conflitar com outros widgets
|
||
WCMAPI.addListener(this, WCMAPI.LISTENER_EDITMODEON, handler, 'meu-listener');
|
||
```
|
||
|
||
### Remova listeners ao destruir widgets
|
||
|
||
Para evitar memory leaks e comportamentos indesejados, remova os listeners ao destruir ou esconder um widget.
|
||
|
||
```
|
||
destroyWidget() {
|
||
WCMAPI.removeListener(WCMAPI.LISTENER_EDITMODEON, 'widgetCalendario-editmode');
|
||
WCMAPI.removeListener(WCMAPI.LISTENER_LOGOUT, 'widgetCalendario-logout');
|
||
// limpeza do DOM...
|
||
};
|
||
```
|
||
|
||
### Verifique o login antes de operações sensíveis
|
||
|
||
```
|
||
if (!WCMAPI.getUserIsLogged()) {
|
||
return;
|
||
}
|
||
const login = WCMAPI.getUserLogin();
|
||
```
|
||
|
||
### Sanitize inputs do usuário com `validateXSS`
|
||
|
||
Antes de inserir qualquer conteúdo gerado pelo usuário no DOM, sanitize-o:
|
||
|
||
```
|
||
var conteudo = WCMAPI.validateXSS($('#campo-descricao').val(), false);
|
||
$('#area-preview').html(conteudo);
|
||
```
|
||
|
||
## Erros Comuns
|
||
|
||
---
|
||
|
||
### "WCMAPI is not defined"
|
||
|
||
**Causa:** O script do widget está sendo executado antes do `wcmapi.js` ser carregado.
|
||
**Solução:** Verifique a ordem de carregamento dos recursos no template do widget ou tema. O `wcmapi.js` deve aparecer antes dos scripts dos widgets.
|
||
|
||
### Listener disparando múltiplas vezes
|
||
|
||
**Causa:** `addListener` está sendo chamado mais de uma vez com o nome `'DEFAULT'` (padrão quando `listenerName` não é informado), e cada chamada atualiza o listener existente — mas se diferentes widgets usam o mesmo nome, os callbacks podem se acumular.
|
||
**Solução:** Sempre informe um `listenerName` único e específico para seu widget.
|
||
|
||
### `getURLParameter` retornando `'null'` em vez de `null`
|
||
|
||
**Causa:** Esta função global retorna a string `'null'` quando o parâmetro não existe.
|
||
**Solução:** Use `WCMAPI._get()` que retorna o tipo nulo correto.
|
||
|
||
```
|
||
// ❌ Armadilha
|
||
if (getURLParameter('modo') == null) { /* nunca entra aqui */ }
|
||
// ✅ Correto
|
||
if (WCMAPI._get('modo') === null) { /* funciona */ }
|
||
```
|
||
|
||
### Widget não inicializa após injeção de HTML
|
||
|
||
**Causa:** `loadWidgets()` não foi chamado após a injeção do HTML.
|
||
**Solução:**
|
||
|
||
```
|
||
$('#container').html(htmlRenderizado);
|
||
WCMAPI.loadWidgets(); // essencial
|
||
```
|
||
|
||
### Sessão expirando mesmo com o usuário ativo
|
||
|
||
**Causa:** `extendSession()` não está sendo chamado em resposta às interações do usuário, ou o interceptor foi removido.
|
||
**Solução:** Vincule `extendSession()` aos eventos de interação de forma global no tema:
|
||
|
||
```
|
||
let timerSessao;
|
||
$(document).on('mousemove keydown click', () => {
|
||
clearTimeout(timerSessao);
|
||
timerSessao = setTimeout(() => WCMAPI.extendSession(), 500);
|
||
});
|
||
```
|
||
|
||
### Requisições AJAX falhando com 401 em modo stateless
|
||
|
||
**Causa:** O cookie `jwt.token` não está presente ou está expirado. O `$.ajaxSetup` global injeta o token automaticamente, mas ele precisa existir.
|
||
**Solução:** Verifique se o fluxo de autenticação está renovando o JWT corretamente. Em modo stateless (`WCMAPI.getIsStateless() === true`), toda autenticação depende do token JWT.
|
||
|
||
## Dicas de Performance
|
||
|
||
---
|
||
|
||
### Evite `isAdmin()` em loops ou na inicialização
|
||
|
||
`isAdmin()` faz uma chamada síncrona ao servidor. Guarde o resultado em cache:
|
||
|
||
```
|
||
const userAdmin = WCMAPI.isAdmin();
|
||
minhaLista.forEach((item) => {
|
||
if (ehAdmin) {
|
||
exibirBotaoExcluir(item);
|
||
}
|
||
});
|
||
```
|
||
|
||
### Prefira `convertFtlAsync` para templates pesados
|
||
|
||
Templates que carregam muitos dados ou recursos devem usar a versão assíncrona para não travar a interface enquanto o servidor processa.
|
||
|
||
### Use `WCMAPI.loadJS` para scripts de widgets, nunca `$.getScript`
|
||
|
||
`$.getScript` desabilita o cache do navegador. `WCMAPI.loadJS` usa `$.cachedScript` internamente, permitindo que o navegador faça cache dos scripts entre carregamentos de página.
|
||
|
||
### Use `WCMAPI._getParam` para verificar parâmetros de versão em URLs
|
||
|
||
Ao montar URLs para recursos externos, verifique se já existe um parâmetro `v` antes de adicionar:
|
||
|
||
```
|
||
const urlRecurso = '/meu-recurso/arquivo.js';
|
||
if (!WCMAPI._getParam(urlRecurso, 'v')) {
|
||
urlRecurso += `?v=${WCMAPI.getVersion()}`;
|
||
}
|
||
```
|
||
|
||
### Nomeie e remova listeners para evitar memory leaks
|
||
|
||
Em widgets com ciclo de vida bem definido (criação e destruição), sempre remova os listeners ao destruir o widget para liberar memória.
|
||
|
||
### Integração com outras APIs do Fluig
|
||
|
||
O `WCMAPI` é a **porta de entrada** — use-o para obter o contexto e, a partir dele, construa chamadas para:
|
||
|
||
- **REST API pública:** `/api/public/2.0/...` — use `WCMAPI.Read()` / `WCMAPI.Create()` etc.
|
||
- **WCMSpaceAPI:** API síncrona de baixo nível (use com cautela)
|
||
- **FLUIGC:** componentes visuais do guia de estilo Fluig
|
||
- **WCMSpaceAPI.OAuthService:** para integrações OAuth, utilize os helpers `validateOAuth` e `validateAndAuthenticateOAuth` do próprio `WCMAPI` |