Pular para o conteúdo principal

Criar Plugins e Stack de App

Nesta seção, você encontra como iniciar a criação de conteúdo na StackSpot.


Introdução

  • Nível Intermediário

Este documento apresenta um exemplo prático de criação de Plugins na StackSpot. Para mais detalhes sobre o processo, acesse a documentação completa sobre Plugins.

Este guia tem como objetivo orientar a criação, teste local e publicação de Plugins, bem como a criação de uma Stack e um Starter na StackSpot.

O exemplo aborda a criação e publicação de dois Plugins:

  • Um Plugin que gera uma página HTML com um header e título customizável via input.
  • Um Plugin que integra uma tabela com dados da API DummyJson Products.

Na sequência, é demonstrado como criar e publicar uma Stack e um Starter utilizando os Plugins criados.

Antes de começar

Principais etapas:

  1. Criar um Plugin
  2. Criar uma Stack e adicionar Plugins
  3. Criar um Starter

Pré-requisitos

Resumo dos passos para criar um Plugin:

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

1. Criar Plugin

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.

  1. Ainda na sua IDE, dentro do diretório criado, execute o comando:
stk create plugin base-html-plugin
  1. Responda as perguntas no seu terminal. Siga o modelo:
  • ? Nomeie seu plugin: base-html-plugin
  • ? Você deseja iniciar um repositório git?: no
  • ? Adicionar remote?: no
  • ? Descrição do plugin: (Descreva seu plugin explicando o propósito) Plugin para gerar um projeto base HTML
  • ? Versão: (0.0.1)
  • ? Selecione o tipo de plugin: app
  • ? Você gostaria de adicionar uma Connection Requerida? no e aperte Enter.

Pronto, você criou o Plugin A. Uma estrutura de pastas foi criada dentro do diretório. Confira, a estrutura de pastas de um Plugin StackSpot:

/test-html
├── base-html-plugin
│   ├── docs
│   │   ├── en-us
│   │   │   └── docs.md
│   │   └── pt-br
│   │       └── docs.md
│   ├── plugin.yaml
Informação adicional

Neste exemplo, não é utilizado as pastas test. Por isso, elas não aparecem no snippet de código acima.

Passo 3. Editar o conteúdo do Plugin A

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 executando o comando:

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

Ele contém as seguintes pastas:

/demo-html-plugins
├── demo-html-plugins
│   ├── LICENSE
│   ├── README.md
│   ├── base-html-plugin
│   │   ├── plugin.yaml
│   │   └── templates
│   └── dummy-json-plugin
  • Abra a pasta base-html-plugin e em seguida entre em templates. Confira:
/demo-html-plugins
── base-html-plugin
│   ├── docs
│   │   ├── en-us
│   │   │   └── docs.md
│   │   └── pt-br
│   │       └── docs.md
│   ├── plugin.yaml
│   ├── templates
│   │   ├── README.md
│   │   ├── css
│   │   │   └── index.css
│   │   ├── index.html
│   │   ├── js
│   │   │   └── jquery-3.6.4.min.js
│   │   └── resource
│   │       └── stackspot-logo.svg
│   └── tests
│       └── test-case-apply-00
│           ├── expected
│           │   └── README.md
│           ├── target
│           └── test-case.yaml
├── demo-html-plugins

Siga as instruções:

  1. Copie os conteúdos (todos os arquivos e pastas) dentro da pasta templates (do repositório que você clonou) e clique na pasta templates do Plugin A.

A pasta deve conter:

/test-html
── base-html-plugin
│   ├── docs
│   │   ├── en-us
│   │   │   └── docs.md
│   │   └── pt-br
│   │       └── docs.md
│   ├── plugin.yaml
│   ├── templates
│   │   ├── README.md
│   │   ├── css
│   │   │   └── index.css
│   │   ├── index.html
│   │   ├── js
│   │   │   └── jquery-3.6.4.min.js
│   │   └── resource
│   │       └── stackspot-logo.svg
│   └── index.html
  1. No arquivo plugin.yaml: edite a sua página HTML. Substitua o conteúdo a partir de Inputs com o código:
