Creating Custom Widgets for dashEE
There’s a new ExpressionEngine (EE) add-on type in town and it’s name is Widget! We’re all familiar with the standard EE add-ons: modules, fieldtypes, accessories, extensions and plug-ins. But did you know there was an additional type that allowed you to customize the control panel homepage with your own content and functionality? It’s called a widget and in this post I’ll review how you can create your own widgets that work with the dashEE module to assemble your own custom EE control panel dashboard.
Before we get started it’s important to note that widgets are not a standard EE add-on type. To use them you first need to install the open source dashEE module which is a complete alternate dashboard with drag-and-drop functionality as well as saved layouts and a handful of other useful features. The module comes standard with about 10 included widgets but the true power lies in the ability to create your own custom widgets. Once created you can then distribute them either as stand alone widgets or package them with your modules to add extra functionality to your existing code.
Just like other EE add-ons, Widget file names are always preceded with wgt. and then the name of your file and followed by .php. In our example we’re going to build a widget that displays the most recent tweets from a selected Twitter feed. So if the name of our widget is Tweets then our file name will be wgt.tweets.php.
Widgets also require a language file. If the widget is being packaged with a module then you can use the modules language file. But if the widget is being distributed on it’s own you will either have to instruct the user to use dashEEs or include a language file with your widget. Each widget requires two language variables that follow your chosen naming convention: wgt_tweets_name and wgt_tweets_description. These variables are important to remember because they are used when displaying your widget in the widget listing of the module.
The code above shows the beginning of our widget file. Following the standard EE add-on naming conventions, our class name will always begin with Wgt_ and be followed by our file name which in this case is tweets. Each widget file should have at least two public class variables defined: title and wclass. The title variable is used to display the name of your widget in the widget title bar (across the top of your widget) and wclass is a placeholder for any additional CSS class names you wish to assign to your widgets container div. You can also add a settings variable if your widget has settings but we’ll discuss that later in the post. Beyond those three you will likely want a variable for the EE object and then any additional variables that you choose.
The only real required method within your widget file is index(). This is the method that gets called by dashEE when a user has installed your widget. After loading the widget file dashEE calls the index method and packages it’s return value within the CSS wrappings of a widget and puts it together with the other widgets to assemble the dashboard. So this method is required and it’s expected to return an HTML string. Back to our example, we’ll be using the Twitter API to get the most recent tweets from a chosen Twitter user for display and then returning them as formatted HTML.
That’s it, we’re done. For the sake of testing our example go ahead and add the two language variables to the dashEE language file and upload the widget file to the widgets directory of the dashEE module. Click the Widgets button and you should see Tweets listed. Click Install and you should see the widget added to your dashboard.
One topic that has caused some confusion is permissions. Obviously if a members group doesn’t have permission to access a given module then they shouldn’t be able to access that modules widgets either. To solve this problem there is an additional method you can add to your widget file called permissions(). For our example we only want Super Admins to have access to this widget so we’ll check the users group and return FALSE if they are not a Super Admin.
A widgets permissions method is called every time the widget is loaded which ensures as a members or modules settings/permissions change the dashboard will be adjusted appropriately. You can do whatever permission checking in this method you wish, all dashEE expects in return is a boolean true if the user should be able to access the widget or false if they shoudln’t. While it is recommended that you include a permissions method with your widget it’s not required.
Back to our example, the widget we have created is functional but not necessarily usable if the user has to modify the code every time they want to change the Twitter account they want to watch. To assist with this we can add a settings_form() method to our widget file to allow the user to modify the widgets settings from within the dashboard.
If your widget file has a settings_form method then an additional icon will be displayed when users mouse over it’s title on the dashboard. When clicked dashEE calls the settings_form method for the widget in question and displays it’s return value within the widget. It’s expected that this method return a form containing the settings that you want to allow the user to change.
For our example that’s going to be the Twitter username and the number of tweets the widget should display. It’s worth noting that it’s not necessary to specify the form action because the module will handle it’s submission via ajax and as for field names those are up to you. Just remember what you named your form fields because you will use those same names when referencing those settings back in the index method.
When adding settings to your widget it’s also important to declare default values for the settings in the widget constructor so your code has something to go off of when initially installed.
Now that we have our settings_form method squared away we can update the index method to reference our newly saved settings. dashEE saves all widget settings as a JSON encoded value along with the widget in the DB and that value is then decoded and passed to the index method through the $settings variable as an object. To learn more about settings you can reference the wgt.feed_reader.php and wgt.blank.php widget files in the Widgets directory as both have settings of their own or refer to the documentation.
That’s it, you’ve created your first dashEE widget. Feel free to download the completed code to refer to for help. Hopefully this has peaked your imagination and gotten you thinking about other cool things you can develop for dashEE. Visit the Widget Directory to see what other developers have created or submit your own widgets for others to download. As always post a comment with any questions or problems.