Criar Plugin Localmente

Nesta seção, você encontra um tutorial de como Criar um Plugin v3 localmente.

Atenção!

Este tutorial foi criado utilizando Plugins na versão 3.

Objetivo

Este tutorial tem o objetivo de orientar a criação, teste local e publicação de Plugins na StackSpot. E ajudar você a entender como criar conteúdo na StackSpot.

Os Plugins que serão utilizados como exemplos:

Geram uma página HTML e adicionam tabelas a ela.

Nível: Iniciante.

Informação Adicional

Este exemplo é uma das possibilidades de criar e publicar plugins localmente. Por isso, não é necessário estar dentro de um Estúdio.

A seguir, confira o resumo dos passos:

Criar Plugin A, base que gera página HTML com header e título customizável por input.
Testar Plugin A.
Criar Plugin B que integra uma tabela com dados de produto da API - DummyJson Products
Testar Plugin B.
Publicar os Plugins no Estúdio.

Pré Requisitos

Você deve estar logado(a) na sua conta StackSpot.
STK CLI instalado

Cuidado!

Esta jornada é feita usando somente o STK CLI, pois é um tutorial de criação de Plugins na sua máquina local.

Passo 1. Criar um diretório vazio

É onde o seu projeto irá ficar. No seu terminal, execute o comando:

mkdir test-html

Acesse o diretório utilizando a sua IDE de costume. Execute o comando:

cd test-html

Passo 2. Criar Plugin A

O Plugin A gera uma página HTML com header e título customizável por input.

Ainda na sua IDE, dentro do diretório criado, execute o comando:

stk create plugin base-html-plugin

Responda as perguntas no seu terminal. Siga o modelo:

Plugin type (tipo do Plugin): app
Add repository: no. A resposta aqui é não. Neste tutorial você irá criar Plugins somente no seu ambiente local.
Version (número da versão): 0.0.1
Plugin description (descrição do Plugin): Plugin para gerar um projeto base HTML
Required connection interfaces: não selecione nenhuma Connection Interface, apenas aperte Enter.

Pronto, você criou o Plugin A.

Uma estrutura de pastas foi criada dentro do diretório. Confira na imagem, a estrutura padrão de um Plugin StackSpot:

Captura de tela do Visual Studio Code mostrando a estrutura de pastas do Plugin A. A pasta principal é base-html-plugin, que contém a subpasta docs com arquivos .md como about.md, implementation.md, markdown-guide.md, release-notes-version.md e requirements.md. Há a pasta templates e, por último, o arquivo plugin.yaml

Passo 3. Personalizar conteúdo do Plugin A

Agora, complete as informações do Plugin para que ele funcione como a base HTML. Para isso, é necessário um repositório, neste caso utilize um já criado pela StackSpot. Clone o repositório executando o comando:

git clone https://github.com/stack-spot/demo-html-plugins.git

Ele contém as seguintes pastas:

Estrutura de pastas do repositório clonado. Nome das pastas demo-html-plugins>base-html-plugin>dummy-json-plugin. Arquivo LICENSE e README.md

Abra a pasta base-html-plugin e em seguida entre em templates. Confira na imagem:

Pasta de templates aberta. Os arquivos são: css, js, pasta resource, index.html, plugin.yaml.

Siga as instruções:

Copie toda a estrutura de arquivos dentro dessa pasta.
Volte para a pasta base-html-plugin que você criou no Passo 2. Acesse a pasta Templates, apague o arquivo README e cole o conteúdo que você acabou de copiar.

A pasta deve ficar como na imagem:

Pasta de templates copiada para Plugin A. A estrutura da pasta base-html-plugin é: docs, templates com css, js, resource, index.html e plugin.yaml

Para personalizar sua página HTML, acesse o arquivo plugin.yaml e apague o conteúdo Inputs e copie e cole o código:

 inputs:
    - label: Titulo da página HTML
      name: title
      type: text
      required: true
      default: Treinamento - StackSpot
      help: 'Informe o título da página HTML que será gerada'

