Creating web UI module¶
In this page you can find a working example of a simple UI for a new module, but, first a little of theory.
Web UI structure¶
All code is organized in three main directories:
/usr/share/nethesis/Nethgui
: framework libraries (can be used for other projects)/usr/share/nethesis/NethServer
: actual implementation of modules UI/usr/share/nethesis/nethserver-manager
: web root directory
Nethgui is a MVC framework that aims to abstract the developer from the backend and frontend. This means that you don’t have to deal with reading and writing properties from DB, neither care about HTML, CSS and JavaScript on the client side. You just write the controller. Of course, if you want, you can play with all three layers but it shouldn’t be necessary in the most of cases.
Each module is composed by 4 parts:
- Controller:
/usr/share/nethesis/NethServer/Module/.php
- View:
/usr/share/nethesis/NethServer/Template/.php
- Translation:
/usr/share/nethesis/NethServer/Language//NethServer\_Module*.php
- Inline help :
/usr/share/nethesis/NethServer/Help/NethServer_Module*\ .html
If needed, a module can add extra resources:
- Specific authorization (JSON format):
/usr/share/nethesis/NethServer/Authorization/.json
- See Nethgui:Authorization - Custom CSS:
/usr/share/nethesis/NethServer/Css/.css
- See Including CSS Custom JavaScript: /usr/share/nethesis/NethServer/Js/.js
- See Including JS- Unit tests:
/usr/share/nethesis/NethServer/Test/Unit/NethServer/Module/.php
- See Nethgui unit test - Utility libraries:
/usr/share/nethesis/NethServer/Tool/.php
Writing the code¶
We add a UI to the package nethserver-ejabberd module. The UI will
expose 2 properties of the ejabberd
db key.
Properties:
- status: start and stop the ejabberd daemon on boot, can be enabled or disabled
- WelcomeText: welcome text, can be anything
Controller¶
First, we create the controller which has 3 main functions:
- initializeAttributes: handle module position in menu
- initialize: bind the properties to the database and set the validator
- onParametersSaved: apply the configuration
Here is the controller
(/usr/share/nethesis/NethServer/Module/Ejabber.php
):
class Ejabber extends \Nethgui\Controller\AbstractController
{
// Add the module under the 'Configuration' section,
protected function initializeAttributes(\Nethgui\Module\ModuleAttributesInterface $base){
return \Nethgui\Module\SimpleModuleAttributesProvider::extendModuleAttributes($base, 'Configuration', 30);
}
// Declare all parameters
public function initialize(){
parent::initialize();
// Bind 'WelcomeText' view parameter to 'WelcomeText' prop in ejabberd key of configuration db
$this->declareParameter('WelcomeText', Validate::ANYTHING, array('configuration', 'ejabberd', 'WelcomeText'));
}
// Execute actions when saving parameters
protected function onParametersSaved($changes) {
// Signal nethserver-ejabberd-save event after saving props to db
$this->getPlatform()->signalEvent('nethserver-ejabberd-save@post-process');
}
}
View¶
Show all fields using built-in functions. If needed, you can add extra HTML markup but remember that the output must be functional on any device (desktop, mobile, text browser, etc).
Template (/usr/share/nethesis/NethServer/Template/Ejabber.php):
echo $view->header()->setAttribute('template', $T('Ejabber_Title'));
// add simple panel
echo $view->panel()
//add 'status' parameter checkbox with value when checked and unchecked
->insert($view->checkbox('status', 'enabled')->setAttribute('uncheckedValue', 'disabled'));
//add 'WelcomeText' text input field
echo $view->panel()->insert($view->textInput('WelcomeText'));
;
// show submit and help buttons
echo $view->buttonList($view::BUTTON_SUBMIT | $view::BUTTON_HELP);
Translation¶
Translation files, are simple PHP files containing an associative
array.
All module language files are placed in /usr/share/nethesis/NethServer/Language/<lang>
.
Given a module with name “Test”, the english language file will be /usr/share/nethesis/NethServer/Language/en/NethServer_Module_Test.php
.
Warning messages about missing translations can be found in /var/log/messages
after Nethgui debug is enabled.
To enable the debug, use index_dev.php on urls, eg: https://<ipaddress>/index_dev.php/en/<module>
.
English translation (/usr/share/nethesis/NethServer/Language/en/NethServer_Module_Ejabber.php):
<?php
$L['Ejabber_Title'] = 'Chat server';
$L['status_label'] = 'Enable Ejabber chat server';
$L['WelcomeText'] = 'Welcome!';
Inline help¶
Help pages are RST documents compiled into xHTML pages at package build time.
===========
Chat server
===========
Ejabber is a chat server that implements the Jabber/XMPP protocol Jabber / XMPP, it support TLS on standard XMPP ports (5222 or 5223).
The chat server uses system users to login.
More examples¶
More examples can be found here or browsing the existing modules.