ActionKit dashboard reports are a wonderful mechanism for extended the admin interface with new capabilities and custom logic. Most obviously, dashboard reports can run query reports and format their results in innovative ways. But dashboards can also contain custom JavaScript logic, including functions that call the ActionKit REST API to create or modify records on behalf of the admin users.
But in the course of developing large and complex dashboards, one quickly encounters a challenge — dashboard reports are edited through the ActionKit admin interface, rather than in the dedicated code editors developers are accustomed to using for large code projects, and they’re not subject to revision control, so if you accidentally delete some important code or introduce a bug, you can’t easily roll back your changes or compare it to a version that was known to work. And if multiple developers are attempting to update the same dashboard, inevitably one person’s changes will be overwritten by another’s unless you institute some kind of procedure to ensure only one person has the editor open at a time.
By contrast, ActionKit’s templating system for pages allows for integration with GitHub, so the code in a templateset can be maintained under version control, along with all of the merging and rollback capabilities that come with that.
It was this thought that led me to wonder… “well, why can’t we leverage that same mechanism for dashboards?” And it turns out that the answer is… we can.
Example
As a starting point, let’s begin with a dashboard report that shows the current time according to the ActionKit server by running one of the built-in queries:
<h2>Server Time</h2>
<p>The time is {{ reports.now }}</p>Creating a Template File
Let’s imagine that our developers are planning to add a bunch of functionality to this report and they want to ensure that they don’t step on each others’ work, and that the report isn’t accidentally changed by campaigners poking around in the ActionKit admin interface.
In the ActionKit admin, click in to Appearance > Templatesets, find the “Original” templateset and click to copy it, giving the new version the name “Admin.”
Then copy the contents of the above dashboard report into a new template file; for this example we’ll call that dash_now.html.
Upload this new files to your Admin templateset, ensuring that you have the “add new custom templates” option checked, and then click the “Publish Changes” button to make the new file live.
Invoking a Template File
We can then replace the contents of our dashboard report with an invocation of this template:
{% include "Admin/dash_now.html" %}When we run the dashboard report, it runs the code in the template file and output the result.
Passing Parameters
If code in a dashboard report needs to prompt the user to enter parameters, it does that by including the {% required_parameter "parameter_name" %} tag.
However, ActionKit does not search the reports and templates included in a dashboard to discover if they take parameters, and so if we’re invoking a template file we can’t simply place the parameter declarations in that file — we have to put them in the dashboard report itself.
Admin/dash_now.html Template:
{% required_parameter "skipheader" %}
{% if not skipheader %}<h2>Server Time</h2>{% endif %}
<p>The time is {{ reports.now }}</p>Associated Dashboard Report:
{% required_parameter "skipheader" %}
{% include "Admin/dash_now.html" %}When we run the dashboard report we’re prompted for a parameter value:
And the value we enter there will influence the output from the included template:
Conclusion
This technique lets us create large complex templates which are managed in the same way as our user-facing template files (perhaps in Git) and which can be invoked within the ActionKit admin, allowing us to extend the back-end of the platform with new capabilities.
I developed this technique while working for WeMove Europe to create a dashboard report that ended up being more than thousand lines long; my thanks to the team there for the interesting challenge!
Leave a Reply