dashboard How to build a simple dashboard with AJAX functionality using a Process module

[abdus]

After this tutorial you'll have learned how to:

• Build a Process module
• Make an AJAX request to backend
• Serve JSON as response

Let's say you want to display the latest orders in a dashboard that you can access from admin panel. And you want it to refresh its content with a button click. Most straightforward and proper way (that I know of) is to create a Process module, as they're built for this purpose.

First, create a directory under /site/modules/, call it ProcessDashboard, and create a file named ProcessDashboard.module under that directory. Following is about the least amount of code you need to create a Process module.

<?php namespace ProcessWire;


class ProcessDashboard extends Process
{
    public static function getModuleInfo() {
        return [
            'title' => 'Orders Dashboard',
            'summary' => 'Shows latest orders',
            'version' => '0.0.1',
            'author' => 'abdus',
            'autoload' => true,
            
            // to automatically create process page
            'page' => [
                'name' => 'order-dashboard',
                'title' => 'Orders',
                'template' => 'admin'
            ]
        ];
    }

    public function ___execute()
    {
        return 'hello';
    }
}

Once you refresh module cache from Modules > Refresh, you'll see your module. Install it.

It will create an admin page under admin (/processwire/) and will show up as a new item in top menu, and when you click on it, it will show the markup we've built in execute() function.

 

All right, now let's make it do something useful. Let's add create a data list to display latest orders. We'll change execute() function to render a data table.

public function ___execute()
{
    /* @var $table MarkupAdminDataTable  */
    $table = $this->modules->MarkupAdminDataTable;
    $table->setID($this->className . 'Table'); // "#ProcessDashboardTable"
    $table->headerRow([
        'Product',
        'Date',
        'Total'
    ]);


    // fill the table
    foreach ($this->getLatest(10) as $order) {
        $table->row([
            $order['title'],
            $order['date'],
            $order['total']
        ]);
    }


    // to refresh items
    $refreshButton = $this->modules->InputfieldSubmit;
    $refreshButton->name = 'refresh';
    $refreshButton->id = $this->className . 'Refresh'; // "#ProcessDashboardRefresh"
    $refreshButton->value = 'Refresh'; // label of the button
    
    return $table->render() . $refreshButton->render();
}

where getLatest() function finds and returns the latest orders (with only title, date and total fields)

protected function getLatest($limit = 5, $start = 0) {
    // find last $limit orders, starting from $start
    $orders = $this->pages->find("template=order, sort=-created, limit=$limit, start=$start");

    // Only return what's necessary
    return $orders->explode(function ($order) {
        return [
            'title' => $order->title,
            'date' => date('Y-m-d h:i:s', $order->created),
            'total' => $order->total
        ];
    });
}

When you refresh the page, you should see a table like this

Now we'll make that Refresh button work. When the button is clicked, it will make an AJAX request to ./latest endpoint, which will return a JSON of latest orders. We need some JS to make AJAX request and render new values. Create a JS file ./assets/dashboard.js inside the module directory.

window.addEventListener('DOMContentLoaded', function () {

    let refresh = document.querySelector('#ProcessDashboardRefresh');
    let table = document.querySelector('#ProcessDashboardTable');

    refresh.addEventListener('click', function (e) {
        // https://developer.mozilla.org/en/docs/Web/API/Event/preventDefault
        e.preventDefault();
      
        // Send a GET request to ./latest
        // http://api.jquery.com/jquery.getjson/
        $.getJSON('./latest', {
            limit: 10
        }, function (data) {
            // check if data is how we want it
            // if (data.length) {}  etc

            // it's good to go, update the table
            updateTable(data);
        });
    });

    function renderRow(row) {
        return `<tr>
                    <td>${row.title}</td>
                    <td>${row.date}</td>
                    <td>${row.total}</td>
                </tr>`;
    }

    function updateTable(rows) {
        table.tBodies[0].innerHTML = rows.map(renderRow).join('');
    }
});

And we'll add this to list of JS that runs on backend inside init() function

public function init()
{
    $scriptUrl = $this->urls->$this . 'assets/dashboard.js';
    $this->config->scripts->add($scriptUrl);
}

Requests to ./latest will be handled by ___executeLatest() function inside the module, just creating the function is enough, PW will do the routing. Here you should notice how we're getting query parameters that are sent with the request.

// handles ./latest endpoint
public function ___executeLatest() {
    // get limit from request, if not provided, default to 10
    $limit = $this->sanitizer->int($this->input->get->limit) ?? 10;
    return json_encode($this->getRandom($limit));
}

Here getRandom() returns random orders to make it look like there's new orders coming in. 

protected function getRandom($limit = 5)
{
    $orders = $this->pages->find("template=order, sort=random, limit=$limit");
    return $orders->explode(function ($order) {
        return [
            'title' => $order->title,
            'date' => date('Y-m-d h:i:s', $order->created),
            'total' => $order->total
        ];
    });
}

And we're done. When refresh button is clicked, the table is refreshed with new data.

Here it is in action: 
2017-04-29_19-01-40.mp4 (227KB MP4, 0m4sec)

Here's the source code:
https://gist.github.com/abdusco/2bb649cd2fc181734a132b0e660f64a2

 

[Enhancement] Converting page titles to edit links

If we checkout the source of MarkupAdminDataTable module, we can see we actually have several options on how columns are built.

/**
 * Add a row to the table
 *
 * @param array $a Array of columns that will each be a `<td>`, where each element may be one of the following:
 *   - `string`: converts to `<td>string</td>`
 *   - `array('label' => 'url')`: converts to `<td><a href='url'>label</a></td>`
 *   - `array('label', 'class')`: converts to `<td class='class'>label</td>`
 * @param array $options Optionally specify any one of the following:
 *   - separator (bool): specify true to show a stronger visual separator above the column
 *   - class (string): specify one or more class names to apply to the `<tr>`
 *   - attrs (array): array of attr => value for attributes to add to the `<tr>`
 * @return $this
 *
 */
public function row(array $a, array $options = array()) {}

This means, we can convert a column to link or add CSS classes to it.

// (ProcessDashboard.module, inside ___execute() method)

// fill the table
foreach ($this->getLatest(10) as $order) {
    $table->row([
        $order['title'] => $order['editUrl'], // associative -> becomes link
        $order['date'], // simple -> becomes text
        [$order['total'], 'some-class'] // array -> class is added
    ]);
}

Now, we need to get page edit urls. By changing getLatest() and getRandom() methods to return edit links in addition to previous fields

protected function getLatest($limit = 5, $start = 0)
{
    // find last $limit orders, starting from $offset
    $orders = $this->pages->find("template=order, sort=-created, limit=$limit, start=$start");
    return $orders->explode(function ($order) {
        return [
            'title' => $order->title,
            'date' => date('Y-m-d h:i:s', $order->created),
            'total' => $order->total,
            'editUrl' => $order->editUrl
        ];
    });
}

protected function getRandom($limit = 5)
{
    $orders = $this->pages->find("template=order, sort=random, limit=$limit");
    return $orders->explode(function ($order) {
        return [
            'title' => $order->title,
            'date' => date('Y-m-d h:i:s', $order->created),
            'total' => $order->total,
            'editUrl' => $order->editUrl
        ];
    });
}

and tweaking JS file to render first column as links

function renderRow(row) {
    return `<tr>
                <td><a href="${row.editUrl}">${row.title}</a></td>
                <td>${row.date}</td>
                <td>${row.total}</td>
            </tr>`;
}

we get a much more practical dashboard.

 

[szabesz]

Thanks @abdus for this useful tutorial! If you could also add how to turn the values of the first column into links, then it would be a 100% perfect example.

[abdus]

1 hour ago, szabesz said:

Thanks @abdus for this useful tutorial! If you could also add how to turn the values of the first column into links, then it would be a 100% perfect example.

Thanks for the suggestion, I've added it to the original post.

[bernhard]

hi abdus,

thanks for your effort on helping others  maybe i can suggest you to take a tool that lots of people are using here for creating micro-screencasts as animated gifs: http://www.cockos.com/licecap/

very easy, very helpful

[abdus]

I've been using ShareX for the screencasts, but it can't handle high DPI screens very well (might be ffmpeg's fault, though), and cursor is offset a bit.
Just tried LICEcap, it seems to work on high DPI screen just fine. I'll use this one from now on.

Thank you very much for the suggestion @bernhard!