Widget Developer Documentation

Widget Basics

Ok, you’ve used widgets in the Moboom platform, so you have a basic grasp of how they work from the user’s side. But what about behind the scenes?

Custom widgets are how you can build out your site in just about any way imaginable. The Moboom platform is a powerful design studio, but any time you want to add features that aren’t built in, you’ll need to build a custom widget. 

And before we get too far, let’s get this out of the way: it’s actually pretty easy to build custom widgets. You don’t need to understand the full API in order to build functional and beautiful widgets. With just a few lines of code, you can be off and running.

The rest of this page will introduce you to some essential concepts: What exactly is a widget? What kind of outputs can you create with widgets? How are widgets rendered?

What’s a widget?

The entire output of the Moboom platform — i.e., the contents and assets needed to build your web page on a client machine — is produced by two systems. 

The first system is the Moboom page template, which builds the core structure of your page. It includes the <html> and <body> tags, and all of the header information. It also includes system-provided libraries such as jQuery, Modernizr, and Bootstrap.

The second system is the widget renderer. Everything on the page (inside the page template) is a widget. In fact, any visible output on your page is created by a widget. Many widgets have been built for you by Moboom, such as the Header widget, Rich Text widget, and Image widget. For the most part, these are widgets that you could have built yourself (after this tutorial, of course). In other words, the core Moboom widgets do not have special privileges that you don’t also have.

So, to say it another way: anything you want to put on your page needs to be created by a widget. And anything that isn’t something that Moboom provides in our core widget collection, or isn’t available for download in the marketplace, is something that you can build yourself as a custom widget. 

Widget outputs

Most widgets will output HTML code. For example, the Header widget just above this paragraph generates the following HTML code:

<div class="heading">
   <h3>Widget outputs</h3>
</div>

The outer <div> is created by the Moboom platform. The class heading is automatically assigned to all Heading widgets; Moboom picks the class based on the name of your widget.

The code inside the <div> is generated by the widget code itself. In this case, the output is extremely simple. But you can create widgets as complex as you like.

You’re probably wondering what the widget code actually looks like for the Heading widget. Here it is, in glorious PHP, and without any explanation:

$text = Moboom::getWidgetSetting('text');
$level = Moboom::getWidgetSetting('level', 1);
echo "<h$level>$text</h$level>";

The Moboom API will be covered in detail shortly. For now, just notice that all of the widget output is generated by the echo command.

While this widget only outputs HTML, some widgets also generate JavaScript and CSS. This is covered in the Mechanics section.

Bootstrap

Moboom sites are built atop the Bootstrap library (version 2.3.2). When you output HTML code for your widget, you are encouraged to use the structures provided by Bootstrap. For more details, see especially the documentation on the Bootstrap grid.

Designing for different sizes & devices

In order to be a good citizen of the Moboom platform, your widget should not make assumptions about the width of its container. Unless you are writing a custom widget for use only on a single site, you should build your widget to work properly on all devices, and look “appropriate” (whatever that means to you) at all widths. 

If your widget will not render meaningfully on devices such as feature phones, feel free to use device checking to suppress all output on those devices. And certainly you should be testing your widget on a wide range of devices, including BlackBerry phones, tablets, older versions of Android, and more. If you work in the San Francisco area, contact us about using our Open Device Lab to do your testing.

Understanding the “sandbox”

Widgets are executed in their own private sandbox. (If you’re interested, the sandbox is actually a Docker instance, which is like a miniature virtual machine.)

Putting widgets in sandboxes allows us to accomplish some very nifty tricks. First, it protects everyone from your bad code. If your widget broke, or tried to do something horribly malicious, the worst that could happen is that the widget breaks. You can’t take down anyone else’s site, and even your own site will continue to run smoothly (other than the broken widget, of course). 

Ever wonder why the list of approved plugins on Wordpress.com is so short? That’s because they don’t sandbox their plugins, so a malicious plugin can do some pretty severe damage. The Moboom server runs many web sites at once, just like Wordpress.com. But we don’t have to approve your custom widgets, because you can’t break anything.

As long as we’re raving: sandboxing also allows us to render widgets in parallel, using multiple independent rendering instances. If that doesn’t mean anything to you, here’s the short version. Your page will render extremely fast. 

Ok, as you can tell, we’re pretty chuffed about the widget rendering engine.

Language features

Because you’re running in a self-contained environment, and not as a file loaded via include, you don’t have access to the outside world in the way that you’re probably used to. For example, the normal methods of accessing cookies, or query variables, or some of the global objects in PHP ($_SERVER) will not work. We provide access methods for many of these important techniques, which we’ll discuss along the way. 

Your widget is run inside its own closure. The $global keyword will not work in widgets, although you can access out-of-scope variables with closures of your own, with the use keyword.

The PHP interpreter is running version 5.4.