Widgets
Last updated
Was this helpful?
v4.x
Last updated
Was this helpful?
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 dependency injection and helper objects.
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.
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.
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
/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.
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.
All widgets receive the following injections that you can leverage in your code. Please refer to the for further reading on the dependencies.
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 for further information.
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 Section. The Markup notation is shown below, please note that the name of the widget has meaning:
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 section above.
