BackendPro User Guide Version 0.3.1

Dashboard

BackendPro provides a customizable dashboard for the control panel. This means you can quickly display important information the the users. It allows widgets to be created and assigned to a section on the dashboard. By default the user can then modify the look of the dashboard by moving widgets around and also by choosing not to display certain widgets.

The dashboard feature is controlled from system/application/controllers/admin/home.php controller class. In this controller you define what widgets you want to show and what they should contain. For the controller to be able to create and display a dashboard it requires two classes:

Lets have a look at the default code in the Home class:

function index()
{         
    // 1. Include dashboard Javascript code
    $this->page->set_asset('admin','js','dashboard.js');

    // 2. Load the dashboard library
    $this->load->library('dashboard');
     
    // 3. Assign widgets to dashboard
    $this->dashboard->assign_widget(new widget($this->lang->line('dashboard_example'),$this->lang->line('dashboard_example_body')),'left');
    $this->dashboard->assign_widget(new widget($this->lang->line('dashboard_statistics'),$this->_widget_statistics()),'right');

    // 4. Load dashboard onto page
    $data['dashboard'] = $this->dashboard->output();

    // Display Page
    $data['header'] = $this->lang->line('backendpro_dashboard');
    $data['page'] = $this->config->item('backendpro_template_admin') . "home";
    $this->load->view($this->_container,$data);
}

function _widget_statistics()
{
    // Generate widget contents, e.g table of data
    return $contents;
}

As you can see from above this controller looks exactly like any other. Some library is called and an ouput is given. So lets step through the main four sections of this code.

  1. This little section includes the dashboard.js javascript file which is used to allow the user to modify the dashboard how they want.
  2. The next section loads the required libraries I talked about earliyer, and creates an instance of the Dashboard class, storing it in $this->dashboard.
  3. This section is where I create and assign widgets to the dashboard. As you can see two widgets are created and assigned to the dashboard object. More details of the class methods used can be found below.
  4. This last section generates the dashboard code.

You will notice a private function in the example above called _widget_statistics(). This function is used to generate the body contents of the statistics widget. The reason the code is in a function instead of inline with the rest of the dashboard code is just to make it easiyer to read. I would advise you also put widget body creation code inside their own functions to make your script more readable.

Guarding a Widget

You may find a time when you only want a widget to be displayed if the user has permission to view the required data. This can be achived through using the Access Control feature. Lets take a look at how this may be done:

if( check('member_widget',NULL,FALSE))
    $this->dashboard->assign_widget(new Widget('Members','Content'),'left');

So in the example above we have used the check helper function to see if the user has access to the resource member_widget. By specifying the last paramter of the call to check as FALSE it means it will just return a boolean result instead of possibilty redirecting the user to an error page (Please see the Access Control feature for more details about this). If the user does pass this test, the widget will be created and assigned to the dashboard.

Dashboard Class

The Dashboard class allows a dashboard object to be created and have widgets assigned to it. It can then generate all the required HTML code to display the dashboard to the user.

Note: Widgets are assigned to the sections in the order you create them in the controller. So a widget assigned before another will apear above the later widget. Of course this is only the default setup. The user may change the order for their personal viewing.

Dashboard Class Function Reference

$this->dashboard->assign_widget();

Assign a widget to a position on the dashboard:

$this->dashboard->assign_widget(Widget Object,'position');

The first parameter is a Widget Class Object. Please see below for how one of these can be created.

The second paramter is the position where you want the widget to appear by default. It can take the value of top, left or right.

Widget Class

The Widget class allows a widget to be created and then when needed its HTML code created. There is not much use using the Widget class on its own, it is for that reason meant to be used in conjuction with the Dashboard class.

Using the class

You only need to know how to create a widget object to use the Widget class, since the Dashboard class takes care of everything else.

Lets look at an example:

new Widget('name','content')

In the example above as you can see a new Widget object being declared and its name and content being passed as parameters. Thats all you need to know.