Plugin Packager

Updated November 2020 - VERSION 2.2

Since version 2.0, Thorium implements a system of external plugins.
Plugins make it easy to extend Thorium functionality.
Plugins are Javascript components that can be reused in different projects. They can be created for Apps and/or Web Projects.
As they use a different approach in Web and Apps, it is often easier to create a plugin for only one of the targets.

A complete tutorial with 2 examples is available here: Create your Own Plugin Tutorial

Writing your Own Plugin

In order to create your own plugin, you have to first download Thorium Plugin Packager.

Thorium Plugin Packager will let you configure your plugin in order to make it usable by Thorium.

Thorium Plugin Packager - Main Interface

The options available on the toolbar are:

• New Plugin: create a new plugin project

• Open a Plugin: open an existing plugin in order to modify it

• Export Plugin: Export a copy of the plugin on your desktop

• Delete Plugin: delete a Plugin project

• Delete Plugin: delete a Plugin project

• Edit Code: open the plugin code in, the default editor

• Install Plugin: copy the Plugin to the Thorium Builder Plugin repository (and makes it available for TB Projects)

When starting Thorium Plugin Packager for the first time, the plugin list will be empty, and you can start creating your first plugin by selecting the "New Plugin" option from the Toolbar.

Let’s see what are the plugin settings you have to enter:

• Plugin Name: the displayed name for your plugin, use only latin characters, in lowercase and without any special character or space.
  

• Plugin Bundle id: generated automatically from your plugin name, and used for internal identification.
  

• Short Description: a description that will appear in the Thorium Builder interface
  

• Plugin Help Link: an URL where the user can find the plugin help 
  

• Plugin Help Label: the short label displayed within TB interface (exemple: Show Help)
  

• Internal Help Link: Read-only, for internal use.
  

• Author: the Author of the Plugin
  

• Version: the version or date of creation of the Plugin (example 1.2 , or 1.1 - 2020 etc…)
  

• Available for Web Projects (Bootstrap): is the plugin available for a Web Project
  

• Available for Mobile Projects (Framework7): is the plugin available for a Mobile Project
  

• Include Visual Interface: if selected, then the Plugin includes a visual interface, it can be added to a screen in design mode and will be displayed in the project.
  None-Visual plugins can be added to a project, but won’t display any interface, it can be for example a set of functions that will perform calculations (mathlib, etc…)
  

  When you select this option, a code is generated:

  <div id=":uniqueid" data-plugin-identifier="com.thorium.myplugin" class="plugin” ></div>

  You can add your own elements within this wrapper, but you must make sure to keep id=“:uniqueid” and data-plugin=“com.thorium….. 
  The first will be the unique identifier within the TB Editor, and the second one will identify the Plugin Internally.
  

• Javascript Dependencies: some Plugins may be created from an existing JS Library, in that case, you can reference this library here, it can be an external reference (CDN …) or a local one if you add the library inside the plugin (local access).
  (Note that you can add multiple dependencies here)
  
  For example, an external dependency can be:
  
   <script type="text/javascript" src=“https://myjslibray.com/thesuperplugin.js"></script>
  
  Or, if the script is present inside the plugin:
  <script type="text/javascript" src="js/plugins/com.thorium.qrcode.generator/thesuperplugin.js"></script>
  
  Note that for local file, the path must always be: js/plugins/pluginbundleid/librayfilename
  

• CSS Dependencies: exactly the same than for Javascript libraries but applied to CSS, for example:
  

  <link rel="stylesheet" href="js/plugins/com.thorium.myplugin/myplugin.css"></link>

Opening an Existing Plugin

With the button “Open Plugin” you can open and edit an existing plugin in order to add functionalities or just to check how it is built.

Adding additional Files to a Plugin

Sometimes you may have to add other files to a plugin, a custom css file or an external libraries that you want to include to the plugin.
By clicking on the button “Add Files to Plugin" , you will have access to the “dist” folder of the plugin that contains all the files that will be published with the project when using the plugin in a TB project.
If you add files here, you must reference them in the dependencies, for example, if you want to add a CSS file to the Plugin project, copy your css file to this folder:

And reference it by adding the following line to the Css Dependencies setting:

The relative path must always be: js/plugins/bundleid/filename

Example of Plugin

Plugin Settings

Some external libraries require to add parameters to the JS reference, for example an API key….
If you need to be able to modify those parameters from the TB interface, then you can create properties that will be directly editable within TB. 
For example, the Paypal Checkout Plugin expects a client ID and a default Currency:

And this is how the Javascript dependency is declared in order to implement the 2 variables:

As you can see in this screenshot, 2 parameters have been added to the Paypal Checkout Plugin with a default value. An here what’s happening when you select this plugin in TB and click on the Configure Button:

You can then change the values used for the 2 parameters in the current Project.

Plugin Variables

Your plugin may require some variables that can be added with a default value and that can be changed by code. They must be declared in the Variables Tab of the plugin:

An exemple of variables added to a plugin (Chart.js plugin in this example)

All the variables declared here will be automatically added to the Plugin object as data attributes, for example, the variable aspectratio and its default value (2) will be automatically added to the Plugin as following:

Then, in the plugin code, you can access to the default value, and use a new value set by code when required by ready - writing the data-attribute.

Plugin Code

This is the most complex part of the Plugin creation process.
When you create a new plugin, a default code structure will be created:

This code contains the following elements:

• The plugin object declaration: (var myPlugin …)

  This is the code that contains Properties and methods of the plugin.
  The access to the properties and methods can be done in your custom code by using the following example syntax:
  

  var PluginName=myPlugin.name;
myPlugin.initialize();


  The object includes a default initialize method that will be called when plugin initializes at runtime, this is the place where you have to write the initialization code.

  You will certainly have to add other custom methods in your Plugin code, you must respect the syntax used, for example:
  

  myFonction: function () {
 …. do you own stuff here
 },

• Commented part: (/*— for Apps only...)

  If your Plugin is designed for a Mobile project, then you should uncomment this block of code.
  This code will be executed when you will open a new page, it will let you perform all your initialisation code on Plugins added to other pages than the index page. (For Web projects, this code is not useful and won’t be executed, so you can simply remove it)
  

• document.addEventListener('deviceready', myPlugin.initialize);

  This code will start the Plugin initialisation when the App will run in Native mode, embedded into an Xcode or Android Studio Project. (See Native App generation).
  If the plugin is designed for Web Project or only for PWAs, this code will not be executed.
  

• document.addEventListener('DOMContentLoaded', myPlugin.initialize);
  

  This Event handler is the main starting point for a Plugin, it will be executed for both PWAs and Web project, it will call the plugin initialization method.

Installing a new plugin

Once your plugin is ready to be tested, you can use the button “Install Plugin”, it will copy the plugin to the Thorium Builder Plugin Folder and make it available for TB (You may have to restart TB at the first plugin installation in order to load it, but after that you just have to rebuild your projects for applying the changes made in the plugin)
You can also install it directly from the TB interface, see External Plugins for more details.