Write a Widget

My assumption is that you've installed dashboard using:
curl -s http://get.hoborglabs.com/dashboard/install | php.
and you can access it locally on http://board.local/dashboard.php?conf=demo

First, We Need Some json.

We need to start with simple configuration for our dashboard and our new widget

This is the simplest example of a dashboard with just one widget.

{
  "name": "Example Dashboard",
  "template": "hoborg",
  "tag": ["examples"],
  "widgets": [
    {
      "name": "This is my first widget",
      "size": "autoHeight span16",
      "php": "test/widget.php",
      "config": {
        "opt1": "val1"
      }
    }
  ]
}

Save it in boards/demo/config/example.json

Now you should be able to go to http://board.local/dashboard.php?conf=example. You will get a dashboard with empty widget, but ... with correct header. That's because dashboard used default widget template to display your widget's data.

Exercise 01

Create boards/demo/data/static_01.html and update widget JSON. Replace php with new static property.

{
  "name": "This is my first widget",
  "size": "autoHeight span16",
  "static": "test.html",
  "footer": "This is footer"
}

Now contnet of static_01.html will end up in the widget body.

Oh, and default template print's footer as well.

Let's write some PHP.

Now let's write some simple PHP class. Dashboard engine looks for PHP files inside widgets folder(s). Our widget config want to use test/widget.php, so let's create board/demo/widgets/test/widget.php.

<php

// my widget
class Widget extends \Hoborg\Dashboard\Widget {
  public function bootstrap() {
    // build widget's data
    $this->data['data'] = $this->getWidgetData();

    // get widget's template
    $this->data['template'] = $this->getTemplate();
  }

  protected function getWidgetData() {
    return array('title' => 'This is my title');
  }

  protected function getTemplate() {
    return '<div class="header">{{name}}</div><div class="body">Title: {{ data.title }}</div>';
  }
}

But what about that config property? Let's use it

protected function getWidgetData() {
  $config = $this->getData('config', array());
  $title = empty($config['title']) ? 'Default Title' : $config['title'];

  return array('title' => $title);
}

protected function getTemplate() {
  $config = $this->getData('config', array());
  $tpl = empty($config['tpl']) ? 'simple' : $config['tpl'];

  return file_get_contents(__DIR__ . "/{$tpl}.mustache");
}

And here's board/demo/widgets/test/simple.mustache

<div class="header">{{name}}</div>
<div class="body">
  <div class="panel">{{data.title}}</div>
</div>

Exercise 02

Create new template boards/demo/widgets/test/advanced.mustache and switch to new view from widget JSON.

Exercise 03

Create boards/demo/data/testdata.json and put some valid JSON in it. All widget objects have access to Kernel. You can use it for instance for finding files.

  protected function getExtraData() {
    $config = $this->getData('config', array());

    if (empty($config['datafile'])) {
      return array();
    }

    // let's look for our file
    $datafile = $this->kernel->findFileOnPath($config['datafile'], $this->kernel->getDataPath());
    if (empty($datafile)) {
      return array();
    }

    $json = file_get_contents($datafile);
    return json_decode($json, true);
  }

Now simply update widget config and template and that is it.

{
  "name": "This is my first widget",
  "size": "autoHeight span16",
  "php": "test/widget.php",
  "config": {
    "datafile": "testdata.json",
    "tpl": "advanced"
  }
}

Mustache Template.

Your mustache template has access to entire widget JSON object. And you have access to entire widget object from PHP!


<div class="header">{{name}}</div> <div class="body"> my widget wicked body </div>