inputs:
   - label: HTML page title
     name: title
     type: text
     required: true
     default: Training - StackSpot
     help: 'Inform the title of the HTML page generated'

Passo 4. Aplicar o Plugin A localmente

Aplique o seu Plugin para testá-lo de forma local, siga as instruções:

  1. Crie um diretório vazio dentro do mesmo diretório criado no Passo 1 (teste-html).

Essa será a pasta onde sua página HTML será gerada após aplicar os Plugins.


Execute os comandos:

mkdir example-project

Acesse o novo diretório, execute o comando:

cd example-project
  1. Aplique o Plugin A para gerar a página base. Execute o comando com o caminho absoluto do diretório do Plugin A.
stk apply plugin <directory_path_pluginA>

Confira um exemplo de caminho absoluto do diretório:

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

Atenção!

Em caso de erro:

  • Verifique se o caminho do diretório que você utilizou está correto; ou
  • Você não pode estar dentro de um Workspace ao executar este comando. Caso esteja, execute o comando stk exit workspace para sair e teste o comando novamente.

  1. Responda "Sim" (Y) para a pergunta no STK CLI:

? A pasta corrente não faz parte de um projeto StackSpot. Você deseja continuar aplicando o plugin assim mesmo? (Y/n)

  1. Dentro do diretório example-project que você criou, confira a estrutura de pastas:
/example-project
├── example-project
│   ├── .stk
│   ├── css
│   ├── js
│   ├── resource
│   ├── plugin.yaml
├── stackspot-logo.svg
├── index.html

Agora 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 o 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:

No seu terminal dentro da IDE, acesse o diretório test-html, e execute o comando:

stk create plugin dummy-json-plugin
  1. Responda as seguintes perguntas no seu terminal:

  • ? Você deseja iniciar um repositório git?: no
  • ? Adicionar remote?: A resposta é não. Neste exemplo você irá criar somente no seu ambiente local.
  • ? Descrição do plugin: (Descreva seu plugin explicando o propósito) Plugin para integrar uma tabela de dados na base HTML.
  • ? Versão: (0.0.1)
  • ? Selecione o tipo de plugin: app
  • ? Você gostaria de adicionar uma Connection Requerida? no e aperte Enter.

Passo 6. Editar o conteúdo do Plugin B

Complete as informações do Plugin para que ele funcione. Utilize o repositório criado pela StackSpot que você já clonou the demo-html-plugins.

  1. Copie dois conteúdos deste arquivo:
  • A pasta inteira chamada Snippets; e
  • O conteúdo da pasta Templates.
├── demo-html-plugins
│   ├── LICENSE
│   ├── README.md
│   ├── base-html-plugin
│   │   ├── plugin.yaml
│   │   └── templates
│   └── dummy-json-plugin
│       ├── plugin.yaml
│       ├── snippets
│       │   ├── import-css.txt
│       │   ├── import-js.txt
│       │   └── table.txt
│       └── templates
│           ├── css
│           │   └── ListProducts.css
│           └── js
│               └── {{table_id}}Action.js
  1. 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.
Atenção!

Só deve existir uma única pasta de Templates dentro do seu Plugin.


  1. Configure o arquivo plugin.yaml e adicione hooks ao Plugin. Cole o código a partir de inputs:
  inputs:
    - label: Name of the table that will be generated
      name: table_id
      type: text
      required: true
      default: product-list
      help: Enter the name of the table that will be generated in the HTML page
    - label: Table columns separated by ';'
      name: column_list
      type: text
      default: ID;TITLE;DESCRIPTION
      required: true
      help: Enter the number of columns of the table that will be generated
    - label: Table attributes separated by ';' (respectively of the inserted columns)
      name: attr_list
      type: text
      default: id;title;description
      required: true
      help: Enter the column attributes in the same order as entered in the
        column_list field.
  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

