Creating_a_Dashboard

Creating a Dashboard for your Users

Xataface allows you to build powerful data-driven applications quickly, but these applications may be daunting to your users if they don't know what they can do with the application. Most applications provide some sort of dashboard or control panel with some introductory instructions and links to commonly used actions in the application. This makes the application more intuitive for users so that they can start using it right away, even without instruction from the developer.

Characteristics of a Dashboard

1. Should be the default page when someone visits the application.
2. Should be customized to show menus and content that are relevant to the current user. (i.e. different users may see different links and content on their dashboard).
3. Should contain at least some basic instructions so that the user understands what the application does when he visits the dashboard for the first time.
4. Should contain links to frequently used actions.

Strategies: 8 ways to skin the cat

There are many viable strategies for adding a dashboard to your Xataface application. This article presents only one. It has been chosen because it satisfies all of the desired characteristics of a dashboard listed above, and it is easy to implement.

This strategy involves the following components:

1. Create a dummy dashboard table.
2. Create a dashboard action and associated template.
3. Make sure our dashboard action is the default action for our application (more complex than just using the default_action? directive in the conf.ini file.

Our Sample Application

Consider our sample application, a publications management system for professors and research groups at a university. It allows users to manage their publications using either BibTex format or a web-based form, and embed those publications into their webpage in a slick sortable format. Currently, when the user accesses the application for the first time, they are shown the list tab of the bibliographies table. This isn't all that informative and it may not be obvious to the user that their first step should be to create a new bibliography via the new record button. Ideally we would like the user to go directly to a dashboard page with options to:

1. Add New Bibliography
2. Edit an Existing Bibliography
3. Embed a Bibliography into their Webpage

And we want some basic instructions so that the user knows what to do when they first access the page.

The Steps

To create this dashboard we will follow the steps listed below (and mentioned above in the strategies section.

Step 1: Create a dummy dashboard table

This may seem unorthodox but it just happens to make our lives easier in the long run. By creating a dummy table we are able to cause that table to be listed first in the _tables section of the conf.ini file and thus be the default table when users visit our application.

CREATE TABLE dashboard (
    dashboard_id int(11) not null auto_increment primary key
);
INSERT INTO dashboard values (1);

Step 2: Make dashboard table default

We now modify the conf.ini file to list the dashboard table first:

[_tables]
    dashboard=Dashboard
    bibliographies=Bibliographies

Step 3: Create a Dashboard action and associated template

This is the step where we actually create our dashboard action. There are three parts to this story:

Creating Action PHP Class

The actual action will be located in the actions/dashboard.php file of our application, and looks like:

<?php
class actions_dashboard {
    function handle(&$params){
        $bibs = df_get_records_array('bibliographies', array());
        df_display(array('bibliographies'=>$bibs), 'dashboard.html');
    }
}

All this does is loads the bibliographies records owned by the current user. Elsewhere we are using security filters so that the user can only see his bibliographies, which is why we don't need to specify any query here in the df_get_records_array function.

It then passes those bibliographies to the dashboard.html template that we create next.

Creating the Action's Template

The template for our action is located in the templates/dashboard.html file:

{use_macro file="Dataface_Main_Template.html"}
    {fill_slot name="main_column"}
        <h1>Welcome to the BibTeX Publication Management System (BPMS)</h1>
        
        <p>This system allows you to manage your publications and publish
        them on the web.  Some common actions you may perform with this system
        include:
            <ul>
                <li><img src="{$ENV.DATAFACE_URL}/images/add_icon.gif"/>
                    <a href="{$ENV.DATAFACE_SITE_HREF}?-table=bibliographies&-action=new">
                        Create New Bibliography</a>
                </li>
                <li><img src="{$ENV.DATAFACE_URL}/images/edit.gif"/> 
                   Edit existing bibliography: 
                   <select onchange="window.location.href=this.options[this.selectedIndex].value">
                    <option value="">Select ...</option>
                    {foreach from=$bibliographies item=bibliography}
                        <option value="{$bibliography->getURL('-action=edit')}">
                            {$bibliography->getTitle()}
                        </option>
                    
                    {/foreach}
                </select>
                </li>
                <li><img src="{$ENV.DATAFACE_URL}/images/file.gif"/> 
                    Embed your bibliography in a webpage:
                    <select onchange="window.location.href=this.options[this.selectedIndex].value">
                    <option value="">Select ...</option>
                    {foreach from=$bibliographies item=bibliography}
                        <option value="{$bibliography->getURL('-action=view')}#embed">
                            {$bibliography->getTitle()}
                        </option>
                    
                {/foreach}
                </select>
                </li>
                
            </ul>
    {/fill_slot}
{/use_macro}

A few key things to notice in this template:

1. It extends the Dataface_Main_Template.html template placing its content in the main_column slot. This allows our action to still display within the header and footer of our application.
2. It makes use of the {$ENV.DATAFACE_SITE_URL} and {$ENV.DATAFACE_SITE_HREF} variables to refer to the site's base url and create links to the desired common actions.
3. It provides a direct link to the new bibliography record form.
4. It uses some slick javascript combined with select lists to allow the user to select any of his current bibliogaphies and edit them, or embed them into a webpage.

Adding entry to the actions.ini file

Currently our dashboard action has no permissions attached to it so users can see it whether they are logged in or not. In this particular application we want to require users to log in, and we have set permissions for all logged in users to NO_ACCESS(). Unfortunately this permission setting is only helpful if our action requires a particular permission to access it. We'll require the 'view' permission for this action, by adding the following to the actions.ini file:

[dashboard]
    permission=view

Step 4: Specify permissions

We still want to specify permissions for our dashboard table to ensure that only logged in users can access the dashboard. So we create a delegate class for the dashboard table at tables/dashboard/dashboard.php with the following contents:

<?php
class tables_dashboard {
    function getPermissions(&$record){
        if ( getUser() ){
            return Dataface_PermissionsTool::ALL();
        }
        return null;
    }
}

Note that we have defined the getUser() function elsewhere as a means of obtaining the current user and checking if a user is indeed logged in.

Notice that this getPermissions? method returns all permissions only if the user is logged in. Otherwise it returns null, which means that it should use the same permissions as the rest of the application as defined in the Application Delegate Class.

Step 6: Make dashboard the default action for the dashboard table

Now we just have one more detail that needs to be taken care of. We want the dashboard action to be the default action for the dashboard table only. By default we would see the list action which isn't helpful at all, so we will want to add a rule in our application delegate class to ensure that the user only sees our custom dashboard action if they access the dashboard table. We define a beforeHandleRequest() method in our conf/ApplicationDelegate.php (the application delegate class) file for this purpose:

<?php
class conf_ApplicationDelegate {
    
...
    function beforeHandleRequest(){
        ...
        $app =& Dataface_Application::getInstance();
    $query =& $app->getQuery();
    if ( $query['-table'] == 'dashboard' and ($query['-action'] == 'browse' or $query['-action'] == 'list') ){
        $query['-action'] = 'dashboard';
    }
        
        
    }
    
    ...
}

This simply checks to see if the table is dashboard and changes the current action to dashboard if so.

Step 7: Try it out

At this point, we are ready to try out our new dashboard to see how it works. When we load our application it should now go to the dashboard action that we created. We should also see Dashboard listed as the first table in the tables menu.

This dashboard presents a major improvement to our application as it is now much more user friendly.