Widgets are small pieces of software that you can add to your ContentBox website to perform a specific function. There are several Widgets built into ContentBox that are used for various parts of your website, and you can insert widgets into blog posts and pages to make your website even more dynamic.
Widgets are one of the ways ContentBox is extendable, you can install modules and themes that overwrite existing widgets, or are brand new... or you can create or customize your own widgets.
Widgets are maintained through the Administrator under Look & Feel > Widgets. You can managing existing widgets, upload new widgets, or download widgets from Forgebox.
In this section of the documentation, you will learn how to develop your own widgets. To learn how to use Widgets, view Widgets under Using Contentbox here
Widgets do not need to have arguments or parameters, but most Widgets are best designed with some customization available to the user.
Let us add a few arguments to our Simple Widget.
Our starting point looks like this.
We want to give the user an option to change the target of the link. To start we will add the urlTarget argument to the renderIt() and then use that argument in our link.
When the user tries to use the widget now, they'll see this added to the Widget selector.
You will see the argument name urlTarget shown, with the type (any). We can add some more options to the arguments to make it more user friendly, including:
Label
Required
Hint
Type
Default
Options
OptionsUDF
MultiOptions
MultiOptionsUDF
These are all added via the JavaDoc syntax for the RenderIt() function. Below is an example of the label being used.
The Label is used when you want to have a more meaningful label for the form field than the name of the argument itself. In our example, by default, the label is urlTarget, but we can change it to something like This is my Label
The Widget Form now shows this label instead of the Argument name
Required does what it says, it makes a field a required field. This will show a label and add the necessary validation.
To make a field required, add Javadoc Meta comment @urlTarget.required to the function meta.
A label goes a long way in helping the user understand the purpose of a field, but you can also use Hints to make this crystal clear.
To add a field hint, add Javadoc Meta comment @urlTarget.hint to the function meta.
Argument Type is very important. By default, all arguments are considered strings, and are shown as a Text Input. The type tells the Widget form builder how to display the argument field. The logic is processed in this order.
Boolean - as a yes / no select drop down
Numeric / String with Options - Select drop down with items from the options list.
Numeric / String with OptionsUDF - Select drop down with items from the options UDF
Numeric / String with MultiOptions - Multiple Select drop down with items from the options list.
Numeric / String with MultiOptionsUDF - Multiple Select drop down with items from the options UDF
Numeric / String - Text Input box
Argument Type can be defined by the Function definition, or with the Meta Data. Below you can see these argument types being set inside the function itself.
You can also use the Meta Data approach that most of the argument options require.
You can set a default Value for the field.
To add a default value for an argument, add Javadoc Meta comment @urlTarget.default _blank to the function meta.
Using Labels, Hints and Required fields helps the user, but in some cases its best if you can give your users a set list of options to pick from. This will provide the user a select drop down box, instead of a text box. This ensures there are no typos.
To add options for an argument, add Javadoc Meta comment @urlTarget.options _self,_blank,_top,_parent to the function meta.
As you can see, the Default value even works with the options drop down, so you can have the default, pre-selected.
Option lists work great for some use cases, but sometimes you might need some dynamic information. This allows you to write a function, and the Widget form builder calls that function for you to load the options. To use an optionsUDF instead of options you need to do 2 things.
1- To add options for an argument via UDF, add Javadoc Meta comment @urlTarget.optionsUDF getTargetTypes to the function meta. The function should be the name without the parenthesis.
2- Add the new function. The new function can be named anything ( other than RenderIt - the default function for a widget ). The function must return an array of elements that can be converted to a string. Here is the UDF function that matches the previous list of options, but this time, we added one, to be sure it is from the UDF.
Reload and test the widget, we see the list of Target Types.
You might see a side effect of adding the function. Now you will see another option, Public Methods with a list of public functions in ths CFC. Widgets are required to implement the default RenderIt() function, but the Widget can actually have several methods.
To hide this function ( since this is outputting an array, not a string ), you cannot use a private function ( otherwise the UDF cannot be called by the Form Builder ), you need to add some meta data to ignore the function.
or you could use the inline meta
With either of these two options, you will see the list of Options provided by the UDF, but you will not see the Public Methods option, as there is only 1 public rendering function.
Using Labels, Hints and Required fields helps the user, but in some cases its best if you can give your users a set list of options to pick from, especially if they user could/should pick one or more options. This will provide the user a multi select drop down box, instead of a text box. This ensures there are no typos.
To add options for an argument, add Javadoc Meta comment @urlTarget.multioptions _self,_blank,_top,_parent to the function meta.
MultiOptionsUDF works the same as OptionsUDF except the user can select none, one or more of the options.
Add the meta to the RenderIt() function
Add the UDF ( include the cbignore meta data so the Widget Form builder ignores the function )
Widgets can range from very simple to very complex, depending on what your goal with the widget is.
Let's build a simple widget, that takes no parameters or arguments from the user, it simply outputs a ContentBox Logo, wrapped in a link to the ContentBoxCMS webpage.
There are several things a Widget needs to work with ContentBox. We'll cover all of these items with a simple example. In other sections we'll look at more complex options you have as a Widget builder.
File in the right Location
CFC Definition and Extension of the BaseWidget
Widget Properties
RenderIt() Function
Remember: Widgets are loaded into memory when the Application is started. To make changes, please reinit your app, or Reload the App from the admin menu to see those changes.
First, you need to create a CFC, in a Widget loading location. In this example we're going to create a ContentBox Logo and Link. So we'll call it ContentBoxBadge.cfc
There are several locations for loading widgets, the main ContentBox core location is:
modules/contentbox/widgets
For now, that is a good location.
See the init line includes the name of the CFC. ContentBoxBadge function init() If you CFC was called GoogleLink your init line would be: GoogleLink function init()
Now when we look in the Widget list, and find our widget... this is what we'll see.
For ContentBox to know more about your widget, you should add some Properties to your widget. This is done in the Init() and can include the following.
Name: The Name of the Widget.
Version: A meaningful version number
Description: A short description of the widget and its use
Author: Author of the Widget
AuthorURL: The URL of the Author of the widget
Icon: This is the icon used by ContentBox. Icons are Font Awesome Icons. Refer to Font Awesome Website for a full list.
Category: This is the grouping the widget will be placed in. This is completely customizable, but the default groups are:
Blog
ColdBox
Content
Layout
Miscellaneous
Utilities
Now when we load Reload the app, and look at the widget list, you will see the details are filled out.
When you build a Widget, they are built to render something out to the user. To use a Widget, you must have a renderIt() function... and it must return something to the RenderData function that calls it.
At it's simplest, you can add this function under your Init()
Once we reload the app, we can test our Widget from the Widget Manager.
Lets build a logo and link in a string, and return that.
Now we reload, and then test it again
Lets add our widget into a page. Lets browse in the admin to Content > Sitemap and click on a page. Find the location in the text you would like to add your widget, and click the Green ContentBox Widget icon ( circled below ).
Pick the Widget out of the list, you can filter the widgets, or select by category ( as we defined in our Widget properties )
Click anywhere on the Widget itself, and the Insert Widget Dialog will open like the screen below.
If there were arguments, you could adjust them here. If this is the widget you want, and the preview looks good, click Insert Widget. Back to Widgets allows you to return to the Widget list to look for a different widget. Cancel returns you to the Content Editors.
Once inserted, click Publish, and then you'll see a Widget placeholder like this.
If you right click on the widget, you can get a Widget Context menu like below. You can edit, or remove a Widget through that context menu, or just double click the Widget placeholder to edit directly.
This example has no arguments or parameters to change, but if you did, you would be able to edit those here, and click Update Widget to save those changes.
You can preview the page using our Responsive Previewer which allows you to see what your page will look like, in desktop, tablet and phone views ( horizontal and vertical ).
When you are happy, ensure you save / publish your page to keep your changes. Once saved, you can view it on the front end of the website.
Widgets are required to provide one function called renderIt(), but they can actually provide more than one render option. If you add another function, then the display of the Widget Form changes.
Now you will see a Public Methods menu, with a list of public functions in ths CFC. Below you can see the required function renderIt() and the 2 additional functions. listOfPages() and listOfCategories()
When you select a different Method, the options change, depending on the function. This means you could have 1 widget, with several different display options... each with their own set of arguments. Packaging them inside a single Widget CFC allows them to easily share functions.
Above, you can see the renderIt() function has 1 arugment, with label, hint, required etc.
The
listOfPages()
function has 1 argument, a plain text field
numberOfPages
, as you can see below.
The
listOfCategories()
function has 1 argument, a plain text field
numberOfCategories
, as you can see below.
If you add a UDF to your Widget, to be able to dynamically create the select drop down for your Widget arguments, you might notice an unexpected side effect. This function / method shows up in the Select a Method drop down box.
Your first thought might be, to use a private function. The Widget form builder needs to call the UDF to generate the Select Boxes, so it cannot be a private function.
The solution, add Meta data about the function... including cbignore. You can add this with the function meta data in a comment.
Or you could add this meta data with the inline meta style.
With either of these two options, you will see the list of Options provided by the UDF, but you will not see the Public Methods option, as there is only 1 public rendering function.