Dica!

Confira se a indentação do arquivo plugin.yaml está correta.

Pronto, você editou o Plugin B.

Passo 7. Aplicar o 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:

  1. Acesse o diretório criado no Passo 4, execute o comando:
cd example-project
  1. Execute o comando com o caminho absoluto do diretório do Plugin B:
stk apply plugin <plugin-B-directory_path>

Coloque o caminhos sem as chaves.

informação

Confira um exemplo de caminho absoluto do diretório:

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

  1. Então responda as perguntas no terminal:
  • ? Name of the table that will be generated (product-list):
  • ? Table columns separated by ';' (ID;TITLE;DESCRIPTION): .
  • ? Table attributes separated by ';' (respectively of the one entered in the columns) (id; title; description): aperte Enter.

Após responder as perguntas o output deve ser:

Plugin <plugin-B-directory_absolute_path> applied.

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

Dica!

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.

Passo 8. Publicar o Plugin A e B

Todo o processo até aqui foi feito localmente. Agora, para ter acesso aos seus Plugins dentro de um Studio no Portal StackSpot EDP, publique o Plugin A primeiro e depois o B.

  1. Acesse o diretório raiz do Plugin A e execute:
stk publish plugin --studio studio-slug-name

Na StackSpot, Slugs são identificadores únicos de Contas, Estúdios, Stacks, e Plugins, eles fazem parte das URLs da StackSpot. Você pode encontrar o slug de um Studio no dashboard dele dentro do Portal StackSpot.


  1. Acesse o diretório do Plugin B e execute:
stk publish plugin --studio studio-slug-name

Você publicou o Plugin A e o Plugin B e pode encontrá-los no seu Studio.

2. Criar uma Stack e adicionar Plugins

Crie uma Stack e adicione os Plugins A e B nela.

  1. Acesse o seu Studio no Portal da StackSpot;
  2. Clique no botão 'Criar' e selecione 'Stack';
  3. Informe: o Studio, nome da Stack e a descrição.
  4. Clique ‘Criar Stack’.

Agora, adicione os Plugins:

  • Clique na Stack que você criou.
  • Clique no botão ‘Adicionar Plugins’.
  • Escolhas os Plugins A e B, clique em ‘Adicionar Plugins’.
Atenção!

Não publique sua Stack ainda! Aguarde até criar o Starter no próximo passo. Caso publique antes de criá-lo, será necessário gerar uma nova versão da Stack.

3. Criar um Starter

Os Starters são úteis para que os criadores de Stack definam dentro da própria Stack combinações comuns de Plugins, e definam "receitas prontas" para as combinações mais comuns dentro da Stack. Nele, você consegue adicionar quantos Plugins quiser.

Para saber mais, confira a seção de Starters

Ainda na sua Stack:

  1. Navegue para a aba 'Starter';

  2. Clique no botão ‘Criar Starter’;

  3. Agora você deve escolher qual tipo de Starter você irá criar. Para esse exemplo, você deve selecionar 'App Starter';

  4. Adicione um Slug e uma descrição para o seu Starter e clique em ‘Continuar’;

  5. Agora, adicione os Plugins que você acabou de criar ao seu Starter. Clique em ‘Adicionar Plugins’;

Cuidado!

A ordem que você adiciona os Plugins é relevante. Selecione Plugin A primeiro, a base HTML. Depois o Plugin B dummy-json.

  1. Clique em ‘Próximo ', depois ‘Concluir‘.

Você criou, publicou Plugins e criou uma Stack com Starter, via STK CLI.

4. Publicar Stack

Para que sua Stack e seu Starter fiquem visíveis e disponíveis para uso dentro do Studio, você precisa publicá-la. Siga as instruções:

  1. Acesse sua Stack;
  2. Clique em 'Publicar';
  3. Selecione o tipo da versão;
  4. Adicione o número da versão;
  5. Clique em 'Publicar nova versão da Stack'.

Quais são os próximos passos?