Assim como no GIF:

Substituição de inputs no Plugin A. Copiar e colar a parte do código mencionado anteriormente

Pronto, você personalizou seu Plugin A.

Passo 4. Aplicar Plugin A

Agora você deve aplicar seu Plugin para testá-lo, confira:

Crie um diretório vazio dentro do mesmo diretório criado no Passo 1. (test-html). Este será a pasta onde sua página HTML será gerada após aplicar os Plugins.

Execute o comando:

mkdir example-project

Acesse o novo diretório, execute o comando:

cd example-project

Aplique o Plugin A para gerar a página base. Para isso, execute o comando com o caminho absoluto do diretório do Plugin A:

stk apply plugin <caminho_do_diretorio_absoluto_pluginA>

Informação Adicional

Confira um exemplo de caminho absoluto do diretório:

/Users/username/test-html/base-html-plugin

Dentro do diretório example-project que você criou, confira a estrutura de pastas como na imagem:

Teste Plugin A. A estrutura dentro do diretório com a pasta example-project e dentro com .stk, css, js, resource e index.html

Pronto, você já pode visualizar a base da sua página HTML acessando o diretório acima no seu computador. Por exemplo, no Mac, acessando pelo Finder; no Windows, pelo Windows Explorer.

Passo 5. Criar Plugin B

O Plugin B que integra uma tabela com dados de produto da API - DummyJson Products. E também:

Habilita customização de colunas exibidas na tabela; e
Utiliza hooks para manipulação de arquivos utilizando snippets.

Siga as instruções para criar o Plugin B:

Em um terminal ainda dentro da IDE, continue dentro do diretório criado no Passo 1. (test-html) e execute o comando:

stk create plugin dummy-json-plugin

Responda as seguintes perguntas no seu terminal:

Plugin type (tipo do Plugin): app.
Add repository: no. A resposta aqui é não. Neste tutorial você irá criar somente no seu ambiente local.
Version (número da versão): 0.0.1.
Plugin description (descrição do Plugin): Plugin para integrar uma tabela de dados na base HTML.
Required connection interfaces: Não selecione nenhuma Connection Interface, apenas aperte Enter.

Pronto, você criou o Plugin B.

Confira a estrutura de pastas criada dentro do diretório. Esta é a estrutura padrão de um Plugin StackSpot. Confira na imagem:

Estrutura de Pastas Plugin B. A estrutura da pasta dummy-json-plugin. A pasta docs possui arquivos .md about.md, implementation.md, markdown-guide.md, release-notes-0.01.md, requirements.md. A pasta templates tem os arquivos README.md e plugin.yaml.

Passo 6. Personalizar conteúdo do Plugin B

Complete as informações do Plugin para que ele funcione. Agora, utilize o repositório criado pela StackSpot que você já clonou no Passo 3., o demo-html-plugins.

Copie dois conteúdos deste arquivo:

A pasta inteira chamada Snippets; e
O conteúdo da pasta Templates.

Conteúdos para copiar do Demo HTML completo. Está destacado na imagem com um quadrado vermelho o que você precisa copiar. A pasta snippets e os arquivos css e js

E depois cole o conteúdo dentro da pasta do Plugin B, dummy-json-plugin. E você deve apagar o arquivo README que existe dentro da pasta Templates.

A pasta deve ficar como na imagem:

Plugin B pasta templates. Depois de copiar a pasta snippets fica com os arquivos: import-css.txt, import-js.txt, table.txt. E a pasta templates com o css e js.

