Creating Widgets

dashEE comes with a number of default widgets including:

Blank Widget – empty widget whose title and content can be configured using widgets settings
EE Create Links – create links as seen on default EE CP home
RSS Feed Reader – configurable to read any valid RSS feed
EE Modify Links – modify links as seen on default EE CP home
New Members – shows 10 most recent EE website members
Recent Entries – shows 10 most recent EE entries
EE View Links – view links as seen on default EE CP Home
dashEE Welcome – welcome widget with links to further resources

The true power behind the module is when you start developing your own widgets either as stand alone tools or as part of your custom modules.

Each widget you develop must be part of a module, whether they are really part of that module or not. If you are developing a stand alone widget you can simply place the widget file in the “widgets” directory of the dashEE module (/system/expressionengine/third_party/dashee/widgets). You could also build a blank module with a “widgets” directory and that would accomplish the same thing.

You can save yourself some time and get a jump start on your widget development by downloading the dashEE widget boilerplate. This widget template will get you up and running quickly.

Getting Started

Create a new widget file called wgt.test_widget.php. Note we are using a similar naming convention to that used by EE to create add-ons.
Create a new class called Wgt_test_widget in your file. Each widget file must have at least 2 things: a title variable which is used to display the widget title and a function called index.
```
<?php
class Wgt_test_widget
{
    public $title;

    public function index()
    {

    }
}
```
In the index function we created set the value of the title variable to whatever you want to display as the title of your widget and return whatever text you want displayed in the content area (formatted as HTML).
```
<?php
class Wgt_test_widget
{
    public $title;

    public function index()
    {
        $this->title = 'Test Widget';
        return '<p>This is a test widget.</p>';
    }
}
```
Now that we have our widget we need to add the widgets name and description to the language file for the ‘installer’. This is what will display when users click Widgets from the dashboard and see all available widgets for them to add. Open the language file for the dashEE module (/system/expressionengine/third_party/dashee/widgets/language/english/lang.dashee.php) and add the following 2 new lines to the bottom of that file:
```
'wgt_test_widget_name' => 'Test Widget',
'wgt_test_widget_description' => 'This is the test widget I just developed.',
```
Save your changes and upload your widget file to the ‘widgets’ directory of the dashEE module (/system/expressionengine/third_party/dashee/widgets) and update the language file as well.
Log in to EE and click Widgets on the top right of the dashEE dashboard. You should now see the widget we just added in the list. ClickAdd next to it and you should see it added to your dashboard.

Creating Advanced Widgets

The above was an example of creating a simple widget that just displays text. But what about creating widgets that can actually do things? Creating widgets like the included RSS feed reader and blank widget requires adding settings to your widget. For this example we’re going to dissect the RSS feed reader widget. Open the RSS feed reader widget located at /system/expressionengine/third_party/dashee/widgets/wgt.feed_reader.php to follow along.

The first thing to notice is that we have added a new class variable called settings and loaded it with an array in the constructor. This variable is what dashEE looks for when determining if your widget is dynamic or static. When adding settings to your widget you must always provide defaults in the constructor and those defaults are saved to the users dashEE settings when the widget is first added to their dashboard.

class Wgt_feed_reader
{
    public $title;
    public $settings;

    /**
     * Constructor
     */
    public function __construct()
    {
        $this->settings = array(
                  'url' => 'http://expressionengine.com/feeds/rss/eeblog/',
                  'num' => 5
                  );
    }

The index function of this widget actually contains some logic instead of just returning static content like the first example. You will notice that you can still gain access to the EE object by using the get_instance() function just like in modules and other EE add-ons. So this index method uses the values stored in settings to go and get the contents of an RSS feed and return it as an unordered list. One thing to note here is that settings is passed as an argument to index. It’s important not to overlook this because if you do then dashEE will be unable to pass the users saved settings to your widget upon load.

public function index($settings = NULL)
{
    $EE = get_instance();
    $EE->load->helper('text');

    $rss = simplexml_load_file($settings->url);

    $display = '';
    $i = 0;
    foreach($rss->channel->item as $key => $item)
    {
        if($i >= $settings->num) { break; }

        $link  = trim($item->link);
        $title = trim($item->title);

        $display .= '<li>'.anchor($link, $title, 'target="_blank"').'</li>';
        ++$i;
    }

    $this->title = ellipsize($rss->channel->title, 19, 1);

    return '
        <ul>'.$display.'</ul>
        ';
}

Finally there is a new method in this widget called settings_form(). This method is called when a user click the settings icon for your widget. At this time you simply need to return an HTML form with fields named the same as the default settings you provided in the constructor and that’s it. dashEE takes care of displaying the form and saving the users settings in the database.

public function settings_form($settings)
{
    return form_open('', array('class' => 'dashForm')).'

        <p><label for="url">Feed URL:</label>
        <input type="text" name="url" value="'.$settings->url.'" /></p>

        <p><label for="num">Number of Posts:</label>
        <input type="text" name="num" value="'.$settings->num.'" /></p>

        <p><input type="submit" value="Save" /></p>

        '.form_close();
}

Widgets and Permissions

Not all widgets are created equal. It’s possible that even though a module is installed you may still not want a user to be able to add a given widget to their dashboard unless they have certain permissions. This can be accomplished by adding an additional method to your widget files called permissions(). The example below is from the EE Create Links widget (wgt.create_links.php).

public function permissions()
{
    if(!$this->_EE->cp->allowed_group('can_access_publish') && (!$this->_EE->cp->allowed_group('can_access_edit') && !$this->_EE->cp->allowed_group('can_admin_templates')) && (!$this->_EE->cp->allowed_group('can_admin_channels')  && ! $this->_EE->cp->allowed_group('can_admin_sites')))
    {
        return FALSE;
    }

    return TRUE;
}

If your widget has a permissions() method that method will be run before allowing users to add the given widget to their dashboard. You can add any logic you want in the permissions method as long as you return TRUE for the user can access the widget or FALSE if they cannot. You can see examples of implementing permissions in the create, modify and view link widgets included with the module.