photo credit: Time is Relative via photopin (license)

Creating Widgets in Magento 2

One feature of Magento that is not as often used as it should be are widgets. Widgets are configurable blocks that can be added to the content in wysiwyg editors in the admin. This gives us great possibilities to add rich content with the wysiwyg-editor without having to manually edit the HTML code. Because having your client edit the HTML code of your content is a recipe for disaster.

Widgets were already present in Magento 1, but in this article I’ll show you how to add widgets in Magento 2

Please note that we use the boilerplate module from the article ‘Creating a module in Magento 2‘ as the entry point for this article. If you never creating a block in Magento 2 before I also suggest to read this article first.

Declare your widget

The first thing you need to do, is let Magento know that you have widgets in the first place. The declaration of widgets is done in a file called widget.xml  in the etc -folder of your module:

Widgets have 2 required parameters:

  1. label: This is the name of the widget as it appears in the dropdown when you select a widget.
  2. description: This is a short description that is shown as soon as you select your widget.

Create your widget class

Note that when declaring our widget we also provided a class: Gielberkers\Example\Block\Widget\Example . This is the class that Magento will use to render the widget. So let’s just take a look at that class shall we?

Now that we created our declaration and our class, we can now …

Use your widget in the Wysiwyg editor

If you didn’t know already how to implement a widget with the wysiwyg-editor, let me show you again:
In the wysiwyg-editor, there is a small little button on the upper-left corner. Actually, it’s the second button (the first one is for variables):

Screen Shot 2016-04-01 at 08.28.43
When you click on this button, a panel appears in which you can select your widget:

Screen Shot 2016-04-01 at 08.29.27
That’s it! Insert the widget, save your page (or static block) and take a peek at the frontend. It’s pure magic.

Adding parameters to your widget

It is also possible to add parameters to your widget. This way, you can give your clients means to customise the widget:

Now, if you now go back to the wysiwyg-editor and edit the (or add a new) widget, you’ll see that we’ve created an input field for our user:

Screen Shot 2016-04-01 at 08.39.23
We can access the data inside our widget class by using Magento’s magic methods:

Edit the widget, save the page, and take a peek at the frontend. Pure magic!

Different type of widget parameters

Not that we only created a parameter of the type ‘text’. Needless to say there are more parameters than just that. Some examples:

  • select, for a dropdown
  • multiselect, to select multiple options at once

Source models

One cool feature you can use in your widgets are source models. You can use source models to provide options of a ‘select’-parameter type. Just look at the following example of a parameter:

This parameter uses the source model Magento\Config\Model\Config\Source\Yesno . Let’s take a look at this class:

The key function here is toOptionArray() . This method returns an array that is used to populate the <select> -attribute:

Screen Shot 2016-04-08 at 08.22.08
There are a lot of source models you can use throughout Magento, just look in any given module if there is a Model\Config\Source -folder, and you’ll see there are a lot of source models out of the box that you can use! But you can also write your own source model of course:

Use it in your widget.xml:

Needless to say, this is how it is rendered in the admin:

Screen Shot 2016-04-08 at 08.21.47
And you can use it in your block class by calling $this->getExample() .


You can also set field dependencies in widgets. This means that one field may only be visible if another field has a certain value. You declare these in the widget.xml file. Here’s an example that shows a category picker depending on another dropdown:

Now, the thing that does the magic in this widget is the following line:

What it says is: “If the parameter ‘choose_category’ has the value ‘1’ then make this field visible, hide otherwise.”. This can be seen when you put it to work:
This is of course a great way to simplify some of the more complex options of your widget, so that it’s better manageable.

This post is part of the series Magento 2 Development from Scratch.

Visitors give this article an average rating of 3.9 out of 5.

How would you rate this article?

2 thoughts on “Creating Widgets in Magento 2”

  1. Tommy Kolkman says:

    You might want to look in the “template” node as well, it gives you the power of using different templates within one widget. When using it in a responsive theme, for example, this might come in handy if you need different markup for mobile and / or desktop.

    1. Giel Berkers says:

      Thanks for the tip! I’ll look into it!

Leave a Reply