Server Manager2 create panel for contrib

From SME Server
Jump to navigation Jump to search

Introduction

Server Manager 2 is based on the perl library Mojolicious and has as its central tenet that the html structure is kept separate from the content that is displayed, giving a lot of flexibility. It has a structure so that the web pages can have a theme applied independant of the content. Behind the scenes a non blocking web server does the actual work, and comes with lots of additional plugins.

Initially the default theme mimics the current Server Manager pages (which is based on formMagick), however a new theme has also been developed which is based on AdminLTE.

If you follow the rules in this document, then your page should work in both themes without any trouble!

I am using the example of the DHCP Manager contrib which has a simple initial panel and 3 subsidiary panels.

Directory Structure

/usr/share/smanager
├── conf - contains preferences file.
├── data
├── lib
│   └── SrvMngr
│       ├── Controller - contains .pm files one for each module
│       ├── I18N
│       │   └── Modules
│       │       ├── Backup
...snip ....one for each module - contains translation strings
│       │       ├── Xt_geoip
│       │       └── Yum
│       ├── Model
│       └── Plugin
├── log
├── script
├── t
└── themes
    └── default
        ├── public
        │   ├── css
        │   ├── images 
        │   └── js
        └── templates - top level .html.ep file (one per theme)
            ├── layouts - contains one .html.ep file for each module
            └── partials - contains partial files - as many as required for modules 
                           (generally corresponds to subsidiary panels)

So each module (contrib in this case), consists of at least 3 files:

  1. .pm file of perl in the controller directory to gather up the content into a data structure (generally a hash or array)
  2. .lex or .pm in the I18n/modules directory consisting of translation strings. I think that the system will generate the .pm file from the .lex file, but will use a .pm file if it is there (need to check this with @michel).
  3. .html.ep file in the themes/default/templates/layout directory being the top level panel plus includes to subsidiary panels.
  4. In addition there may be "extra" .html.ep files in the themes/default/templates/layout/partials directory, which are conditionally included in the top level panel code.

Configuration/Preferences File

This is found in /usr/share/smanager/conf/srvmngr.conf. Initial contents are:

#------------------------------------------------------------
#              !!DO NOT MODIFY THIS FILE!!
# 
# Manual changes will be lost when this file is regenerated.
#
# Please read the developer's guide, which is available
# at http://www.contribs.org/development/
#
# Copyright (C) 1999-2006 Mitel Networks Corporation
#------------------------------------------------------------
{
# configuration file for Mojolicious Server-Manager2 application
#
    secrets => ['blah blah'],
    theme => 'default',
    # session timeout
    timeout => '300',
    hypnotoad => {
    ## adresses and ports listened
        listen => ['http://127.0.0.1:982'],
        proxy  => 1,
        pid_file => '/var/run/smanager.pid',

    ## process number based on CPU number [x 2]
        workers => (`grep processor /proc/cpuinfo | wc -l` * 2),

    ## connections queue size, per worker
        accepts => 100,

    ## propriétaire et groupe du serveur
        user => 'admin',
        group => 'admin'
    },
    # is js-jquery available
    hasJquery => 1,
    modules_dir => 'lib/SrvMngr/Controller',
    webapp => 'smanager',
    mode => 'production',
    debug => 0,
}

If you change the "mode" => "development", then when you get a runtime error it will show you the context. Otherwise it just gives a generic error message.

The file is templated so every time you reload the rpm then it will get set to "production", unless you add a custom template to:

"/etc/e-smith/templates/usr/share/smanager/conf/srvmngr.conf" to override it.

Later you will see how to access the "debug" property in your perl code which can be used to switch on and off diagnostic information.

Here's the contents of my "/etc/e-smith/templates-custom/usr/share/smanager/conf/srvmngr.conf/30other":

    modules_dir => 'lib/SrvMngr/Controller',
    webapp => 'smanager',
    mode => 'development',
    debug => 1,
\}

The files we need

