Server Manager2 create panel for contrib

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.

• 

  Front Panel
  

• 

  DHCP Leases
  

• 

  Network Scan
  

• 

  WinPopup
  

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/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.

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).

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

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, epseically after the desktop has been suspended for a while).

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