Creating Dashlets

From Sit
Jump to: navigation, search
Broom icon32.png This article (or section) needs work.
Please help us and our readers by clicking the edit link above and expanding/improving this text.

Your dashlet is a regular PHP script, place your dashlet in the plugins/ directory giving it a .php extension as normal

Contents

Naming your dashlet

You should pick a unique name for your dashlet using only lower case letters (no numbers or symbols), the name is used in the filename and in the functions used within your dashlet.

Your dashlet filename should be of the format dashboard_foobar.php, where foobar is your dashlets unique name.

Your main dashlet function dashboard_dashlet()

Every dashlet should define a function that must be named dashboard_foobar, where foobar is the unique name of your dashlet. This function would normally make a call to dashlet() (See below) to draw the dashlet on the dashboard. e.g.

$dashboard_foobar_version = 1;

function dashboard_foobar($dashletid)
{
    $icon = icon('statistics', 16);
    $title = 'Foo Bar';
    $link = 'about.php';
    $content = '<p>Hello World</p>';
    echo dashlet('foobar', $dashletid, $icon, $title, $link, $content);
}

The parameter $dashletid is required, SiT will pass your main dashlet function a string which is to be used be used in the windowbox of the dashlet, and elsewhere.

dashlet()

The SiT function dashlet() can be used by your dashlet to draw a dashlet windowbox with a title and an icon.

Syntax:

echo dashlet($dashlet, $dashletid, $icon, $title, $link, $content);

Where $dashlet is the unique name of your dashlet and $dashletid is the unique name of your dashlet, $dashletid is the ID string that you received from SiT as a parameter to your main dashlet function call (See above). $icon should be a string containing a HTML image tag (<img>) for a 16x16 icon to display on the dashlet windowbox. $title should be a string containing the title to use. $content should contain the HTML of anything you want to display within the dashlet windowbox. (You can omit $content if your dashlet is to auto-refresh, see dashboard_dashlet_display() below.

Making your dashlet refresh with dashlet_dashlet_display()

Optionally SiT supports refreshing dashlet content via an AJAX call, this is very easy to do, simply set up your main dashlet function to call dashlet() as described above, and then define a new function in your dashlet named dashlet_foobar_display(), where foobar is the unique name of your dashlet. e.g.

function dashboard_foobar_display()
{
   echo "Hello World @ ";
   echo date('H:i');
}

That's it! That's all you need to make your dashlet refresh automatically and to add a manual refresh icon. If you have defined any content in your call to dashlet() (See Above) it will be overwritten by the content you echo in your dashlet_dashlet_display() function.

Adding an 'edit' button to your dashlet refresh with dashlet_dashlet_edit()

Optionally SiT supports an edit button, which can be added to your dashlet to provide the ability for users to configure your dashlet. To add an edit button simply define a new function in your dashlet named dashlet_foobar_edit(), where foobar is the unique name of your dashlet. e.g.

function dashboard_foobar_edit($dashletid)
{
   echo "Configuration example";
   // More code here
}

This simple example isn't very useful, all we've done so far is display some alternative content (the text "Configuration example") when the edit button is pressed. For a more useful configuration window, we need a HTML form and a call to dashlet_link().


function dashboard_foobar_edit($dashletid)
{
   echo "<form id='foobarform' action='{$_SERVER['PHP_SELF']}' method='post'>";
   echo "<input type='text' name='configuration' />";
   echo "</form>";

   echo dashlet_link('foobar', $dashletid, $linktext, 'edit',  ... ...

}

Versioning dashlets

If you make any changes to the dashlet and change the version number

 $dashboard_foobar_version = 2;

Make sure that SiT can upgrade it in it's version database.


function dashboard_foobar_upgrade()
{
    global $CONFIG;
    $upgrade_schema[2] = "
    UPDATE `{$CONFIG['db_tableprefix']}dashboard_foobar` SET foo='foobar' WHERE foo='bar';
    ";
    return $upgrade_schema;
}

function dashboard_foobar_get_version()
{
    global $dashboard_foobar_version;
    return $dashboard_foobar_version;
}

The dashboard_foobar_upgrade() tells sit that there is an upgrade ready.

If you make changes to the database, this example shows how the upgrade should be used:

function dashboard_foobar_upgrade()
global $CONFIG;
{
    $upgrade_schema[2] = "
        -- INL 12Mar10
        ALTER TABLE `{$CONFIG['db_tableprefix']}dashboard_foobar` ADD `table` INT( 5 ) NULL ;
";

For more consequitive versions just add a new $upgrade_schema[x].

function dashboard_foobar_upgrade()
{
    global $CONFIG;
    $upgrade_schema[2] = "
        -- INL 12Mar10
        ALTER TABLE `{$CONFIG['db_tableprefix']}dashboard_foobar` ADD `table` INT( 5 ) NULL ;
";
    $upgrade_schema[3] = "
        -- INL 13Mar10
        ALTER TABLE `{$CONFIG['db_tableprefix']}dashboard_foobar` ADD `table2` INT( 10 ) NULL ;
";
    $upgrade_schema[4] = "";
    // no upgrades for the SQL schema but this is a new version
    return $upgrade_schema;

Dashlet Template

$dashboard_foobar_version = 1;

function dashboard_foobar($dashletid)
{
    $icon = icon('statistics', 16);
    $title = 'Foo Bar';
    $link = 'about.php';
    $content = '<p>Hello World</p>';
    echo dashlet('foobar', $dashletid, $icon, $title, $link, $content);
}

/*
 *function dashboard_foobar_display()
 *{
 *   echo "Hello World @ ";
 *   echo date('H:i');
 *}
*/

/* 
 *function dashboard_foobar_edit($dashletid)
 *{
 *   echo "Configuration example";
 *   // More code here
 *}
*/

/*
 *function dashboard_foobar_upgrade()
 *{
 *    global $CONFIG;
 *    $upgrade_schema[2] = "";
 *    return $upgrade_schema;
 *}
*/

function dashboard_foobar_get_version()
{
    global $dashboard_foobar_version;
    return $dashboard_foobar_version;
}


This documentation is unfinished, it's a work-in-progress, if you have any questions please ask on IRC.

See Also

Personal tools
project