Widget Developer Documentation

Input Settings

If you’re building widgets that require no user input, you can skip this section. 

If you want users to be able to edit your widget in any way — changing text or images, or changing styles — then read on.

Types of settings

Moboom gives you the following data types that you can use for your widget settings:

  • Numeric — This data type limits the user to numeric values. There are two types of numeric settings, integer or decimal (floating-point). No error-checking is performed for you; if the user enters text which is not numeric, an empty value is returned. If you need to set boundaries — perhaps you want only positive integers — you must do that in code, as the settings editor does not allow you to limit user input.
  • Text — There are three types of text-entry settings: single-line, multi-line (textarea), or full HTML. The HTML type accepts raw HTML code as input.
  • Boolean — This type will be displayed as a checkbox, whose value will be returned as 0 or 1. (Before it is touched, it may return empty.)
  • Date — There are two types: date and datetime. They both give the user a popup calendar for selecting dates. 
  • List picker — This data type creates a dropdown list. You specify a list of options that the user can select.
  • Image — The user can either upload an image or select one from the library or a content set.
  • File — The user can upload any file (such as a PDF of other document). This is documented on the Images & Files page.
  • Page element — The user selects a page element from the current site. The use of page elements is covered on the Misc Topics page.

Most of these types are what we call content-aware, which means the user can easily link them to a content set. In most cases, if you expect the user to link to a content set, you should use the one-line text data type. For example, if a content set called Blog has a field called postDate, you might think that you would use the Date type for a widget setting. But this would actually present a problem, because the date-entry field does not allow you to type directly into it; it uses a popup date picker instead. If you instead use the text data type, the user can easily link to the postDate field using a content-aware bubble.

You can also create a collection of elements, which allows for a repeating group of settings. Collections are documented on the next page.

A quick example

We will rebuild the Heading widget as a simple starter project. Go to the widget builder and create a new widget called Heading Dupe.

Click on the settings button (below the file list on the right side). Add the first setting as shown here.

Select Text from the data-type popup menu. In the name field, enter “text” — this is the keyword that you’ll use when loading the settings in code. In the label field, enter whatever text you want the user to see when editing this widget.

We also need a setting to indicate the heading level. This will be a dropdown menu that allows the user to select which heading tag they want to use. Look carefully at the settings below: first, choose the Select option for data type. Enter “level” for the field name. Then click the Add button to add options to your dropdown menu. Enter values as shown below...and continue through H6.

Be sure you click Save at the top of the Settings page.

Here is the PHP code for this widget. Copy this into main.php.

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

Now try it out! Go to the page editor on your site (you may need to reload the page if it was already open). Find the Heading Dupe widget, and drag it onto your page. 

You should experiment with the different data types. Most of them are straightforward to use. We will look at some data types that need special handling next.

Default widget styles

We’ve already seen how you can load style sheets using the API call to Moboom::registerCssFile(). This is generally not the preferred method for applying styles to your widget, for three reasons.

  • External style sheets do not accept LESS syntax, only CSS
  • They can’t be modified by users
  • They don’t process server-side media queries (documented elsewhere)

The other (and generally preferred) method for styling widgets is using the default styles. Each widget has an option to set default styles for new instances of the widget. To set the default styles, click the “drop” icon below the file list in the widget builder. You can create named styles, which allow less-technical users to edit simpler styles (like color and typography), or advanced styles, which allow users to edit the LESS style rules directly. More documentation on the user experience can be found in the Moboom documentation

Of course, there is a time and place to use external style sheets. In particular, if you are building a widget around a third-party library that comes bundled with a CSS file, you will find it more convenient to load it with the API than with the default styles.