Criar Extensões Customizáveis

Nesta seção, você encontra os passos para criar Extensões Customizáveis.

Introdução

No contexto da StackSpot, uma Extensão Customizável permite criar uma nova página dentro do Portal da StackSpot EDP. Para isso, a Plataforma oferece um SDK que possibilita o desenvolvimento de páginas personalizadas, totalmente integradas ao ambiente da StackSpot EDP.

A Extensão facilita a integração com outras ferramentas, oferecendo uma experiência centralizada e personalizada para as pessoas desenvolvedoras.

Atenção!

Toda a implementação e gerenciamento da Extensão é de total responsabilidade do cliente.
Se uma Extensão apresentar um incidente de segurança identificado pela StackSpot, ela poderá ser desativada a qualquer momento.

Uma Extensão Customizável pode ser criada em dois níveis:

Organização: todo mundo que faz parte de uma Conta poderá visualizar a Extensão cadastrada.

Workspace: a Extensão será publicada em todos os Workspaces.

A pessoa responsável pela Organização deve criar e publicar uma Extensão no Portal da StackSpot. Depois disso, a Extensão ficará disponível no menu principal da Organização ou no menu do Workspace, e poderá ser usada.

Pré-requisito

Bibliotecas Necessárias

Para construir uma Extensão StackSpot, é preciso ter as bibliotecas a seguir:

React
Citric: design System da StackSpot.
Portal Theme: tema para o Design System.
Portal Translate: mecanismo de internacionalização.
React Query: gerenciador de estado de rede global.
Styled Components: para estilizar componentes.

Informação Adicional

As bibliotecas Portal Translate, React Query e Styled Components devem estar incluídas no projeto, mas o uso delas é opcional.

Bibliotecas Recomendadas

Navegador Citron: se a sua extensão tiver várias páginas, use o navegador Citron Navigator, um navegador desenvolvido internamente para React.
Componentes do Portal: um conjunto de componentes utilizados por todos os Portais da StackSpot construídos sobre o Citric. Utilize-o apenas se precisar de alguns dos componentes desta biblioteca.

Instalar o SDK

A Extensão é uma Aplicação React com Typescript que executa como uma client application ou client-side (executada no navegador da pessoa usuária).

A Extensão pode interagir com a API da StackSpot para recuperar algumas informações da sua conta StackSpot EDP ou qualquer serviço, desde que você forneça a autenticação necessária.

Para criar o projeto, instale o STK da StackSpot @stack-spot/portal-extension:

No seu terminal, execute o comando a seguir:

pnpm (recomendado)

Instalação recomendada
pnpm add @stack-spot/portal-extension

npm ou yarn

npm i @stack-spot/portal-extension

yarn add @stack-spot/portal-extension

A StackSpot disponibiliza um exemplo do projeto de uma Extensão.

Uso do SDK

Expor o seu projeto como Extensão

Para utilizar a sua Aplicação na StackSpot, você deve expor o projeto como uma Extensão da StackSpot. Para isso, configure o arquivo de ponto de entrada da sua Aplicação como no exemplo a seguir. (Exemplo: App.tsx):

App.tsx
import { StackspotExtension } from '@stack-spot/portal-extension'

export const App = () => (
  <StackspotExtension>
    {/* Your content goes here */}
  </StackspotExtension>
)

Atenção!

É preciso ter a permissão de criação de Extensão, disponível para Account Holders e Account Admins.

No exemplo a seguir, modais e painéis à direita carregam outras visualizações desta mesma Aplicação. Para ter múltiplas visualizações, use o React Navigator (Navegador Citron).

import { StackspotExtension } from '@stack-spot/portal-extension'
import { Button } from '@citric/core'
import { alert, confirm, showModal, showRightPanel } from '@stack-spot/portal-extension'
export const App = () => (
  <StackspotExtension>
    <Button
      onClick={() => alert({
        title: 'Alert',
        subtitle: 'This is an alert!',
      })}
    >
      Show alert
    </Button>
    <Button
      onClick={async () => {
        const answer = await confirm({
          title: 'Confirm',
          subtitle: 'Do you confirm?',
        })
        console.log(answer ? 'confirmed' : 'canceled')
      }}
    >
      Show confirm
    </Button>
    <Button
      onClick={() => showModal({
        title: 'My modal',
        subtitle: 'This is an example of modal',
        path: '/path-to-modal',
      })}
    >
      Show modal
    </Button>
    <Button
      onClick={() => showRightPanel({
        title: 'Meu painel',
        subtitle: 'This is an example of right panel',
        path: '/path-to-right-panel',
      })}
    >
      Show floating side panel on the right
    </Button>
  </StackspotExtension>
)

Exibir toasters

import { StackspotExtension } from '@stack-spot/portal-extension'
import { Button } from '@citric/core'
import { showToaster } from '@stack-spot/portal-extension'

export const App = () => (
  <StackspotExtension>
    <Button onClick={() => showToaster({ message: 'Hello World' })}>
      Show an info toast
    </Button>
    <Button onClick={() => showToaster({ message: 'Oops! An error.', type: 'error' })}>
      Show an error toast
    </Button>
  </StackspotExtension>
)

