Widget Developer Documentation

Misc Topics

Error checking

As discussed earlier (see Widget Basics), The Moboom renderer sandboxes widgets for security, portability, and language-neutrality. One of the extra benefits of the sandbox is that widgets fail gracefully. 

The red box at right shows how a custom widget will fail in Moboom. Rather than breaking the page or hanging the server, a broken widget will cause the renderer to print an error message. The error only displays in the Moboom studio; on your live site, an empty div will be generated.

You can also call the PHP function error_reporting() if you want to adjust the types of errors reported.

A broken widget:

  • Could not render widget.
  • Error (4): syntax error, unexpected 'broken' (T_STRING) on line 2 of file: /var/widgets/main.php

Design mode

There may be situations in which you want your widget to render differently in the studio than on your live site. For example, some of Moboom’s widgets will print out a message if the widget settings have not been sufficiently filled in to render a useful widget. The following fragment illustrates the use of Moboom::isDesignMode() in practice:

$setting = Moboom::getWidgetSetting( 'info');
if ( empty( $setting) and Moboom::isDesignMode()) {
    echo "(Please set up the Test widget)";
}

Consider what would happen without this message. If a widget is not set up properly, it may not output anything at all. This leaves the user with nothing to click on in the studio. Thus, they will be unable to edit the widget, leaving it unreachable — impossible to edit, impossible to remove. The extra message in the widget fragment above will prevent this lockout.

There are two related APIs that you may find useful: Moboom::isLive() and Moboom::isPreviewMode(). See the API reference for details.

Invisible widgets

What if you’re writing a widget that is designed to produce no HTML output? For example, we have a widget called JS Include which is meant to be an easy way for you to insert JavaScript on your page. The widget’s output is whatever script you give it; it generates no structural HTML elements that the user can click on, even if the script affects the DOM. So...how is the user supposed to grab the widget to edit it?

At right is an example of an invisible widget. You can flag your widget as invisible on its settings page. If you do so, the Moboom studio will display an icon placeholder for your widget, which users can click in order to edit the widget’s settings.

Page elements

You can load page elements from within a widget very easily. You might want to do this in a widget that lists elements from a content set, like a blog index or a real estate listing. You could hand-craft the output of each listing, and embed that HTML code into your widget. But a better solution (in many cases) is to keep the design separate, and let the user arrange the elements of each listing however they like.

Let’s go over that again. One way to write a widget that creates a blog index is to write the code so that it emits the DOM structure for each blog post: the featured image, the title, and the blurb text with a “read more” link. The problem with that approach is that if you (or your users) ever want to change the layout of each blog index — perhaps to use a wide image instead of a square image — then you have to rebuild the widget code. 

The other way to write the widget is to let the user select a page element to hold each blog post. They can design the page element any way they like using all of the features of the Moboom studio (and all of its widgets). Then your widget will print out a fresh copy of the page element for each blog post, and design changes will not require you to edit the widget code.

Now that you understand why you might do this, here is how. That’s the easy part. First, ensure you give your user a way to select a page element by building a setting with that data type. Then, in your widget code, use the API call to Moboom::includePageElement().

$pageElt = Moboom::getWidgetSetting( 'content');
Moboom::includePageElement( $pageElt, NULL);

URLs

You should run all of your URLs through the Moboom::createUrl() API. Just do it.

$url = Moboom::createUrl( 'api-reference');

This API is mainly needed to future-proof your widget. Consider it a best practice.

We have some very fancy and interesting stuff going on at the server, including a module that generates multiple sites from a single template. If you build your widgets using this API, your widgets will be usable on multi-site installations.

Cookies & global variables

With widgets running in their own miniature virtual machines, the access to PHP’s global and variables and system environment is slightly different.

The Moboom widget renderer gives you access to a fresh copy of most of the relevant global variables: $_GET, $_POST, $_REQUEST, $_COOKIE, $_SESSION. These are read-only, of course. Use them as you normally would:

$q = $_GET['q'];

The global variables are set once when your widget is loaded. So, for example, the $_COOKIE array will not reflect calls to Moboom::setCookie().