Tutorial - Create your Own Plugin

Create your own Plugin with the Thorium Plugin Packager

By Thorium Builder Team - November 2020

In this tutorial, we will learn how to create a Plugin with the Thorium Plugin Packager.

We recommend you to first read the Documentation in order to understand the basics of a Thorium Builder Plugin: https://www.thoriumbuilder.com/helpcenter/plugin_editor.html

The first Plugin. Is very basic, it will display the current Date and Time, we will call it showdatetime
The second one will explain how to implement a none-visual component that will let you clear the App service Worker cache.

Many Thanks to Harald Schneider (https://marketmix.com/de/) for sharing the code used in the second example (reset the Service Worker cache).

Getting Started

First, you have to install and launch the Thorium Plugin Packager (Download it from its help page at https://www.thoriumbuilder.com/helpcenter/plugin_editor.html )

Important

Thorium Plugin Packager will only work on a Mac with a valid Thorium Developer Edition

Thorium Builder Packager Main Interface

Click on the New Plugin button in order to create a new Plugin and call it showdatetime

Select the “Available for Mobile Projects Option (Framework7)” and select "Include Visual Interface" as well.
The default Interface code will be generated:

Add a class named datetimewidget to the class list, we will use later this class name as a selector for the widget. So the html code will be:

<div id=":uniqueid" data-plugin-identifier="com.thorium.showdatetime" class="plugin datetimewidget
" >

</div>

This additional class can also be used as default selector if you want to add default CSS to the plugin, for exemple .datetimewidget { color: black; font-size: 15px; } ...

Click on the “Edit Code” button from the toolbar, the code will be loaded in the default Javascript Editor editor. (For example, Visual Studio Code for Mac)

At this step, we will create a function for calculating the Date & Time, just add the following code to the Plugin object:

getDateTime: function(){

        var date= new Date().toLocaleString();

        return date;
}

And then, call this function with a Timer in the initialisation code:

initialize: function () {
      setInterval(function(){ 
         var dt=showdatetime.getDateTime();
         $('.datetimewidget').html("<b>"+dt+"</b>");

      }, 1000);

},

Note that the Selector used here is based on the class “.datetimewidget” that was added to the visual interface.

The whole code should be then the following:

Now, click on the Apply button in order to save the plugin and on the "Install Plugin” button from the toolbar.
If you launch (or restart) Thorium Builder and go to the TB Preferences, the Plugin should be displayed in the Installed Plugin List:

Testing the Plugin

Now we will create a new Mobile project with Thorium Builder, and we will activate our new plugin for this project (go to the Plugin Tab of the Project settings):

At this step, when you go back to the Page Editor, you should see the plugin in the Widget list (Group Plugins at the bottom of the list):

Drop the Plugin to your project page:

Important

The plugins are not executed in the Editor and are displayed with a default gray interface with a plugin icon.

Run the Project:

The date and time are now displayed on the screen and are refreshed every second.

Important

If you make changes to the plugin code, just reuse the button “Install Plugin” in the Thorium Plugin Packager and Rebuild your project in Thorium Builder, all your changes will be republished in your project automatically.

Application to a none-visual, component

Some Plugins may just need to perform actions, calculations, etc… and don’t need a visual interface.
We will here implement a non-visual component with the code provided by one of our German Thorium builder user Harald Schneider (https://marketmix.com/de/).
The purpose of this plugin is to trigger a reset of the Service Worker Cache from the App.

Let’s create this new plugin, we will call it serviceworkerreset

Plugin Parameters

The process requires to call a PHP file from the server and to reload the App, so we need to first create a PHP file with the name prepare-update.php and containing the simple following code:

<?php

header('Clear-Site-Data: "cache", "executionContexts"');

exit;
?>

Use the “Add Files to Plugin” button and add this php file to the plugin:

Once the PHP file has been added to the Plugin select the "Edit Code Button” from the toolbar, and add a function that will reset the Service Worker Cache by using the PHP code.
Add the following method to the Plugin object:

resetServiceWorker: function() {

      app.request.get("js/plugins/com.thorium.serviceworkerreset/prepare-update.php", 
           function(data) {

              caches.delete("thorium-cache");

              window.location.reload(true); 
        }); 
 }

Of course this example can be improved, for example, the extended code above implements a delay of 1 second with a loading wheel before calling the PHP file, it is testing first if a Service Worker is installed and if the App is online and finally call the PHP script in a promise with error management:

Note

You can use the Thorium log in order to display information while running the App in the TB simulator, the function to call is thoriumCorePlugin.logEvent
This function expect 2 parameters, the first one is the log level (0: Success, 1: Warning, 2:Error), the second one is the test you wish to display in the log window.

Save the Plugin (Apply Button) and click on the Install button: the Plugin will be installed/updated and will be available for your projects.

We will now check how to implement it in a Mobile Project. Start TB, create a new project and enable the plugin from the Project Preferences=>Plugins

If you rebuild the project and go to the published project folder, you will see that both the Plugin JS file and the PHP files have been added to the project:

Now let’s see how to call the plugin in order to reset the SW cache.

As this plugin has no visual interface, it won’t be visible in the Widget list, but because it has been added to the project, it is reachable with c custom code. We will then add a button to the interface:

And we will add a onClick Event to the button:

And then, we add just 2 lines of code to the event:

serviceworkerreset.resetServiceWorker(); will call the reset function.

Important

This plugin won’t work when you will run the app locally with the Simulator, it will work only for an App hosted on a Server.

You can download this Plugin example here:

Download the ServiceworkerReset Plugin

Note

By using the “Open a Plugin” button in Thorium Plugin Packager, you can open this plugin and modify it in order to complete it and create your own version