Coding with Thorium Builder

Updated on January 11, 2021

Although Thorium Builder is a NoCode product, it can be useful or necessary to add some custom code in particular situations.

We will talk here about PWA projects powered by Framework7 .
Responsive Web Projects are powered by Bootstrap and jQuery and are really standard so you can find a lot of help and resources on the web (but the logic is the same as for mobile apps)

The purpose of this documentation is not to teach you how to code and describe all of the functions available in the framework, but simply to help you get started with your custom code implementation.
Please be aware that although we provide this “How To” tutorial, we do not provide any technical support on coding, only for issues directly related to TB. And the code you add to your project is obviously your own responsibility.

General Concepts

Mobile projects created with Thorium Builder are Single Page Applications (SPAs). This means that when the app is loaded from its url, the index page and associated components (css, js, etc.) are also loaded. When users open another page, the page code is dynamically loaded and added to the DOM at the top of the main view (the index page).

This means that all JS and CSS files loaded by the index page are available for ALL pages in the project. Thus, in order to allow you to add your own code or styles, each Mobile project created with Thorium builder comes with 2 custom.js and custom.css files (js and css subfolders of the project). These 2 files are loaded automatically by the index page and are then available globally for the entire project. Here we'll focus on the Custom.js file.

The Framework

Thorium Builder PWA is powered by the awesome Framework7 (https://framework7.io), and although f7 supports Vue.js, React, and Svelte, Thorium Builder uses the Framework7 Core option.
This means you can code with Vanilla JS or with the built-in Core Library which is almost equivalent to Jquery.
The complete documentation for Framework7 is available at this address: https://framework7.io/docs/

Responding to Events in Thorium Builder

Thorium Builder can generate the necessary code that will let you respond to an event. Let’s see how to implement a very basic response to the Click/touch event on a button: First of all, just create an empty App and add a Button on the page.

Select the button and then select the “Events” tab from the properties panel:

Double-click on the “onClick” event, It will then load a basic code editor with the generated code:

As you can see on the screen, the Click event is handled by triggering an event based on the object ID.
Then we will just display an Hello World message: Complete the code as following:

$(document).on("click", "#obj-31238", function(e){
          e.preventDefault();
          app.dialog.alert("Hello World");
});

Run your App...

Click on the Button, the dialog popups. Now let’s say that instead of displaying a message, we want to interact with another element of the page.

We ‘ll change the text value of another element when the user click/touch on the button. And for that purpose, we will show you how to call a function:

Add a Text field on the screen and get its ID:

Then edit the custom.js file again (You can use the Command+Alt+C shortcut to start the Code Editor quickly)

We will now write a function that will calculate a contents to be displayed on our new text field:

function getDateTime() {
  return new Date().toLocaleString();
}

 $(document).on("click", "#obj_31238", function(e){
      e.preventDefault();
      $('#obj-18565').text(getDateTime());
 });

Run your App again: the button click now displays the current date-time on the Text field

Custom Event Handlers

Sometimes you may need to respond to an event triggered by a sub-element of a widget.
This is the case with widgets that include a list of sub-elements: for example, the data-lists, medialists ...

Such Widgets are generally defined in the DOM with a global div with a specific class (eg. list, .medialist …) and different lines ("<li>”) wrapped within a <ul> element.
So for example you may need to detect a “click” event on every line of a datalist/medialist.

The first thing you have to do is analyzing the DOM structure of the Widget, by using the  Inspector of the browser debugger. (Read the Tutorial Using Safari Debugger for more details).

For example, here is the DOM Structure of a simple Data-List:

As you can see in this screen-shot, the main widget has the id "datalist-1014” and the class “.list” and there is a <ul> wrapper inside with different lines (“<li>”)

So, if you need to handle the Click event on every line (<li>) of this data list, then you can add the following event handler to your code:

$(document).on("click", "#obj-31238 li", function(e) {
         //Do Something
});

Now let’s say that we just want to get the value of the item-footer selected by the user and display its value in a dialog box:

$(document).on("click", "#datalist-1014 li", function(e) {
    e.preventDefault();
    var clickedLine=this; //Get the selected line reference
    var itemFooter=clickedLine.querySelector(".item-footer"); //Get the selected line item footer
    if (itemFooter) {app.dialog.alert(itemFooter.outerText);} //Display the Selected line Contents (if exists)
});

A complete example template with this code  is available here: https://www.thoriumbuilder.com/downloads/tutorials_files/javascript_example.hbt.zip

Global Events Attached to Plugins

Most of the Plugins available in Thorium Builder are generating custom events. (Framework7 itself generates events, but TB implement other specific ones)
 For instance, the JSON Api Plugin or the Firebase trigger a set of custom events that are visible only when the JSON Api plugin is activated in your project:

The logic is always the same, so the event code is generated and you can put your code inside.

Global Variables and Constant

As the custom.js file is global and used everywhere, you can declare constant and variables that will be always available during the App execution.

Debugging your code

Of course, as a noCode product, TB does not include a Debugger, but you can use the Safari or Chrome Debugger without problem.

If you run a local Web server on your computer, then no problem. If you run your App only from TB without a Web Server, then you can launch the index file directly into your browser (so with the file:// protocol) , but in that case you will have to check the “Disable Local File Restrictions” from the Developper menu of Safari (almost same process on Chrome).
You may have to check as Well “Disable Cross Origin Restrictions” if you are using external Widgets (youTube, etc…)

Read our Tutorial Using Safari Debugger  for more details.

For more details about the amazing possibilities implemented in Framework7, don’t forget to read their documentation at address https://framework7.io/docs/

Shortcut Functions (API)

Read the Thorium API Page