Hello World Plugin

Let’s build your first plugin: “Hello World”.

💡

You can find the complete code in this Github repo. Feel free to clone it and use it as a template or reference for your plugins.

1. Plan

   We already have a name: “Hello World”, so we can check this box.

   The “Hello World” plugin will embed a simple widget into every application’s page, which will display a random application user’s name and the number of users using this application.

   This impacts what our manifest.json file will look like. We will get to it in the next step.

2. Build

   First, let’s create the manifest.json file for our plugin.

   Let’s start with the mandatory properties that every plugin must define, regardless of its purpose and functionality - the version (must be a valid semver version) and the list of categories this plugin is associated with.

   Since this is our first version, we’ll go with 1.0.0 , and for categories we will choose “Productivity” as this plugin is such a productivity boost!

   JSON

   {
     "version": "1.0.0",
     "categories": ["Productivity"]
   }
   

   Next, let’s add the necessary properties needed for our plugin to function as we expect, under the config section:

   JSON

   {
     "version": "1.0.0",
     "categories": ["Productivity"],
     "callbackUrl": "A_VALID_CALLBACK_URL",
     "config": {
       "consent": {
         "description": "Select one of the available app user statuses. The plugin will only fetch users who match the status you selected.",
         "fields": [
           {
             "name": "status",
             "type": "dropdown",
             "label": "User Status",
             "options": [
               {
                 "label": "Active",
                 "value": "active"
               },
               {
                 "label": "Deleted",
                 "value": "deleted"
               }
             ]
           }
         ]
       },
       "app": {
         "fields": [
           {
             "key": "username",
             "type": "singleLine",
             "label": "Random application user"
           }
         ]
       },
       "widgets": [
         {
           "type": "KeyValue",
           "fields": [
             {
               "key": "app.username"
             }
           ]
         }
       ]
     }
   }
   

   Using this manifest, every time our plugin is installed, 2 things are going to happen:

   1. One custom application field: "Random application user" will be created, based on the app.fields list.
   2. A KeyValue widget will be embedded into every application’s page, displaying the fields, based on the widgets list.

   Our manifest is now complete. Let’s move on the creating the readme file for our plugin.

   Markdown

   Introducing the "Hello World Plugin" – the perfect way to add a touch of personalized engagement to every application's page. This lightweight and versatile plugin seamlessly embeds a simple yet dynamic widget, providing users with a delightful greeting that includes a randomly selected user's name and the total number of users currently using the application.
   
   Key Features:
   
   1. Personalized Greetings: Delight your users with a warm welcome by displaying a randomly chosen user's name in the widget. This personalized touch adds a friendly and engaging element to your application.
   
   2. User Count Display: Keep your community informed! The widget also showcases the current number of users actively using the application. It's a subtle way to highlight your growing user base and create a sense of community.
   
   3. Easy Integration: With a user-friendly design, the "Hello World Plugin" is designed for hassle-free integration. Simply install the plugin, and the widget will automatically appear on every application page.
   
   4. Customization Options: Tailor the widget to match your application's aesthetics. Choose from various display options, such as color schemes and fonts, to ensure a seamless blend with your existing UI.
   
   5. Lightweight and Fast: Our plugin is optimized for performance, ensuring that it adds a personalized touch without compromising your application's speed. The widget loads quickly, contributing to a smooth user experience.
   
   How to Use:
   
   1. Install the "Hello World Plugin" plugin from the marketplace.
   2. Enjoy the instant addition of the widget to every page, creating a more engaging user experience.
   
   ---
   
   Note: The "Hello World Plugin" is not just a greeting; it's a small yet impactful way to enhance user interaction and foster a sense of community within your application. Install today to add a touch of personalization to your user experience!
   

   And last, let’s wrap things up with our logos. The logos can be downloaded from the example repo.

3. Deploy

   Copy and paste the following cURL commands to deploy the “Hello World” plugin:

   1. Create the plugin

      cURL

      curl --request POST 'https://api.toriihq.com/v1.0/plugins' \                                                                                                          git:(master|●6✚4…3
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <YOUR_API_KEY>' \
      --data '{
          "name": "Hello World"
      }'
      

   2. Compress the files into a ZIP folder

      Text

      // macOS
      zip -r plugin.zip README.md logo_253x148.png logo_40x40.png manifest.json
      
      // linux
      sudo apt-get install zip
      zip -r plugin.zip README.md logo_253x148.png logo_40x40.png manifest.json
      
      // windows (using PowerShell 5.0+)
      Compress-Archive -LiteralPath 'README.md logo_253x148.png logo_40x40.png manifest.json' -DestinationPath "Test.zip"
      

   3. Upload the ZIP folder to Torii

      cURL

      curl --request POST 'https://api.toriihq.com/v1.0/files/upload' \
      --header 'Authorization: Bearer <YOUR_API_KEY' \
      --form 'type="plugin"' \
      --form 'file=@"<PATH_TO_ZIP_FOLDER>"'
      

   4. Link the plugin to the ZIP folder

      cURL

      curl --request PUT 'https://api.toriihq.com/v1.0/plugins/{uuidPlugin}' \                                                                                                          git:(master|●6✚4…3
      --header 'Content-Type: application/json' \
      --header 'Authorization: Bearer <YOUR_API_KEY>' \
      --data '{
          "idUpload": <ID_RETURNED_IN_#3>
      }'
      

   At this point, you should be able to see the “Hello World” plugin on the Marketplace.

4. Test

Run yarn start or npm run start to set up the server to listen to install/uninstall events, and update the fields created by the plugin. Make sure your server is able to accept API calls over the network and that your callbackUrl is updated accordingly.

You can use tools like ngrok to expose your server to the internet.

Go ahead and install your plugin to test everything is working as expected.