abdus

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

Recommended Posts

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.

chrome_2017-04-29_17-03-07.thumb.png.cf2bad54019bcc4eb354168dc5df14fb.png

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.

chrome_2017-04-29_17-12-11.thumb.png.72112716449f08dfc872dee86a5e030a.png

 

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

chrome_2017-04-29_18-32-47.thumb.png.7c915544b190bb099d3086e0a66f3e76.png
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.

2017-04-30_15-34-09.thumb.gif.e050cb9396156b792244e8dfa7f9a704.gif

 

  • Like 29

Share this post


Link to post
Share on other sites

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.

  • Like 1

Share this post


Link to post
Share on other sites
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.

  • Like 4

Share this post


Link to post
Share on other sites

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/

licecap_rules.gif

very easy, very helpful :)

  • Like 5

Share this post


Link to post
Share on other sites

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!

  • Like 1

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.

  • Similar Content

    • By Soma
      LogMaintenance
      A simple ProcessWire module to give some maintenance control over log files. I found myself often having lots of log files for different things that can grow more or less quickly to a size where they can be difficult to maintain. The built in Logger of PW does a good job of giving you the possibility to delete or prune logs. But it has to be done manually and sometimes a log grows into millions of lines, which makes it often impossible to even prune it as it's too large.
      LogMaintenance uses LazyCron to run the maintenance task and there's several settings you can setup on a global or per log basis.
      Archive: will create zip files for each log file in logs/archive/ folder and add the log each time the maintenance is run to a subfolder containing the datetime.
      Lines: keeps logs to a certain number of lines 
      Days: keeps the log to a certain number of days
      Bytes: keeps the log to a certain amount of bytes
      Each setting is checked from top down, the first setting to contain something is used. So if you check the "Archive" option, all other settings are ignored and logs are archived everytime the LazyCron is executed. If you want to keep your logs to a certain amount of bytes just leave all other settings to 0 or blank.
      Per Log Settings
      There's a textarea that you can use to setup a config for a specific log file one per line. All the logs you define here ignore the global settings above. The syntax for the settings is:
      logname:[archive]:[lines]:[days]:[bytes] 
      errors:1:0:0:0 // would archive the errors log messages:0:10000:0:0 // will prune the errors log to 10000 lines  
      The module can be found on github for you to check out. It's still fresh and I'm currently testing.
      https://github.com/somatonic/LogMaintenance
    • By louisstephens
      So I have a project where multiple pages are sending POST data to 1 single template page.  All was working well (well, at least with one ajax post), but now I have hit a stumbling block. I figured  the "best" way to handle the request were to use url segments and then use the following in the status page:
      if ($config->ajax && $input->urlSegment1 == 'add-bookmark') { // some code here } However, this doesnt seem to really work (as I assume the the request isnt being posted to /status/ but rather to /status/add-bookmark/). What is the best way to actually handle this?
    • By louisstephens
      Currently, I have a page set up listing all child pages using a foreach loop and outputting some information (thus far, it is all gravy). However, I ran into a slight problem. I have a "button" on each item being rendered that when clicked needs to send the page id to another page for processing via ajax. I thought I could just save the item id like :
      <?php $itemId = $item->id; ?> And then encoding it below in my javascript:
      var itemId = <?php echo json_encode($itemId); ?>; var data = { itemId: itemId, }; $.ajax({ type: "POST", url: "/intra/status/", data: data, success: function(){ console.log(itemId); } }); However, it is only posting the last page's id rendered by the foreach. Have I just overlooked something simple on this?
    • By teppo
      Fieldtype Page IDs is a third party Fieldtype that, simply put, stores Page references as integers (Page IDs).
      This fieldtype was built as a quick and dirty workaround for Page Reference fields' inability handle self-references due to circular reference issues. A project I've been working on for a while now includes a combination of RepeaterMatrix content blocks and tagging/categorization system that would've resulted in a lot of duplicate pages (and plenty of unnecessary manual work for content editors) had I used built-in Page Reference fields, and thus a new Fieldtype felt like the most sensible approach.
      Fieldtype Page IDs was designed to be loosely compatible with Page References in order to make conversions between the two feasible, but it is quite limited feature wise:
      largely due to the fact that stored values are actually just integers with no connection to Pages whatsoever some advanced selectors and related features are not supported, and page values can't be directly accessed configuration settings are limited to the bare essentials (selector string and Inputfield class) only a handful of Inputfields (AsmSelect, Checkboxes, Text) are (currently) supported Anyway, in case you need to store Page IDs (and Page IDs only) and are happy with the limitations mentioned above, feel free to give this Fieldtype a try. It has been working fine for me in one particular project, but hasn't been tested that much, so please tread carefully – and let me know if you run into any issues.
      GitHub repository: https://github.com/teppokoivula/FieldtypePageIDs
      Modules directory: https://modules.processwire.com/modules/fieldtype-page-ids/
    • By daniels
      This is a lightweight alternative to other newsletter & newsletter-subscription modules.
      You can find the Module in the Modules directory and on Github
      It can subscribe, update, unsubscribe & delete a user in a list in Mailchimp with MailChimp API 3.0. It does not provide any forms or validation, so you can feel free to use your own. To protect your users, it does not save any user data in logs or sends them to an admin.
      This module fits your needs if you...
      ...use Mailchimp as your newsletter / email-automation tool ...want to let users subscribe to your newsletter on your website ...want to use your own form, validation and messages (with or without the wire forms) ...don't want any personal user data saved in any way in your ProcessWire environment (cf. EU data regulation terms) ...like to subscribe, update, unsubscribe or delete users to/from different lists ...like the Mailchimp UI for creating / sending / reviewing email campaigns *I have only tested it with PHP 7.x so far, so use on owners risk
      EDIT:
      I've updated the module to 0.0.4. I removed the instructions from this forum, so I don't have to maintain it on multiple places. Just checkout the readme on github 🙂
      If you have questions or like to contribute, just post a reply or create an issue or pr on github.