Skip to main content

Create Plugin Locally

This section provides a tutorial on how to create a Plugin v3 locally.


warning

This tutorial was created using Plugins version 3.

Objective

This tutorial aims to guide the creation, local testing, and publication of Plugins on StackSpot. It will help you understand how to create content on StackSpot.

The Plugins used as examples:

  • Generate an HTML page and add tables to it.

Level: Beginner.

info

This example is one possibility for creating and publishing plugins locally. Therefore, it is not necessary to be inside a Studio.

Check the summary of the steps below:

  1. Create Plugin A, a base that generates an HTML page with a customizable header and title.
  2. Test Plugin A.
  3. Create Plugin B that integrates a table with product data from the API - DummyJson Products
  4. Test Plugin B.
  5. Publish the Plugins in the Studio.

Requirements

caution

This journey uses only the STK CLI, as it is a tutorial for creating Plugins on your local machine.

Step 1. Create an empty directory

This is where your project will be. In your terminal, run the command:

mkdir test-html

Access the directory using your usual IDE. Run the command:

cd test-html

Step 2. Create Plugin A

Plugin A generates an HTML page with a customizable header and title.

  1. Still in your IDE, within the created directory, run the command:
stk create plugin base-html-plugin
  1. Answer the questions in your terminal. Follow the model:
  • Plugin type: app.
  • Add repository: no. The answer here is no. In this tutorial, you will create Plugins only in your local environment.
  • Version:: 0.0.1.
  • Plugin description: Plugin to generate a base HTML project.
  • Required connection interfaces: do not select any Connection Interface; just press Enter.

Done! You created Plugin A.

A folder structure was created within the directory. Check the image, the standard structure of a StackSpot Plugin:

Screenshot of Visual Studio Code showing the folder structure of Plugin A. The main folder is the base-HTML-plugin, which contains the docs subfolder with .md files like about.md, implementation.md, markdown-guide.md, release-notes-versionx.md, and requirements.md. There is the templates folder and, finally, the plugin.yaml file.

Step 3. Customize Plugin A content

Now, complete the Plugin information to work as the HTML base. A repository is necessary; in this case, use one already created by StackSpot. Clone the repository by running the command:

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

It contains the following folders:

Folder structure of the cloned repository. Folder names demo-html-plugins>base-html-plugin>dummy-json-plugin. LICENSE and README.md files

Open the base-html-plugin folder and then enter templates. Check the image:

Templates folder open. The files are: css, js, resource folder, index.html, plugin.yaml.

Follow the instructions:

  1. Copy the entire file structure within this folder.

  2. Go back to the base-html-plugin folder you created in Step 2. Access the Templates folder, delete the README file, and paste the content you just copied.

The folder should look like the image:

Templates folder copied to Plugin A. The structure of the base-html-plugin folder is docs, templates with CSS, js, resource, index.html, and plugin.yaml.

  1. To customize your HTML page, access the plugin.yaml file, delete the Inputs content, and copy and paste the code:
 inputs:
- label: HTML page title
name: title
type: text
required: true
default: StackSpot - Training
help: 'Enter the title of the HTML page to be generated'

Just like in the GIF:

Replacing inputs in Plugin A. Copy and paste the mentioned code part.

Done! You customized your Plugin A.

Step 4. Apply Plugin A

Now you need to apply your Plugin to test it, check it out:

  1. Create an empty directory within the same directory created in Step 1. (test-html). This will be the folder where your HTML page will be generated after applying the Plugins.

Run the command:

mkdir example-project

Access the new directory, run the command:

cd example-project
  1. Apply Plugin A to generate the base page. To do this, run the command with the absolute path of the Plugin A directory:
stk apply plugin < absolute_path_to_pluginA_directory >
info

Check an example of an absolute path to the directory:

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

Within the example-project directory you created, check the folder structure as in the image:

Test Plugin A. The structure within the directory with the example-project folder and inside with .stk, css, js, resource, and index.html

Done! Now, you can view the base of your HTML page by accessing the directory above on your computer. For example, on Mac, access is through Finder; on Windows, access is through Windows Explorer.

Step 5. Create Plugin B

