Building a Craft CMS Dashboard Widget
We tweak the widget behavior by only allowing a single instance, adding a widget icon, and limiting the column span.
We have a nice, simple but helpful widget now. However, I want to tweak a few more things before we wrap up this first version. Let’s jump in.
With some widgets, you want to allow as many instances of the widget as a user desires. And, by default, Craft’s widget class will allow that. However, it doesn’t make much sense to allow multiple instances of this deprecation warnings widget. One is enough, so let’s constrain it so there can only be a single instance of the widget at a time.
In the base Widget class, there’s a static method called allowMultipleInstances() that returns a boolean. By default it returns true unless we override it to return false in our own class. Let’s do that.
In the DeprectWidget.php class file, we’ll add some new code to override that base class method:
protected static function allowMultipleInstances(): bool
{
return false;
}
Now when we refresh the dashboard and try to create another instance of the widget, it’s no longer available in the drop-down. If we remove the copy we have, then it’ll show up again!
Right now we are using the default icon that Craft provides for our widget. This is the first letter of the widget name in a circle style. Let’s do something custom for this using an SVG image.
To get started we need to use the icon() static method that is part of the base Widget class. We’ll override it with our own and show our custom icon.
Up near the top of the the DeprecWidget.php class file, let’s add a new static method for the icon:
public static function icon()
{
}
And to define the icon we want to to use for this widget, we need to return the icon file.
I know that Craft already has an icon associated with the Deprecation Warnings in the Control Panel. If I navigate over to them, we see that it uses the little bug SVG icon. In the interest of making things simpler and the UI uniform, let’s just borrow that icon.
Since Craft CMS already set up an alias to easily access that icon, we’ll call it directly via the alias Craft already has created, so it’s just a simple one-liner:
public static function icon()
{
return Craft::getAlias('@appicons/bug.svg');
}
Now let’s clear the widget instance we have right now and reload the page to see our change. Looking at it, we now see our custom icon in the right place!
Our last final tweak is to control the number of columns that we want our widget to display.
After creating a new instance of a widget, we can resize it to one or more columns using the gear menu.
We can safely ignore this and let the widget grow to whatever size the user desires. However, this simple widget has no increased helpfulness at full width, so let’s restrict it to just 2 columns.
We need to add a static method to our widget class that lets us define the maximum column span.
public static function maxColspan(): int
{
}
This method returns an integer with the number of columns we want to restrict to. So let’s return 2.
public static function maxColspan(): int
{
return 2;
}
When we reload the control panel dashboard and try to adjust our widget width, it’ll let us change it wider than our max column-span but when we reload, the widget is always constrained to the max-width we set.
We have a nice, fully functional, and practical widget that we can use in our project. DeprectNotifier is super handy as a default module while developing a Craft-powered web development project.
Congrats on building your first widget!
Building a Craft CMS Dashboard Widget is made up of the following videos: