Dashboard boxes - Code snippets

Displaying Dashboard boxes

DESCRIPTION This Web App illustrates the display of statistics boxes like the ones we can find on popular dashboard templates.

The statistics displayed on the boxes are retrieved from a remote PHP controller action.
They are refreshed both by using an AJAX request (Refresh button) and by reloading the entire view.

Finally, the amounts are displayed in euros by applying the French locale installed on the web hosting.

PREREQUISITE The ZnetDK for Mobile Starter Application is installed and configured (go to the Get Started page and follow the given procedure).

STEPS Only four steps are required:

Step 1: Coding the view in charge of displaying the statistics boxes,
Step 2: Coding the controller that supplies the data to display on the boxes,
Step 3: Setting the locale to French in order to format the amounts in currency,
Step 4: Loading two extra style sheets to beautify the display of the statistics boxes,
Step 5: Adding a new item to the App's navigation menu.

DEMONSTRATION See live demo....

Step 1 - Coding the view `statboxes.php`

The view statboxes.php must be installed into the INSTALL_DIR/applications/default/app/view/ folder.

In order to retrieve the statistics to display in the view, the code starts by calling directly in PHP on the server-side, the get action implemented in the \app\controller\StatCtrl controller (see implementation in Step 2), via the doAction() method.
Next, the statistics returned by the get action are inserted in the corresponding <h3> tags when the view is converted to HTML on the server-side, before being downloaded.
In order to force the view to be reloaded each time the corresponding menu item is clicked, the zdk-viewreload CSS class is added to any HTML element of the view, in this case to the div.statboxes element.
The responsiveness of the statistics boxes is ensured by the w3-row-padding and w3-quarter W3.CSS classes.
Extra Flat UI colors (w3-flat-alizarin, w3-flat-belize-hole, ...) are used to color the statistics boxes. Theses colors are declared by loading the w3-colors-flat.css library (see step 4).
Finally, an event handler is implemented within the <script> tag in response to the clicks on the Update button, to request in AJAX the last statistics and display them in the view, thus avoiding fully reloading the view.
The znetdkMobile.ajax.request() is the method used to invoke remotely the same controller action than the one initially called on the server-side, to fill the view with the statistics.
Once the statistics updated in the DOM, a snackbar message is displayed by calling the znetdkMobile.messages.showSnackbar() method.

View statboxes.php

<?php
$response = \app\controller\StatCtrl::doAction('get');
?>
<div class="statboxes zdk-viewreload w3-row-padding w3-margin-top w3-stretch">
    <div class="w3-quarter w3-margin-bottom">
        <div class="w3-container w3-flat-alizarin w3-padding-16">
            <div class="w3-left"><i class="fa fa-tasks w3-xxxlarge"></i></div>
            <div class="w3-right">
                <h3 class="tasks"><?php echo $response->tasks; ?></h3>
            </div>
            <div class="w3-clear"></div>
            <h4>Tasks</h4>
        </div>
    </div>
    <div class="w3-quarter w3-margin-bottom">
        <div class="w3-container w3-flat-belize-hole w3-padding-16">
            <div class="w3-left"><i class="fa fa-bank w3-xxxlarge"></i></div>
            <div class="w3-right">
                <h3 class="balance"><?php echo $response->balance; ?></h3>
            </div>
            <div class="w3-clear"></div>
            <h4>Balance</h4>
        </div>
    </div>
    <div class="w3-quarter w3-margin-bottom">
        <div class="w3-container w3-flat-emerald w3-padding-16">
            <div class="w3-left"><i class="fa fa-credit-card w3-xxxlarge"></i></div>
            <div class="w3-right">
                <h3 class="expenses"><?php echo $response->expenses; ?></h3>
            </div>
            <div class="w3-clear"></div>
            <h4>Expenses</h4>
        </div>
    </div>
    <div class="w3-quarter w3-margin-bottom">
        <div class="w3-container w3-flat-carrot w3-text-white w3-padding-16">
            <div class="w3-left"><i class="fa fa-handshake-o w3-xxxlarge"></i></div>
            <div class="w3-right">
                <h3 class="sales-orders"><?php echo $response->salesOrders; ?></h3>
            </div>
            <div class="w3-clear"></div>
            <h4>Sales orders</h4>
        </div>
    </div>
</div>
<button id="btn-refresh-stats" class="w3-button w3-theme-action"><i class="fa fa-refresh"></i> Update</button>
<script>
    $('#btn-refresh-stats').on('click', function(){
        znetdkMobile.ajax.request({
            controller: 'statctrl',
            action: 'get',
            callback: function (response) {
                $('.statboxes h3.tasks').text(response.tasks);
                $('.statboxes h3.balance').text(response.balance);
                $('.statboxes h3.expenses').text(response.expenses);
                $('.statboxes h3.sales-orders').text(response.salesOrders);
                znetdkMobile.messages.showSnackbar('Statistics refreshed.');
            }
        });
    });
</script>

PHP HTM5 JS

This view requires extra styles that are coded in a dedicated style sheet named statboxes.css, placed into the INSTALL_DIR/applications/default/public/css/ folder and finally loaded in the main page of the application via the declaration made in Step 4.

Style sheet statboxes.css

.statboxes .fa {
    color: rgba(255,255,255,.6);
}
.statboxes h4 {
    border-left: 6px solid;
    margin-left: -16px;
    padding-left: 12px;
    color: rgba(255,255,255,.6);
}

CSS

Step 2 - Coding the controller `statctrl.php`

The controller statctrl.php must be installed into the INSTALL_DIR/applications/default/app/controller/ folder.

The get action (method named action_get() in the class derived from \AppController) is called by the statboxes.php view to obtain the statistics to display.
The \Convert::toMoney() method is called to convert the float values to currency amounts according to the locale configured for the application.

Controller statctrl.php

<?php
namespace app\controller;
class StatCtrl extends \AppController {
    static protected function action_get() {
        $response = new \Response();
        $response->tasks = rand(0,99).'%';
        $response->balance = \Convert::toMoney(rand(0,9999)+(rand(0,99)/100));
        $response->expenses = \Convert::toMoney(rand(0,9999)+(rand(0,99)/100));
        $response->salesOrders = rand(0,200);
        return $response;
    }
}

PHP

Step 3 - Setting the locale to French

To set the locale to French (in my case named fr_FR.utf8), just edit the INSTALL_DIR/applications/default/app/lang/locale.php script and declare the LC_LOCALE_ALL PHP constant as shown below.

Script locale.php

define('LC_LOCALE_ALL', serialize(array('fr_FR.utf8')));

PHP

Step 4 - Loading two extra CSS libraries

Two extra style sheets are loaded in the main page of the application by declaring the CFG_APPLICATION_CSS parameter into the config.php script located into the INSTALL_DIR/applications/default/app/ folder.

The line below can be inserted anywhere in the config.php script.

Script config.php

define('CFG_APPLICATION_CSS', serialize([
    'https://www.w3schools.com/lib/w3-colors-flat.css',
    'applications/default/public/css/statboxes.css'
]));

PHP

Step 5 - Adding "Dashboard" item to the navigation menu

Finally, to give users access to the statboxes.php view, the menu's item named Dashboard is declared into the menu.php script of the Web App (see Get Started | New menu items for more information).

The menu.php script is located into the INSTALL_DIR/applications/default/app/ folder.

Script menu.php

static public function initAppMenuItems() {
    
    // ... Here, some menu items...
    
    \MenuManager::addMenuItem(NULL, 'statboxes', 'Dashboard', 'fa-dashboard');
    
    // ... Here, other menu items...
    
}

PHP