Dashboard¶
The dashboard module is the landing page of NethServer Web UI. It aims to give an overview of system status. Dashboard is fully pluggable and extensible: each NethServer module can add it’s own tab or even a widget inside the System status or Applications tab.
There are three default tabs:
- System status
- Services
- Applications
The dashboard module heavily uses Javascript but works correctly even on smartphones.
SystemStatus tab¶
It’s the main tab composed by three main submodules:
- System release: show the system release
- Resource usage:
- system load
- cpu number
- uptime
- physical memory usage statistics
- virtual memory (swap) usage statistics
- root partition usage statistics
- Network
- configuration of each assigned netwok interface (IP address, netmask, etc.)
- real-time statistics of received and transmitted data
- host name, domain name, default gateway
This tab can be extended using plugins.
Services tab¶
Service tab lists all system services, including current status (running or stopped), configured status (enabled or disabled) and associated TCP and UDP ports. This tab cannot be customized.
Applications tab¶
Applications tab lists all installed application with extra information. Each package can create a special PHP class which describes the installed application.
Extending the dashboard¶
The dashboard heavily uses Nethgui framework to render all information, so you need a little bit of understanding on how project:Nethgui PHP framework actually works. Don’t panic!
Nethgui is a MVC framework specially designed for NethServer web UI tasks.
All files are inside /usr/share/nethesis/NethServer
path, with the following sub-paths:
- Module: controller files
- Template: template files
- Language: language files
Application custom widget¶
This is the simplest widget inside the Applications tab. This kind of widget should be used by all web applications.
Let see the nethserver-collectd-web example.
The package must include a PHP file inside Module/Dashboard/Applications/
directory. The script will describe a new class which extends the AbstractModule class and implements the ApplicationInterface interface. A little scary, eh? There is the full example:
<?php
class Collectd extends \Nethgui\Module\AbstractModule implements \NethServer\Module\Dashboard\Interfaces\ApplicationInterface
{
public function getName()
{
return "Collectd Web";
}
public function getInfo()
{
$cweb = $this->getPlatform()->getDatabase('configuration')->getKey('collectd-web');
$hostname = $this->getPlatform()->getDatabase('configuration')->getType('SystemName');
$domain = $this->getPlatform()->getDatabase('configuration')->getType('DomainName');
return array(
'url' => "http://$hostname.$domain/".$cweb['alias']
);
}
}
Not so scary :)
Basically, the ApplicationInterface requires to implement two simple methods:
- getName(): return the name of the application. The name is used to alphabetically sort all the applications inside the Application tab.
- getInfo(): return an arbitrary associative array. All <key,value> pairs will be printed inside a little auto-generated widget. If the array contains a key starting with ‘url’ string, the value of the key will be wrapped inside an
<a href=''>
HTML tag.
We can now analyze the above getInfo
function implementation. First we read the collectd-web
key from the configuration
db. All properties are then accessible as an associative array. Then we read the value of the special keys SystemName
and DomainName
. Finally we fill the return array with the url where the web application will be accessible.
System status custom widget¶
Let’s take a SystemRelease class which add a widget inside the SystemStatus tab:
- Controller:
Module/Dashboard/SystemStatus/SystemRelease.php
- Template:
Template/Dashboard/SystemStatus/SystemRelease.php
- English translation:
Language/en/NethServer_Module_Dashboard_SystemStatus_SystemRelease.php
- Italian translation:
Language/it/NethServer_Module_Dashboard_SystemStatus_SystemRelease.php
Translation files are simple PHP associative arrays. The language files in the examples are self-explanatory.
You can find all examples inside the nethserver-ui-examples repository.
Controller¶
First of all, let’s introduce few keys concepts about HTTP request handling in Nethgui.
When the browser open an URL, for example /SystemRelease
, the system will search for a module named SystemRelease. If the request contains some query parameters, the server side module will invoke two functions process() and prepareView(), if no query is specified only the function prepareView will be invoked.
The process will handle the query and prepare all data for the prepareView function. For example, here is the process implementation of a simple SystemRelease module:
<?php
...
public function process()
{
$this->release = $this->readRelease();
}
Simple. The process will invoke a private method readRelease which reads a file, and save the result on a private attribute. All data are now available and we have to send them back using the prepareView function:
<?php
...
public function prepareView(\Nethgui\View\ViewInterface $view)
{
//if no query is specified, make sure to initialize the data
if (!$this->release) {
$this->release = $this->readRelease();
}
$view['release'] = $this->release;
}
The release attribute is mapped inside the $view array, ready to be sent to the client. When the client requests the page for the first time with no query, we need to fill the release attribute because the process is not previously called. Then all the $view data will be used to fill the HTML template. If the client send a JSON request with a timestamp as a parameter (which is the standard behavior for ajax calls) the module will invoke process and prepareView, then all data will be formatted in JSON format.
Request examples:
- HTML rendering:
/Dashboard/SystemStatus/SystemRelease
- JSON response:
/Dashboard/SystemStatus/SystemRelease.json
Finally, if you want to order the widget inside the System Status tab, you should define a variable $sortId, like:
public $sortId = 40;
View¶
It’s time to create a simple template to show the data from the controller. Below there’s an example using a built-in CSS class.
<?php
echo "<div class='dashboard-item'>";
echo "<dl>";
echo $view->header()->setAttribute('template',$T('release_title'));
echo "<dt>".$T('release_label')."</dt><dd>"; echo $view->textLabel('release'); echo "</dd>";
echo "</dl>";
echo "</div>";
This is a static template without any use of Javascript. Inside the template file, you always have access to the $view variable where all data are stored by the previous explained prepareView function. There also a very useful function called $T(…) used for translations. The most important part of this examples is the call $view->textLabel(‘release’). This line is an helper which extract the release variable from the view an wrap it a span HTML tag identified by an auto-generated class (useful for Javascript processing).
A full example can be found in the nethserver-ui-examples repository under the dashboard directory.
Custom Tab¶
Any NethServer package can add a custom tab inside the dashboard. To create a new tab you have to write a class extending an existing controller inside the /usr/share/nethesis/NethServer/Module/Dashboard
directory.
See “API”:http://dev.nethserver.org/nethgui/Documentation/Api/ for a list of available controllers.
See mytab example in nethserver-ui-examples repository for more information.