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.
Moboom gives you the following data types that you can use for your widget settings:
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.
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.
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.
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.