Here is a listing of the core widgets in ContentBox. You can find much more information about them in the API Docs
Widget
Description
Archives
A widget to render blog archive links
Categories
A widget to render out blog categories with counts
cb
Access to the ContentBox Helper object and its methods
CommentForm
Generate a comment form
ContentStore
Render a content store object
EntryInclude
Include a blog entry content wherever you want
Menu
Render a ContentBox defined menu
Meta
Render out basic ContentBox meta links like login, logout, etc.
PageInclude
Include page content wherever you want.
RecentComments
Show n recent comments
RecentEntries
Show n recent blog entries
RecentPages
Show n recent pages
RelatedContent
Render links to related content pages or blog entries
Relocate
Do a browser relocation to another page
Renderview
Render a view anywhere in the ColdBox application
RSS
Reads an RSS feed and displays the items as a list or summary list
SearchForm
Render out a search form
SubPageMenu
Renders a sub page menu according to rendered context
Viewlet
Execute and render ANY ColdBox event
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 are small pieces of software that you can add to your ContentBox website to perform a specific function. A widget is simply a ColdFusion Component (cfc) that extends our core widget (contentbox.models.ui.BaseWidget) and lives in a specific location where ContentBox can register it. It must have at least one rendering function called renderIt() and it has full access to WireBox dependency injection and helper objects.
There are several Widgets built into ContentBox (Core Widgets) 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.
The Base widget has been created with some properties and injections in order to help you in development.
The following are the optional base properties defined for all widgets.
All widgets receive the following injections that you can leverage in your code. Please refer to the API Docs for further reading on the dependencies.
Widgets are maintained through the Administrator under Look & Feel > Widgets. You can manage existing widgets, upload new widgets, or download widgets from Forgebox as well.
The manager also allows you to read the widget's documentation and actually test out its rendering functions. So please use this playground to your advantage.
Widgets can exist in many locations depending on your needs. They can also be discovered when used as markup in your ContentBox editors (More on this later)
/modules/contentbox/widgets
Core widgets are widgets that exist inside the ContentBox core module and are shipped by the version of ContentBox installed. These widgets should not be modified or you should not really place custom widgets here. Check out the Api Docs for further information.
/modules_app/contentbox-custom/_widgets
Custom widgets are your very own widgets that you will program to enhance ContentBox. These should definitely be in source control and are managed by you!
Module widgets are widgets that live inside ContentBox Modules not vanilla ColdBox modules, ContentBox MUST know about the module. They can come from core or custom module registrations. All you need to do is place the widgets inside a widgets folder in the root of the module.
Important: If you put modules outside of the ContentBox conventions they will not be inspected and registered.
The currently active theme can also do widget contributions. If the theme package contains a widgets folder in its root, then all of those widgets will also be registered in ContentBox.
Important: Please note that if you use theme widgets in your content and you switch themes, you could have nasty exceptions or warnings in your content.
Widgets are rendered in your UI when you place them in content via the editors or manually using our triple mustache markup. The UI approach can be seen in the Using ContentBox Section. The Markup notation is shown below, please note that the name of the widget has meaning:
By default, the WidgetName will be searched for in the following locations by convention:
Custom Location
Active Theme Location
Core Location
If the widget cannot be found in either of those locations an exception will be thrown.
If you want a widget from a module rendered then you need to give it the address of the module like so:
If you want a widget from the current theme explicitly then give it the ~ address:
You can manually render widgets outside of content by leveraging the CBHelper's widget() method:
This method calls the renderIt() method by convention. If you want more control, then retrieve the widget instance and use it.
If you want to use the widget, then retrieve it using the getWidget() method from the CBHelper.
Please note that the name of the widget is important as ContentBox will try and figure out the location of the widget. Please refer to the Widget Discovery section above.
Widgets can range from very simple to very complex, depending on what your goal with the widget is.
Important: Widgets are self-contained and reusable. If you need to break your widget into more files or needs more files for it to work, then consider refactoring the widget into a .
DO NOT CREATE !
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 for loading widgets, the custom ContentBox core location is:
/modules_app/contentbox-custom/_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
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.
Let's build a logo and link in a string, and return that.
Now we reload, and then test it again
Let's add our widget into a page. Let's 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 argument, 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.
Icon: This is the icon used by ContentBox. Icons are Font Awesome Icons.
