Building custom widgets
The Social Media and Widgets modules have become pretty popular in the months since they launched. The feature request queues have been filling up. Mostly with requests to customize widgets or add new ones.
The modules already support a variety of ways to add new and custom widgets on your own. There are two ways to create your own widgets; coding them in modules using the Widgets and Social Media APIs or adding them via Drupal's UI using the Widget definition admin. While the UI approach has some limitations, it is remarkably flexible and works well as a simple way to add most widgets you might need or to customize those provided by other modules.
It's Alive – Experimenting with Widgets
At their most fundamental level widgets are just snippets of markup code. The Widget module encapsulates these snippets into widget definitions. Definitions store the code templates and any other data related to making the widget work. Once a definition has been created, the widget can be reused and customized in many different ways on the site.
To create a new widget definition simply install the widgets module and go to admin > structure > widgets > definitions and click on the + Add new definition link. If you have a module that provides widget definitions like the Social Media module you can clone those definitions to see how they are built.
Once you have a definition created you have two options from the definition admin page (admin > structure > widgets > definitions). The operations edit link allows you to alter the definition. By clicking on the name of the definition you are taken to a preview. The preview shows you the how the widget will display, the input and rendered version of the code and provides a form containing any widget custom configuration settings. You can change configuration settings and see how the widget reacts. Using the widget edit and preview forms together gives you a lot of control for tweaking your widget definition.
Widget templates
The definition template is the meat of the widget definition. It is where the code snippet is stored. Templates can be as simple as static cut and paste code. For example you can use the below code from Twitter to create a Tweet button. Go ahead and try these code examples out in the widget definition admin to see how they work.
While widget definition built using static templates might prove a convenient, simple way to organize your site's code snippets, the real power of widget templates is the ability to add in dynamic elements. Widgets support Drupal core's de-facto system for dynamic data, tokens. You can use tokens to make widgets more adaptive. For example, in our Tweet button we might want to customize the Tweet message by using the data-text attribute. Note, I have left off the JavaScript portion of the code to save space.
When this widget is displayed the tokens will be replaced with dynamic data from your site. In the widget definition preview form you can click the tweet button to see the results.
There are times though where you want to allow admins to easily customize the widget without having to know the code structure. Widget templates support a variables syntax that will auto generate fields in a configure form for admins to easily make changes. Template variables are denoted by using brackets and question marks as follows:
[?key=default_value?]
In our Tweet button example, we might want to allow admins to specify a via Twitter handle using the syntax
Tweet
The above code introduces a variable configuration "via". By default it is blank. You could set the default to a literal value or a token. When the widgets system encounters a variable it adds a field to the configuration form for that widget. You can see an example of the configuration form on the widget preview form (admin > structure > widgets > definitions > [name of definition]). Site administrators can access this form on a real widget from the widget set editor (admin > structure > widgets > [name of a set])
One issue you might run into with a widget is that you want to implement a variable attribute but when it is blank you want to remove the attribute all together. In the code above, even if you leave the via variable blank, the code would still render as data-via="". If you want to remove the entire attribute when no value is given you can use the following structure:
In the above variable structure the entire data-via attribute is contained within the variable markers. The configurable part of the code is contained within curly brackets. If the value of via is set to <none> the entire attribute is removed.
Getting more advanced
The widgets definition UI provides a great deal of flexibility for creating widgets. However there are times where you might want to do more advanced things. For example you might want to customize the configuration form. To do that, you will need to code your widget into a module (hint, use the definition export) and use hook_widgets_element_alter. This is just one example. The widgets module has several APIs to support advanced configuration.
In a future post I will review the APIs. For now, it helps to look at how the Social Media module implements the Widget APIs.
Got a great widget
If you have worked out a great widget definition you think would be helpful for others, go ahead and export it and send it to me. The Widgets or Social Media issues queues on drupal.org are the best place to submit new widgets ideas.