So, we'll create the following files for the new SM2 panel(s) for the DHCPManager contrib.

  1. /usr/share/smanager/lib/SrvMngr/Controller/Dhcpman.pm
  2. /usr/share/smanager/lib/SrvMngr/I18N/Modules/Dhcpman/dhcpman_en.lex
  3. /usr/share/smanager/themes/default/templates/dhcpman.html.ep
  4. /usr/share/smanager/themes/default/templates/partials/_dhcpm_scan.html.ep
  5. /usr/share/smanager/themes/default/templates/partials/_dhcpm_winpopup.html.ep
  6. /usr/share/smanager/themes/default/templates/partials/_dhcpm_leases.html.ep

Quite why the partials have to start with the "_" I am not sure - looks like a convention to "underline" that fact that they are only called internally.

Note the initial capital letter on the file name for the controller file, and also the Translation directory.

Converting from formMagick

if you are converting an existing contrib with a formMagick panel, then you will want to use the current files as a basis for the re-write.

For the DHCP manager contrib, these are:

  1. /etc/e-smith/web/functions/dhcpd
  2. and sometimes a file in here: /usr/share/perl5/vendor_perl/esmith/FormMagick/Panel Although in this case there is not. (and I find that directory structure impossible to remember - "esmith" sans "-" throws me).
  3. and translatable strings in here: /etc/e-smith/locale/en-us/etc/e-smith/web/functions/<contrib name> the format is XML- like whereas SM2 requires a more perl l- ike structure.


I have not really understood how formMagick works, but mostly the subroutine names and code shows what is needed.

Coding Environment

I work using a "test" SME10 VM accessed through an SSH tunnel (setup in the fstab) from my Fedora/Cinnamon desktop using the "geany" editor.

Here is the fstab entry:

root@sme10.thereadclan.me.uk:/			/home/brianr/SME10 	fuse.sshfs 	rw,auto 	0	 0

I'll setup a geany project with all the above files open in tabs. Opening the editor project will open all the files in one go, assuming that the mapping to SME10 is live (sometime I have to manually mount it in Nemo, especially after the desktop has been suspended for a while).

Your mileage may of course vary!! Other editors etc are available.

I can then run the Server Manager in a browser against the SME10 VM, and make changes directly into the VM and see the results quickly.

Sometimes the changes require a:

signal-event smanager-refresh

The Controller File (Dhcpman.pm)

Navigation Menu and Routing Tables

Here is the heading for "untested" skeleton for the controller file.:

#!/usr/bin/perl -wU

#----------------------------------------------------------------------
# heading     : Configuration
# description : DHCP manager
# navigation  : 2000 2500
#
# name   : dhcpman,    method : post, url : /dhcpman,     ctlact : Dhcpman#main
# name   : dhcpman1,   method : get,  url : /dhcpman1,    ctlact : Dhcpman#do_leases
# name   : dhcpman2,   method : get,  url : /dhcpman2,    ctlact : Dhcpman#do_winpopup
# name   : dhcpman3,   method : get,  url : /dhcpman3,    ctlact : Dhcpman#do_scan
# name   : dhcpman4,   method : get,  url : /dhcpman4,    ctlact : Dhcpman#do_delete_lease
# name   : dhcpman5,   method : get,  url : /dhcpman5,    ctlact : Dhcpman#do_update_config
#
# routes : end
#
#

The Server Manager 2 system extracts these "comments" from the header of the controller file and builds the navigation menu and the routing tables accordingly.

The Navigation menu controls are described in here (search for "Navigation metadata").

The best link I can find for a description of Mojolicious routes is here.

Perl Main and sub-routines

use strict;
use warnings;
use Mojo::Base 'Mojolicious::Controller';

use constant FALSE => 0;
use constant TRUE  => 1;

use Locale::gettext;
use SrvMngr::I18N;
use SrvMngr qw(theme_list init_session);

use Data::Dumper;
use esmith::util;
use esmith::AccountsDB;

our $db  = esmith::ConfigDB->open() or die("Unable to open Configuration DB");
our $adb = esmith::AccountsDB->open() or die("Unable to open accounts DB");

my %dhcp_data = ();

Necessary library units are identified and Configuration databases opened and the hash to be used to communicate with the template files is initialised.