Criar menus de contexto

A partir da Extensão, você pode criar um menu contextual para sua página.

Atenção!

Confira as limitações do menu:

O menu de seções (menu principal) não pode ser alterado por uma Extensão.
O menu é representado por um objeto de template predefinido, ou seja, o usuário não é livre para criar o que quiser. Ele deve seguir uma estrutura bem definida.
Somente Extensões de página inteira podem alterar o menu, por exemplo, se a Extensão for carregada como um widget pelo pai, o menu contextual não será exibido.

Para criar o menu, use o showMenu(options). Confira o exemplo a seguir:

import { showMenu } from '@stack-spot/portal-extension'
import { root } from 'navigation'

showMenu({
  options: [
    {
      label: 'Loja Digital',
      children: [
        { label: 'Início', href: root.$link(), active: true },
        { label: 'Problemas', href: root.issues.$link() },
        { label: 'Gerenciamento', href: root.management.$link() },
      ]
    },
    {
      label: 'Links Externos',
      open: false,
      children: [
        { label: 'Stackspot', href: 'https://www.stackspot.com', target: '_blank' },
        { label: 'Zup', href: 'https://www.zup.com.br', target: '_blank' },
        { label: 'Google', href: 'https://www.google.com', target: '_blank' },
        { label: 'Microsoft', href: 'https://www.microsoft.com' },
        { label: 'Apple', href: 'https://www.apple.com' },
      ]
    },
  ]
})

O menu contextual suporta um conjunto de funcionalidades. Confira o tipo MenuSectionContent em suas definições de tipo para mais detalhes.

Uma vez exibido, o menu só muda se showMenu for chamado novamente com outro valor. O menu desaparece se o usuário sair da página da Extensão ou se você chamar explicitamente closeMenu().

Executar requisições para a API da StackSpot

A Extensão do Portal não tem acesso ao token de acesso do usuário e não pode fazer requisições diretas para a API da StackSpot. Em vez disso, você deve importar um cliente de rede do SDK e utilizá-lo.

Para mais informações sobre o uso da API, recuperação dos dados de usuários logados na StackSpot e pré-visualização da Extensão, acesse a página do SDK.

Criar Extensão no Portal

Passo 1. Acesse o Portal de Conta da StackSpot e, em seguida, clique no menu ’Organização’;

Passo 2. Na seção ’StackSpot EDP’, acesse a subseção ’Extensões’;

Passo 3. Clique no botão ’Criar extensões';

Passo 4. Preencha os campos a seguir:

Nome

Um slug é sugerido quando o campo de nome é preenchido. Se quiser alterar o slug, clique no botão ’Editar'.

Nível: escolha entre Organização ou Workspace.
Descrição: é um campo opcional.
Arquivo: faça upload, em formato zip, do arquivo que será a sua Extensão.

Esse arquivo passará por um processo de varredura de segurança. Se ele não estiver dentro da política de segurança, ele pode ser excluído.

Passo 5. Clique no botão ’Criar’.

A imagem está em inglês.

Pronto, sua Extensão foi criada. Agora você precisa ativá-la.

Ativar ou desativar uma Extensão

Ativar uma Extensão

Para ativar uma Extensão, siga os passos a seguir:

Passo 1. Na linha da Extensão que você criou e quer ativar, clique no ícone que indica mais opções;

Passo 2. Clique no botão ’Ativar'.

A imagem está em inglês.

Pronto, você ativou uma Extensão. Agora ela pode ser usada na StackSpot.

Desativar um Extensão

Para desativar uma Extensão, siga os passos a seguir:

Passo 1. Na linha da Extensão que você quer desativar, clique no ícone que indica mais opções;

Passo 2. Clique no botão ’Desativar'.

Pronto, você desativou uma Extensão.

Editar uma Extensão

Você pode editar uma Extensão enquanto ela está ativa, mas o slug não pode ser alterado. Para editar, siga os passos a seguir:

Passo 1. Na linha da Extensão que você quer editar, clique no ícone que indica mais opções;

Passo 2. Clique no botão ’Editar’;

Passo 3. Em ’Editar extensão’, edite um ou mais campos:

Nome
Nível
Descrição
Substituir arquivo

Passo 4. Para concluir a edição, clique no botão ’Editar';

A imagem está em inglês.

Pronto, você editou uma Extensão.

Remover uma Extensão

É possível remover uma Extensão, mas todas as versões dela também serão removidas da StackSpot EDP. Para isso, siga os passos a seguir:

Passo 1. Na linha da Extensão que você quer remover, clique no ícone que indica mais opções;

Passo 2. Para confirmar a remoção, clique no botão ’OK'.

A imagem está em inglês.

Pronto, você removeu uma Extensão do Portal.

Introdução

Pré-requisito

Bibliotecas Necessárias

Bibliotecas Recomendadas

Instalar o SDK

Uso do SDK

Expor o seu projeto como Extensão

Exibir conteúdo de Modal

Exibir toasters

Criar menus de contexto

Executar requisições para a API da StackSpot

Criar Extensão no Portal

Ativar ou desativar uma Extensão

Ativar uma Extensão

Desativar um Extensão

Editar uma Extensão

Remover uma Extensão