Widget Developer Documentation

Mechanics

Before you learn the details of API calls and other programming techniques, you need to get the basic mechanics out of the way. Where is the widget builder? How do you install external script files or images? 

You’ll be building your first widget here. Nothing fancy...step by step.

Installing the widget builder

The widget builder is a module. If it’s installed on your site, you’ll find it in the left sidebar in the Moboom studio.

If your site doesn’t have the module installed, here’s how to get it up and running:

  1. Open your library: In the left sidebar, click My Library.
  2. Filter your library to just include modules. In the left sidebar, under Types, select Modules. This will show only modules, and not themes or widgets.
  3. Click Widget Builder.
  4. On the Details popup, click Add To. You’ll see a list of all sites available to you.
  5. To add the module to a site, select it from the list, and then click Install.

Creating a new widget

When you visit the widget builder page, you’ll see a popup menu at the top-center of the window. Click on it and select “Create new widget.” Name your widget by clicking again in the header where it now says “New Widget,” and type “Example Widget 1.”

New widgets are not created empty; they are complete and functioning. 

In the right sidebar, you’ll see a list of assets included with your widget. For now, there is only one file, main.php. The file’s contents are shown in the main part of the window. As of this writing, the starter code for new widgets looks like this:

<?php
echo 'Hello, I am your shiny new widget';

Make sure you save the file, by clicking on the Save button at the top right of the text editor.

Now, switch to the page editor for one of the pages in your site. Your new widget will appear in the list of widgets in the Uncategorized section (or you can search for it as well).

Note
When you create a new widget, it is immediately available to all of the sites in your site collection. However, any time you make changes in the widget builder, you will need to reload the site studio for those changes to become available. For example, if you have two tabs open — one with the widget builder, and one with the site studio — your new widget will not be available in the site studio tab until you reload the page.

Adding assets (general)

Widgets are not limited to a single file called main.php. You can add assets to the widget package, such as additional PHP files, scripts, images, and style sheets.

There are two ways to add an asset. The first way is for text files, whose content can be pasted into the on-screen editor:

  1. Ensure you’re in the widget builder, and that the correct widget is selected. (Its name is shown at the top of the screen.)
  2. At the bottom of the right sidebar, click the plus sign . This will create a file called “new_file.php”. 
  3. Double-click on the file name in the right sidebar, and rename it.

The second way to add an asset is for binary files such as images or font files. 

  1. Ensure you’re in the widget builder, and that the correct widget is selected.
  2. At the bottom of the right sidebar, click the upload button .
  3. You will be prompted for which file to upload from your computer. Select the file, and it will be installed into your widget.

After you’ve added an asset, you can rename it by double-clicking it. You can also delete it by clicking the next to the file name.

Changes to the widget code are immediately available. There is no separate publish step, other than saving your files. Once you do that, you can preview your site, and the new widget code will be used.

Adding assets: PHP files

The first thing we will add is another PHP file. 

Follow the instructions above in the section called “Adding assets (general).” Name the new file extras.php. Put the following code into it:

<?php
function supercompute( $a, $b) {
    return $a + $b;
}

Now edit the code of main.php:

<?php
include( 'extras.php');
$output = supercompute( 12, 33);
echo "Supercomputer output: $output”;

That’s all there is to it. Because widgets are published instantly, your new code is available immediately.

Adding assets: images

You can also add images to your widget. Images are covered in depth on the Images & Files page. For now, we will add an image directly to the widget itself, rather than letting the user select an image in the widget settings. (This is useful for situations in which the images are not meant to be overridden, such as user-interface elements.)

Follow the instructions above in the section called “Adding assets (general)” to upload an image. You can rename it if you like by double-clicking it in the file list in the right sidebar.

To display the image, add a new function to the extras.php file. In the example below, the image is called test.jpg.

