Building a Craft CMS Dashboard Widget
Ryan populates the widget with dynamic content from the Craft Deprecator service, uses the UrlHelper to create a CP URL, and more.
The first thing I want to do is fix the name of the widget. The default name is the class name, as you can see from the PascalCased name, which matches our class name.
Let’s create a better name to display there. We do that using a static method in our widget class file called displayName()
.
This static method will return the name of the Widget, as defined by us.
At the top of our DeprecWidget
class file:
public static function displayName(): string
{
}
This method returns the name of the widget as a string that we define. We’ll keep it simple and not worry about translations at this point, just returning a simple string.
public static function displayName(): string
{
return "Deprecation Warnings";
}
If we reload the dashboard, we’ll see the name update. This name changes even without instantiating a new widget because the name is called from a static class method.
Now let’s address the content of the widget. We see this silly graphic because we don’t have any HTML set to display. This is the placeholder that Craft provides to us. We’ll update the widget title and body content to make it functional for its purpose.
displayName
The displayName()
method provides the main name of the widget. This display name shows in the Add Widget drop-down and in the widget itself unless we specify a widget title.
In our widget, I don’t want to show the name of the widget in the widget because it’s not helpful information. We’ll have other copy there that will let the user know the context of the widget.
We could blank out the returned value of displayName()
but it is needed elsewhere in the CP, so we’ll that. Instead, we’ll define the widget title using the getTitle()
method from the parent class.
public function getTitle(): string
{
return '';
}
Instead of returning the name of the widget, we’ll return an empty string.
Now we can focus on the main content of the widget. This could anything you can do in HTML and PHP and will vary by widget. We’re going to display the number of deprecation warnings and some helper text for our widget, so it’s clear what the number means.
We tell the widget what to display using the getBodyHtml()
method. This is a method that we set in our widget class that overrides the same method in the base Widget class that we’re extending.
This method returns a string containing the HTML that we want the widget to render. For right now, we will return a simple string of HTML with some styling. Later on, in the course, we’ll use a twig template in our widget to make that a bit easier to maintain.
public function getBodyHtml(): string
{
return "<div class='centeralign'><h2 style='font-size:3rem;'>10</h2><p class='centeralign'>deprecationswarnings to address.</p></div>";
}
We now have a simple layout with a large number and some microcopy to explain the number.
The next step is to make the deprecation warning number dynamic and fed from a Craft service.
In Craft we have access to the Deprecator service via a trait called getDeprecator()
. The service has a method called getTotalLogs()
, which is perfect for our needs!
First, let’s import the main Craft class in our widget class.
use Craft;
And then, we’ll set the value of the total logs to the variable count
. And use a string interpolation to output the value of count
.
public function getBodyHtml(): string
{
$count = Craft::$app->getDeprecator()->getTotalLogs();
return "<div class='centeralign'><h2 style='font-size:3rem;'>10</h2><p class='centeralign'>deprecation warnings to address.</p></div>";
}
And now, if we reload the dashboard, we should see it populate with a deprecation warning! As a side note: I put some code in the index template of this Craft installation with intentionally incorrect Twig code so we’d get at least one deprecation warning to test with.
This setup with just a string of text as HTML isn’t ideal, but we’ll fix that up in a later video and refactor this to use templates instead of the current implementation.
I’d also like to have a way for someone to link off right to the deprecation warnings page in the control panel and see what’s going on.
Let’s create a button that links off to the deprecation warning page. We’ll just use simple markup here:
<p><a class='btn small' href=''>Review and Fix</a></p>
We’ll add it to our existing markup.
public function getBodyHtml(): string
{
$count = Craft::$app->getDeprecator()->getTotalLogs();
return "<div class='centeralign'><h2 style='font-size:3rem;'>10</h2><p class='centeralign'>deprecation warnings to address.</p><p><a class='btn small' href=''>Review and Fix</a></p></div>";
}
To get the URL of the deprecation warnings page in the Control Panel’s Utilities section, we need to first import the UrlHelper
class from Craft and then use it to generate a URL with the URL path.
use craft\helpers\UrlHelper;
public function getBodyHtml(): string
{
$count = Craft::$app->getDeprecator()->getTotalLogs();
$deprecUrl = UrlHelper::url('utilities/deprecation-errors');
return "<div class='centeralign'><h2 style='font-size:3rem;'>10</h2><p class='centeralign'>deprecation warnings to address.</p><p><a class='btn small' href='{$deprecUrl}'>Review and Fix</a></p></div>";
}
We just need to reload the dashboard, and the button works!
Building a Craft CMS Dashboard Widget is made up of the following videos: