An Introduction to the world of OctoberCMS Widgets

An Introduction to the world of OctoberCMS Widgets

Highly customizable, easy to use, robust security and breakthrough performance, are a handful of many reasons that works behind the popularity of OctoberCMS. One of the most competitive CMS platforms, OctoberCMS has been a preferred pick for many, against its top-notch competitors. Being an active member of OctoberCMS community ever since 2016, AddWeb has so far successfully accomplished 5+ projects and contributed 1 plugin. All of these and 500+ man hours of OctoberCMS-ing, we consider us to be eligible enough to share our tips and information surrounding OctoberCMS.

 

Recently, we were working on one of our projects and the thought of the widgets playing an instrumental part in building an OctoberCMS website, crossed our mind. So, let us speak and share something about them today.

 

What are OctoberCMS widgets?

Widgets are the self-contained blocks of functionality, which helps in solving different tasks. A back-end controller prepares the widget data, along with handling the AJAX requests. It also always have the user interface.

 

Widgets are useful for both the back-end as well as front-end. Widgets can furthermore be categorized under three main types, as follows:

  1. Generic Widgets

  2. Form Widgets

  3. Report Widgets

Let us now share some details on each of the above-mentioned widget types.
 

1) Generic Widgets

  • They are the bundles of functionality, which can be injected to the page.

  • They act like components and stored inside the widgets folder.

  • They’re the modular bundles of functionality, supply partials and are given the titled using aliases.

  • They are the back-end equivalents of front-end components, whose only difference is the use of YAML extension that bank-end widget uses for configuration for binding the backend pages.

  • The widget classes are saved in the widgets directory, which is a part of the plugin directory.

  • The directory name matches the widget class name, which is written in lowercase.

  • Widgets are able to supply the assets and the partials.

Widgets Directory Structure:

An Introduction to the world of OctoberCMS Widgets

Class Definition:

  • It is compulsory for the generic widget classes to extend with the Backend/Classes/WidgetBase class.

  • When any other plugin class, generic widget controlled should always belong to the plugin namespace.

Below is the illustrious image of widget controller class definition:

An Introduction to the world of OctoberCMS Widgets
  • It is compulsory for the widget class to have a ‘render()’ method in order to produce the widget markup by rendering the widget partial.

Below is the illustrious image of the widget controller class with the ‘render()’ method:

An Introduction to the world of OctoberCMS Widgets
  • Pass variable in partials (view file)  you can either add them to the $vars property.

Below is the illustrious image of the pass variable in partials:

An Introduction to the world of OctoberCMS Widgets

2) Form Widgets

  • They’re the special kind of widgets in OctoberCMS.

  • They open up the opportunity to create new control types, which can be later used by other plugins/CMS.

  • They are used for adding new control types to the back-end forms.

  • They come with features that are commonly used in supplying data for models.

  • They must be registered in the Plugin.php file.

Form Widget Properties:

  • There are a few core properties of form widgets, which are used in the form field configuration.

  • One needs to first define the properties that are configurable on the class and later call the fillFromConfig method, in order to populate them inside the init method definition.

Below is the illustrious image of Form Widget Properties:

An Introduction to the world of OctoberCMS Widgets

This is the property set in the form field definition value when you’re using the widget.

An Introduction to the world of OctoberCMS Widgets

Form Widget Registration:

  • The plugins are required to register the Form Widgets inside the Plugin registration class by overriding the registerFormWidgets method.

  • The registerFormWidgets method returns an array containing the widget class in the keys and widget shortcode as the value.

Below is the illustrious image of the registerFormWidgets:

An Introduction to the world of OctoberCMS Widgets

Loading Form Data:

  • The core purpose of formWidgets is loading data from the model and store the value in the database.

  • Once a form formWidgets is rendered, a request is initiated for the store value with the use of getLoadValue method.

  • The getId and getFieldName methods will come back with a unique identifier and a name for the HTML element used in the form.

  • At the time of rendering, all these values are passed to the widget partial.

An Introduction to the world of OctoberCMS Widgets
  • All in all, formWidgets helps in sending across the user input value back with the help of an input element.

  • In the example shared above, inside the myformwidget partials, the elements can be rendered from the defined variables.

Below is the illustrious example showing the method of passing the variables in partial:

An Introduction to the world of OctoberCMS Widgets

Saving Form Data:

  • At the time of taking the user input and store the same in the database, form widget will call the getSaveValue() and make an internal request in order to receive that value.

  • If you wish to modify this behaviour, you can simply override the method in your form widget class.

An Introduction to the world of OctoberCMS Widgets
  • There are certain cases, which you do not want to give a value to. For example, a form widget that displays information without really saving anything.

In order to do ignore that value for the class, one needs to return the special constant called FormField::NO_SAVE_DATA, which is derived from the Backend\Classes\FormField.

An Introduction to the world of OctoberCMS Widgets
  • Create the formWidget with the use of the command.

  • The create:formwidget command generates a back-end form widget, view and basic asset files.

  • The first parameter specifies the author and plugin name while the second parameter specifies the form widget class name.

An Introduction to the world of OctoberCMS Widgets

3) Report Widgets

  • They are the most popular kind of widgets.  

  • They are helpful in adding specific context-based content.

  • They can be used both, on the back-end dashboard as well as in other back-end report containers.

Report Widget Classes:

  • Report Widgets classes should extend from the Backend\Classes\ReportWidgetBase class.

  • Report Widgets classes should override the render method in order to render the widget itself.

  • Report widgets use partials and a special directory layout.

Below is the illustrious image of this special directory layout used by Report Widget:

An Introduction to the world of OctoberCMS Widgets

Below is the illustrious image of the Report Widget class definition:

An Introduction to the world of OctoberCMS Widgets

Report Widget Registration:

  • Plugins can register Report Widgets by overriding the registerReportWidgets method inside the Plugin registration class.

  • registerReportWidgets method returns an array containing the widget class in the keys and widget shortcode as the value.

Below is the illustrious image of the registerReportWidgets:

An Introduction to the world of OctoberCMS Widgets

Hope the above blog helped you in clearing the concept of OctoberCMS Widgets. If you still have a query and wish to learn more about it - drop us a message. If you want to make a suggestion on the above-shared information - drop us a message. We’re all ears!