As can be seen from the routing tables the following routines are specified to be the receipt of control depending on the web page user.

In simplified terms these are the routines (as before currently untested):

sub main {
    #
    # Initial page - full summary of parameters etc
    # Initial para from the Wiki.
    #
    my $c = shift;
    $ddc_data{"first"} = 'dhcp_DESCRIPTION';
    do_display( $c, %dhcp_data );
}

sub do_display {
    #
    # Front parameters page
    #
    my $c = shift;
    # Accumulate parameters for Configuration DB
    # .....
    $c->stash( title => $title, modul => $modul, dhcp_data => \%dhcp_data );
    $c->render( template => 'dhcpman' );

sub do_leases {
	#
	# Show a table of the leases
	#
	my $c = shift;
    $ddc_data{"first"} = 'dhcp_LEASES';
    $ddc_data{"leases") = get_leases_in_array();
    $c->stash( title => $title, modul => $modul, dhcp_data => \%dhcp_data );
    $c->render( template => 'dhcpman' );
}	
	

sub do_winpopup {
	#
	# call to win pop up 
	#
	my $c = shift;
	#..... get winpopup details
    $c->stash( title => $title, modul => $modul, dhcp_data => \%dhcp_data );
    $c->render( template => 'dhcpman' );
}

sub do_scan {
	#
	# call to show scan results
	#
	my $c = shift;
	# ..... get scan results
    $c->stash( title => $title, modul => $modul, dhcp_data => \%dhcp_data );
    $c->render( template => 'dhcpman' );
}
 
sub do_update_config {
	#
	# Update config dhcp parameters 
	# called through form submit.
	#
	my $c = shift;
	# Input results are in $c->param(<fieldname>).
	# If parameters do not validate, then return error message.
	# else write into config DB, and...
	# signal-event and ...return ok
	my $ret = update_config($c);
	if ($ret == 'ok') do_display($c);
	return 
}

sub do_delete_lease {
	#
	# Delete the specified lease
	# Called from link in table of leases
	#
	my $c = shift;
    # Lease in $c->param("lease")
    # Validate  - if not return error message
    # delete it
    # If deletion not ok return message
    # else return "ok"
    my $ret = delete_lease($c);
    if ($ret == "ok") do_display($c);
    return 
}

sub update_config {
	my $c = shift;
	#...do it
	return "ok";
}

sub delete_lease {
	my $c = shift;	
    # ...do it
    return "ok";
}

sub get_leases_in_array {
	my $c = shift;
	my @leases = [];
    # ...do it
    return @leases;
}

The Template Files (dhcpman.html.ep and partials)

Mojolicious Meta Commands

Perl Commands

Html

Translation Strings files

Here is a sed script and extra commands to take a formMagick strings file and make it into a lex file suitable for SM2.


Create a sed script file (cnv_lexi.vi):

/lexicon/ d
/entry/ d
s/'/\\'/g
s/<base>/'ddc_/
s/<\/base>/' => /
s/<trans>/'/
s/<\/trans>/',/
s/\t//g
s/<!\[CDATA\[//g
s/]]>//g
/^$/d
s/        '/'/g
s/         //g
s/=> \n/=> /g

Then the shell script to run it: (extractlex.sh):

#!/bin/sh
cp /etc/e-smith/locale/en-us/etc/e-smith/web/functions/$1 $1.res
sed -f cnv_lexi.vi /etc/e-smith/locale/en-us/etc/e-smith/web/functions/$1 $1.res | tr "\n" "~" | sed 's/\s+~/~/g' | sed 's/~,/,/g' | sed "s/~'~/'/g" | sed s/"~',~'/',~/g" | tr "~" "\n" > $1.lex

Run it by:

./extractlexi.sh dhcpd

You will need to edit the "ddc_" prefix in the .lex file to conform to whatever you want to use.

Then run:

/etc/e-smith/events/actions/locales2-conf

Which will loop through all the lex files and create corresponding .pm files where they do not exist. This could go in the (rpm) install inside the createlinks file (remember to delete the .pm file(s) first).

The .lex File

The .pm File

The Final Panels