blog documentation FAQ followers forum marketplace services youtube

HowTo: add a panel to the Dashboard

The Jamroom Network » Documentation » Module Developer Guide » HowTo: add a panel to the Dashboard

Table of Contents:


Overview
Customize
Admin adds Panels
For Developers
For Developers: include.php

  • Overview

    This document covers adding a panel option to the dashboard.

    These steps show developers the code needed to offer an output option for the admin user to choose to show on the dashboard.
  • screenshot of the dashboard with a few panels highlighted

  • Customize

    The Customize button allows the admin user to add new rows and columns to the dashboard.

    Many modules provide dashboard panels, it is up to the admin user to display them where they are required.

    Click on the Customize button to add rows of empty panels as locations to bring in the panels that you are interested in.
  • screenshot of the dashboard with 5 rows and 5 cols available

  • Admin adds Panels

    The admin user can add a panel to the dashboard by clicking on one of the empty panels (indicated by a ? in the screenshot above).

    When the admin user clicks on a ? they can choose the panel to add from the available ones provided by modules.
  • screenshot of the options available to the admin user to add new panels

  • For Developers

    For your module to provide an option of a panel it needs to do a few things, we will look at those things below.

  • For Developers: include.php

    In your modules include.php file:
    /modules/(your module)/include.php

    you will have an _init() function. The first thing to do is to register your dashboard panel in the modules _init() function. 
    /**
 * jrImage_init
 */
function jrImage_init()
{
    jrCore_register_module_feature('jrCore', 'dashboard_panel', 'jrImage', 'cached image count', 'jrImage_dashboard_panels');

    return true;
}
  • The code above is for the jrImage module registering the 'cached image count' dashboard panel.

    Make sure you use your module name instead of 'jrImage' and put the title you want to use in place of the 'cached image count'. The third part is the name of the function that will be fired when the panel is in place.

    In the code above the name of the function that is firing is jrImage_dashboard_panels() but the convention is not set in stone, whatever function name you put there will fire.
  • The function does the processing and then if it has something to display puts that information into an array and returns the array for display in the panel.

    If no information is found false is returned. 
    /**
 * Dashboard Panels
 * @param $panel
 * @return bool|int
 */
function jrImage_dashboard_panels($panel)
{
    global $_conf;
    // The panel being asked for will come in as $panel

    $out = false;
    switch ($panel) {

        case 'cached image count':
            // .......

	      $out = array(
		  'title' => intval($out)
	      );
            break;

    }
    return ($out) ? $out : false;
}
  • We can see by looking at the jrImage modules include.php file that it provides 2 dashboard panels.

    Both of the panel names are registered in the _init() function and both direct to the same function for processing jrImage_dashboard_panels(). Then inside jrImage_dashboard_panels() a switch is used to return the desired output. 
        // We provide some dashboard panels

    jrCore_register_module_feature('jrCore', 'dashboard_panel', 'jrImage', 'image cache size', 'jrImage_dashboard_panels');
    jrCore_register_module_feature('jrCore', 'dashboard_panel', 'jrImage', 'cached image count', 'jrImage_dashboard_panels');
  • It would also be fine to define two separate functions for each of the panels and not use a switch if the developer preferred.

Tags