<?php
function showTestImage() {
    $imgURL = Moboom::getBaseUrl() . 'test.jpg';
    $img = Moboom::createImageUrl( $imgURL);
    echo "<img src='$img' />";
}

The API call to Moboom::getBaseURL() retrieves the path to the directory that the widget is stored in. Use this API any time you want to build a client-side reference to an asset. (Note that we didn’t need this API call when we used the include function to load the file extras.php. That’s because PHP files are loaded server-side.)

When you look at the source code of the generated page, you’ll see what this API call is doing. Assets in your widget are loaded using URLs like this: /_ext/widgets/d4567890-1e87-abcd-4567-12345abcde01/scripts.js. You should never hard-code these paths, as the Moboom platform may move your widget package to a different directory at any time.

Adding assets: folders

Grouping files into folders is not strictly necessary, but it can be a convenience. Other than the root file (main.php), none of the other assets in your widget package need to be at the top level. 

To add a folder, click the folder icon below the file list on the right side of the widget builder. You can drag and drop files into and out of the folder as needed.

Files stored in folders must be referenced using their folder names:

$imgURL = Moboom::getBaseUrl() . 'images/test.jpg';

Adding assets: JavaScript

There are several ways to load scripts into your widgets. Since these scripts are loaded client-side, we’ll need to be careful and specific about how and when they are needed.

For this first example, add a new file called scripts.js to the widget, and enter the following code:

$(function() {
    $(“body”).css( ‘background’, ‘#fcf’);
});

The first line of this script tells jQuery to wait until the document has been fully loaded before running the second line of code. When that happens, the background color of the web page will change. Not the most useful script, but it will do.

Loading script files

Now, to load this script file into the web page, add a line of code to main.php. The last line in the next code snippet is new:

<?php
include( 'extras.php');
$output = supercompute( 12, 33);
echo "Supercomputer output: $output”;

Moboom::registerScriptFile( Moboom::getBaseUrl() . 'scripts.js', Moboom::POS_END);

The API call Moboom::registerScriptFile() takes two parameters. The first is the path to the script, and here we again need to use the API call to Moboom::getBaseUrl() because the script is loaded client-side. The second parameter is a keyword, Moboom::POS_END, that tells the widget renderer to load the script file right before the closing </body> tag.

Note that if you load multiple instances of the same widget onto the same page, script files loaded this way will only be included once. You’ll typically use this method when including library code that can be shared by multiple instances of the widget.

Loading script commands directly

JavaScript commands can also be loaded directly, rather than by using an external file. Here is an example. Pay particular attention to the first two lines.

<?php 
$script = '$("body").css( "color", "blue")'; 
Moboom::registerScript('colorify', $script, Moboom::POS_READY);

The first line creates a PHP variable that holds some JavaScript code. The second line uses the API call  Moboom::registerScript() to install the script inside a jQuery-ready function. (See the API reference for details.) 

In other words: like the previous script, this new script will run after the DOM has loaded. We’ve used a different technique — loading the script directly rather than as an external file reference — which has some significant differences in implementation. If you view the source of the generated page, you’ll see the JavaScript code has been written into the page, rather than linked from an external file.

Watch out!
Scripts loaded using Moboom::registerScript() will be embedded directly in the HTML code of the page. If you include multiple instances of the same widget on a page, the script will be repeated multiple times. This API is most useful when writing scripts that are specific to a single instance of your widget. So scripts loaded this way will typically reference DOM elements by ID, rather than by class. See the code for Product Switch in the Samples section.

The discussion on the use of JavaScript in widgets is continued, with more complex examples, on the JavaScript page.

Adding assets: CSS

External style sheets are easily loaded using their own API call:

Moboom::registerCssFile( Moboom::getBaseUrl() . ‘styles.css’);

This API is almost the same as loading a JavaScript file. For style sheets, however, we don’t need to indicate where the file should be loaded, as all style sheets are loaded in the <head> section of your web page.

There is another way to load styles, which we’ll discuss in the section on Settings.