Create Plugin Locally
This section provides a tutorial on how to create a Plugin v3 locally.
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.
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:
- Create Plugin A, a base that generates an HTML page with a customizable header and title.
- Test Plugin A.
- Create Plugin B that integrates a table with product data from the API - DummyJson Products
- Test Plugin B.
- Publish the Plugins in the Studio.
Requirements
- You must be logged into your StackSpot account.
- STK CLI installed
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.
- Still in your IDE, within the created directory, run the command:
stk create plugin base-html-plugin
- 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:
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:
Open the base-html-plugin folder and then enter templates. Check the image:
Follow the instructions:
-
Copy the entire file structure within this folder.
-
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:
- 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:
Done! You customized your Plugin A.
Step 4. Apply Plugin A
Now you need to apply your Plugin to test it, check it out:
- 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
- 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 >
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:
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:
- 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
- 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.
- Check the folder structure created within the directory. This is the standard structure of a StackSpot Plugin. Check the image:
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
.
- Copy two contents from this file:
- The entire folder called
Snippets
; and - The content of the
Templates
folder.
- Then paste the content inside the Plugin B folder,
dummy-json-plugin
. Delete the README file from theTemplates
folder.
The folder should look like the image:
- Configure the
plugin.yaml
file and add hooks to the Plugin. Paste the code in theinputs
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:
- Access the directory created in Step 4,run the command:
cd example-project
- 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.
Check an example of an absolute path to the directory:
/Users/username/test-html/dummy-json-plugin
Enter the path without the braces.
- 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.
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:
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
- Create a Studio, if you have permission; or
- Be inside a studio.
You must publish Plugin A first and then Plugin B.
- 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.
- 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.