Plugin B integrates a table with product data from the API - DummyJson Products. And also:

  • Enables customization of columns displayed in the table; and
  • Uses hooks to manipulate files using snippets.

Follow the instructions to create Plugin B:

  1. In a terminal still within the IDE, continue within the directory created in Step 1. (test-html) and run the command:
stk create plugin dummy-json-plugin
  1. Answer the following questions in your terminal:
  • Plugin type: app.
  • Add repository: no. The answer here is no. In this tutorial, you will create only in your local environment.
  • Version: 0.0.1.
  • Plugin description: Plugin para integrar uma tabela de dados na base HTML.
  • Required connection interfaces: Do not select any Connection Interface, just press Enter.

Done! You created Plugin B.

  1. Check the folder structure created within the directory. This is the standard structure of a StackSpot Plugin. Check the image:

Plugin B Folder Structure. The structure of the dummy-json-plugin folder. The docs folder has .md files about.md, implementation.md, markdown-guide.md, release-notes-0.01.md, requirements.md. The templates folder has the README.md and plugin.yaml files.

Step 6. Customize Plugin B content

Complete the Plugin information so that it works. Now, use the repository created by StackSpot that you already cloned in Step 3., the demo-html-plugins.

  1. Copy two contents from this file:
  • The entire folder called Snippets; and
  • The content of the Templates folder.

Contents are to be copied from the complete demo HTML. Highlighted in the image with a red square is what you need to copy. The snippets folder and the css and js files.

  1. Then paste the content inside the Plugin B folder, dummy-json-plugin. Delete the README file from the Templates folder.

The folder should look like the image:

Plugin B templates folder. After copying the snippets folder, it has the files: import-css.txt, import-js.txt, table.txt. And the templates folder with CSS and js.

  1. Configure the plugin.yaml file and add hooks to the Plugin. Paste the code in the inputs section:
inputs:
- label: Name of the table to be generated
name: table_id
type: text
required: true
default: product-list
help: 'Enter the name of the table to 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 to be generated'
- label: Table attributes separated by ';' (respectively from the columns entered)
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"

Done! Your customized your Plugin B.

Step 7. Apply Plugin B

Apply Plugin B to generate the request table. You should apply it in the same directory created in Step 1.

Follow the instructions:

  1. Access the directory created in Step 4,run the command:
cd example-project
  1. Run the command with the absolute path of the Plugin B directory:
stk apply plugin < absolute_path_to_pluginB_directory >

Enter the paths without the braces.

info

Check an example of an absolute path to the directory:

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

Enter the path without the braces.

  1. Then answer the questions in the terminal:
  • ? Name of the table to be generated (product-list): .
  • ? Table columns separated by ';' (ID;TITLE;DESCRIPTION): .
  • ? Table attributes separated by ';' (respectively from the columns entered) (id;title;description): press Enter.

After answering the questions, the output should be:

Plugin < absolute_path_to_pluginB_directory > applied.

Done! Now you can view your updated HTML page with the table.

info

Additional Information The final result (after applying the Plugins) is in the generated project directory, in this case, in example-project. In this project, you will find an index.html file that you can open in the browser to check the result of applying the Plugins.

To access it, enter the directory through your computer. For example, if it's a Mac, it would be through Finder; if it's Windows, it would be through Windows Explorer.

The result of your page should be like the image:

Generated HTML page. The folder has a table with 3 columns. The title is StackSpot Training. The first column is ID, the second is Title, and the third is Description.

Now that you have created and applied the Plugins locally, the next step is to Publish them.

Step 8. Publish the Plugins

All the process so far has been done locally. Publishing your Plugin allows other people to use it on the Portal.

Requirements

  1. Create a Studio, if you have permission; or
  2. Be inside a studio.

You must publish Plugin A first and then Plugin B.

  1. Access the root directory of Plugin A and run the command:
stk publish plugin --studio studio-slug-name 

On StackSpot, Slugs are unique identifiers for Accounts, Studios, Stacks, and Plugins and make up the StackSpot URLs.

  1. Now, access the Plugin B directory and run the previous command.

Done! You published Plugin A and Plugin B and can find them in your Studio.