Por fim, configure o arquivo plugin.yaml e adicione hooks ao Plugin. Cole o código na seção inputs:

 inputs:
    - label: Nome da tabela que será gerada
      name: table_id
      type: text
      required: true
      default: product-list
      help: 'Informe o nome da tabela que será gerada na página HTML'
    - label: Colunas da tabela separado por ';'
      name: column_list
      type: text
      default: ID;TÍTULO;DESCRIÇÃO
      required: true
      help: 'Informe quantidade de colunas da tabela que será gerada'
    - label: Atributos da tabela separado por ';' (respectivamente do inserido nas colunas)
      name: attr_list
      type: text
      default: id;title;description
      required: true
      help: 'Informe os atributos das colunas na mesma ordem que inserido no campo column_list'
  hooks:
    - type: edit
      trigger: before-render
      path: index.html
      changes:
        - search:
            string: "</body>"
            insert-before:
              snippet: snippets/table.txt
            when:
              not-exists: "<table id=\"{{table_id}}\">"
    - type: edit
      trigger: before-render
      path: index.html
      changes:
        - search:
            string: "</html>"
            insert-before:
              snippet: snippets/import-js.txt
            when:
              not-exists: "./js/{{table_id}}Action.js"
    - type: edit
      trigger: before-render
      path: index.html
      changes:
        - search:
            string: "</head>"
            insert-before:
              snippet: snippets/import-css.txt
            when:
              not-exists: "css/ListProducts.css"

Pronto, você customizou seu Plugin B.

Passo 7. Aplicar Plugin B

Aplique o Plugin B para gerar a tabela de requisição. Você deve aplicá-lo no mesmo diretório criado no Passo 1.

Siga as instruções:

Acesse o diretório criado no Passo 4, execute o comando:

cd example-project

Execute o comando com o caminho absoluto do diretório do Plugin B:

stk apply plugin <caminho_do_diretorio_absoluto_pluginB>

Coloque o caminhos sem as chaves.

informação

Confira um exemplo de caminho absoluto do diretório:

/Users/username/test-html/dummy-json-plugin

Coloque o caminho sem as chaves.

Então responda as perguntas no terminal:

? Nome da tabela que será gerada (product-list): .
? Colunas da tabela separado por ';' (ID;TÍTULO;DESCRIÇÃO): .
? Atributos da tabela separado por ';' (respectivamente do inserido nas colunas) (id;title;description): aperte Enter.

Após responder as perguntas o output deve ser:

Plugin <caminho_do_diretorio_absoluto_pluginB> aplicado.

Pronto, você já pode visualizar a sua página HTML atualizada com a tabela.

Informação Adicional

O resultado final (depois da aplicação dos Plugins) fica no diretório do projeto gerado, neste caso, no example-project. Nesse projeto, você encontra um arquivo index.html que é possível abrir no navegador pra verificar o resultado da aplicação dos Plugins.

Para acessá-lo, entre no diretório por meio do seu computador. Se for um MAC, por exemplo, seria pelo Finder; se for um Windows, pelo Windows Explorer.

O resultado da sua página deve ser igual à imagem:

Página HTML gerada. A pasta possui uma tabela com 3 colunas. O título é Treinamento StackSpot. A primeira coluna é o ID, a segunda Título e a terceira Descrição.

Agora que você criou e aplicou os Plugins localmente, a próxima etapa é Publicá-los.

Passo 8. Publicar os Plugins

Todo o processo até aqui foi feito localmente. Ao publicar o seu Plugin, você permite que outras pessoas possam utilizá-lo no Portal.

Pré requisitos

Criar um Estúdio, caso tenha permissão; ou
Estar dentro de um estúdio.

Você deve publicar primeiro o Plugin A e depois o Plugin B.

Acesse o diretório raiz do Plugin A e execute o comando:

stk publish plugin --studio studio-slug-name

Na StackSpot, os Slugs são identificadores únicos para as Contas, Estúdio, Stacks e Plugins e compõem as URLs da StackSpot.

Agora, acesse o diretório do Plugin B e execute o mesmo comando acima.

Pronto, você publicou o Plugin A e o Plugin B e pode encontrá-lo no seu Estúdio.