2,411
edits
Changes
From SME Server
Jump to navigationJump to searchSME Server:Documentation:Developers Manual:Chapter10 (view source)
Revision as of 11:52, 25 April 2008
, 11:52, 25 April 2008Splitting the SME Server Developers Guide (and relocating)
<div class="CHAPTER">
=The server-manager web interface=
The user interfaces to the SME Server (the web based server-manager and the text mode console interface) perform their work by modifying the master system configuration database to describe the new system configuration, then regenerating the various application configuration files by <span class="emphasis">''signalling an event''</span>.
This decoupling of the user interfaces from the system configuration allows packages to be added and removed without modifying the user interface code. It also allows all actions performed by the manager to be scripted, if this is desired. For example, if a new package needs to expand a template when users are created, it can just create the appropriate links in the <tt class="FILENAME">user-create</tt> event.
<div class="SECT1">
----
==The web directory==
The primary files which make up the SME Server manager are kept in the <tt class="FILENAME">/etc/e-smith/web/</tt> directory. These files define the layout of the web functions and require auxiliary files which provide translations and the implementation of the functions.
<div class="TABLE">
'''Table 10-1. Web interface directories'''
{| class="CALSTABLE" border="1"
! Name
! Description
| <tt class="FILENAME">/etc/e-smith/web/common/</tt>
| Common files such as images and page headers.
|-
| <tt class="FILENAME">/etc/e-smith/web/functions/</tt>
| Screen definitions, written in FormMagick XML. The scripts in this directory are linked into the <tt class="FILENAME">cgi-bin</tt> directory of the panels in which they should appear.
|-
| <tt class="FILENAME">/etc/e-smith/web/panels/</tt>
| Top-level directory for panel definitions. Each panel is a collection of screens, presented as a single user interface.
|-
| <tt class="FILENAME">./manager/{cgi-bin,common,html}/</tt>
| Subdirectories for the HTML, CGI and common files for the "manager" panel, which is accessed by the <span class="emphasis">''/server-manager/''</span> URL.
|-
| <tt class="FILENAME">./password/{cgi-bin,common,html}/</tt>
| Subdirectories for the "password" panel, which is accessed by the <span class="emphasis">''/user-password/''</span> URL.
|-
| <tt class="FILENAME">/etc/e-smith/locale/</tt>
| Top-level directory for all panel localizations.
|-
| <tt class="FILENAME">./en-us/etc/e-smith/web/functions/</tt>
| Subdirectory containing localization into US English.
|-
| <tt class="FILENAME">./fr/etc/e-smith/web/functions/</tt>
| Subdirectory containing localization into French.
|-
| <tt class="FILENAME">/usr/lib/perl5/site_perl/</tt>
| Top-level directory for all Perl modules.
|-
| <tt class="FILENAME">./esmith/FormMagick/Panel/</tt>
| Subdirectory containing Perl modules which provide the implementations to support the panel definitions.
|}
</div></div><div class="SECT1">
----
==Web function scripts==
The <tt class="FILENAME">functions</tt> subdirectory contains all of the screen definitions for all panels. Each screen definition is a CGI script which displays the screen and also handles the CGI form submission. The scripts are written using the <code class="CLASSNAME">CGI::FormMagick</code> toolkit, which separates the screen layout from the panel implementation code, facilitates form validation and provides full support for localisation of the manager.
<div class="SECT2">
----
===An overview of FormMagick===
<div class="SECT3">
====Layout of a FormMagick script====
This section describes the FormMagick panel which is used in [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#EXERCISE5 the Section called ''Exercise 5: Adding a user interface screen'' in Chapter 12]. A typical FormMagick web function starts with the script preamble, which notes it as a perl script and informs the vi editor that the majority of the file is XML, rather than perl.
<nowiki>#!/usr/bin/perl -wT
# vim: ft=xml:</nowiki>
This is followed by the navigation settings metadata, which determine where the script should appear in the manager menu bar.
<nowiki>#----------------------------------------------------------------------
# heading : Demo
# description : Logger
# navigation : 1000 1000
#----------------------------------------------------------------------</nowiki>
Next is a small number of lines of perl which create a FormMagick object and then call the <code class="CLASSNAME">display</code> method to draw the page.
use strict;
use warnings;
use esmith::FormMagick::Panel::loggerdemo;
my $f = esmith::FormMagick::Panel::loggerdemo->new();
$f->display();
And finally there is the FormMagick XML page description, which starts at the <var class="LITERAL">__DATA__</var> marker and continues to the end of file. We will examine that in the next section.
</div><div class="SECT3">
----
====The FormMagick XML description====
The FormMagick XML is divided into a preamble and then a set of pages. The preamble contains references to the title, header and footer of the page. These are usually the same on all pages so that a consistent header and footer is displayed.
<form
title="FORM_TITLE"
header="/etc/e-smith/web/common/head.tmpl"
footer="/etc/e-smith/web/common/foot.tmpl">
The upper-case word <var class="LITERAL">FORM_TITLE</var> is a placemarker token for a phrase which needs to be localised. There is an associated lexicon file which provides the translation of this token into the appropriate language for the user accessing the panel, as specified by their browser settings. For example, here is the English lexicon entry for that token:
<entry>
<base>FORM_TITLE</base>
<trans>Logger demo</trans>
</entry>
If the user browses the panel with English as their chosen language, the panel will display in English. If they choose French, French will be displayed. If an unsupported language is chosen, FormMagick will fall back to US English. Adding another language is basically a matter of providing the lexicon for that language.
The rest of the XML description is a series of pages. In this example there is a single page. Each page starts with a <var class="LITERAL">page</var> tag, which gives the page a name for later reference and can optionally specify a <var class="LITERAL">pre-event</var> and <var class="LITERAL">post-event</var>.
<page name="First" pre-event="print_status_message()"
post-event="change_settings">
The <var class="LITERAL">pre-event</var> is a reference to a function in the panel implementation (described later) and called before the page is loaded. The <var class="LITERAL">post-event</var> is called after the user submits the information on the page, for example by pressing the <var class="LITERAL">Save</var> button.
Each page is then composed of a number of fields
<field
type="select"
id="loggerdemo_Interval"
options="10,20,30,40,50"
value="get_interval()">
<label>LABEL_LOGGERDEMO_INTERVAL</label>
</field>
<field
type="select"
id="loggerdemo_status"
options="'disabled' => 'DISABLED', 'enabled' => 'ENABLED'"
value="get_status()">
<label>LABEL_LOGGERDEMO_STATUS</label>
</field>
Each field describes a user interface widget (e.g. a select box) and provides the data required for that widget. These data may be static lists (the options of the first field above), a set of key/value pairs (the options of the second field above) or dyanamic data returned from a subroutine (the value parameters in each of the fields).
The command '''perldoc CGI::FormMagick''' provides detailed documentation about the supported field types.
It is also possible to call subroutines which generate the required HTML for a section of a page. For example, buttons are often added by calling the <var class="LITERAL">print_button</var> routine:
<subroutine src="print_button('SAVE')" />
<div class="NOTE"><blockquote class="NOTE">
'''Note: '''Buttons should be part of the FormMagick XML description, and hopefully will be in the future. The <var class="LITERAL">print_button</var> routine is a workaround for the lack of a button widget.
</blockquote></div>
Each page must finish with a closing page tag:
</page>
After all of the pages have been described there is a single XML tag to close the form.
</form>
</div></div><div class="SECT2">
----
===Navigation metadata===
The web manager's navigation frame is generated automatically by examining the contents of the <tt class="FILENAME">/etc/e-smith/web/functions/</tt> directory.
In order to be listed in the navigation frame, your CGI script must contain <var class="LITERAL">heading</var>, <var class="LITERAL">description</var> and <var class="LITERAL">navigation</var> lines, usually at the top of the script:
<nowiki># heading : Configuration
# description : E-mail
# navigation : 6000 6700</nowiki>
These define the category heading under which your add-on's admin interface should be listed, the title it should have, and the priority it should have in the listing order. The first number gives the priority of the heading (usually a multiple of 1000) and the second number gives the priority of this particular item within that heading group. In other words, a heading with a priority of 1000 will come before one with 6000 in the navigation panel, and within that heading category the individual items are listed in order from highest to lowest.
To figure out what numbers to give your own script, figure out where you want it to appear in the navigation panel then check source code for the scripts which appear before and after where you want to be. For instance, if you want your item to appear before "Remote Access" and after "Local Networks" in the navigation menu, you would look at <tt class="FILENAME">/etc/e-smith/web/functions/remoteaccess</tt> and <tt class="FILENAME">/etc/e-smith/web/functions/localnetworks</tt> and find the following:
<nowiki># heading : Security
# description : Remote access
# navigation : 5000 5200
# heading : Security
# description : Local networks
# navigation : 5000 5300</nowiki>
You might then put something these lines in your own script:
<nowiki># heading : Security
# description : Advanced security
# navigation : 5000 5250</nowiki>
<div class="TIP"><blockquote class="TIP">
'''Tip: '''When naming your script, use a name which closely resembles the description (and hence the name in the navigation panel). This makes it easier to correlate menu items to Perl scripts. Just take the descriptive name and remove capital letters, punctuation and spaces. For instance, "Advanced security" might become <tt class="FILENAME">/etc/e-smith/web/functions/advancedsecurity</tt>
</blockquote></div></div><div class="SECT2">
----
===Permissions and security===
The CGI scripts must have elevated permissions (setuid <var class="LITERAL">root</var>) in order to write to the configuration database, since they will be run by the web server (which runs as user <var class="LITERAL">www</var>). To ensure that these scripts can only be run by system administrators, the permissions on the parent directory and the scripts are set so that only the members of the <var class="LITERAL">admin</var> group can run them. These panels are also restricted in the web server configuration so that only the <var class="LITERAL">admin</var> user can access them.
</div></div><div class="SECT1">
----
==Common files==
The <tt class="FILENAME">common</tt> subdirectory contains any static files (such as images) which are used by multiple panels.
</div><div class="SECT1">
----
==Panel definitions==
The <tt class="FILENAME">panels</tt> directory contains the panel definitions. There is one subdirectory for each panel. Each panel must have html and cgi-bin subdirectories. The cgi-bin subdirectory should contain only symbolic links to the actual CGI scripts in the functions directory, and the html directory should contain the main index.html file for the panel, as well as any required navigation links.
<div class="NOTE"><blockquote class="NOTE">
'''Note: '''The word panel is also sometimes used to refer to an individual web manager web function.
</blockquote></div>
Keeping the CGI scripts for all panels in a shared directory makes it much easier to create auxiliary panels with slightly different options and permissions. You can just copy the entire panel directory, then customize the access permissions and navigation links. For example, it would be very straightforward to create a password-protected panel which only allowed the creation and deletion of user accounts. That task could be delegated to administrative staff.
</div></div></div><div class="PART"><div class="TITLEPAGE">
=III. How to create an SME Server package - step by step=
<div class="TOC">
; '''Table of Contents'''
; 11. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#GETTING-STARTED Getting started]
; 12. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#TUTORIAL Getting to know how to customize the SME Server]
; 13. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#APPLICATION-PACKAGING Packaging your application]
; 14. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#AEN1577 The SME Server development environment]
</div></div>
=The server-manager web interface=
The user interfaces to the SME Server (the web based server-manager and the text mode console interface) perform their work by modifying the master system configuration database to describe the new system configuration, then regenerating the various application configuration files by <span class="emphasis">''signalling an event''</span>.
This decoupling of the user interfaces from the system configuration allows packages to be added and removed without modifying the user interface code. It also allows all actions performed by the manager to be scripted, if this is desired. For example, if a new package needs to expand a template when users are created, it can just create the appropriate links in the <tt class="FILENAME">user-create</tt> event.
<div class="SECT1">
----
==The web directory==
The primary files which make up the SME Server manager are kept in the <tt class="FILENAME">/etc/e-smith/web/</tt> directory. These files define the layout of the web functions and require auxiliary files which provide translations and the implementation of the functions.
<div class="TABLE">
'''Table 10-1. Web interface directories'''
{| class="CALSTABLE" border="1"
! Name
! Description
| <tt class="FILENAME">/etc/e-smith/web/common/</tt>
| Common files such as images and page headers.
|-
| <tt class="FILENAME">/etc/e-smith/web/functions/</tt>
| Screen definitions, written in FormMagick XML. The scripts in this directory are linked into the <tt class="FILENAME">cgi-bin</tt> directory of the panels in which they should appear.
|-
| <tt class="FILENAME">/etc/e-smith/web/panels/</tt>
| Top-level directory for panel definitions. Each panel is a collection of screens, presented as a single user interface.
|-
| <tt class="FILENAME">./manager/{cgi-bin,common,html}/</tt>
| Subdirectories for the HTML, CGI and common files for the "manager" panel, which is accessed by the <span class="emphasis">''/server-manager/''</span> URL.
|-
| <tt class="FILENAME">./password/{cgi-bin,common,html}/</tt>
| Subdirectories for the "password" panel, which is accessed by the <span class="emphasis">''/user-password/''</span> URL.
|-
| <tt class="FILENAME">/etc/e-smith/locale/</tt>
| Top-level directory for all panel localizations.
|-
| <tt class="FILENAME">./en-us/etc/e-smith/web/functions/</tt>
| Subdirectory containing localization into US English.
|-
| <tt class="FILENAME">./fr/etc/e-smith/web/functions/</tt>
| Subdirectory containing localization into French.
|-
| <tt class="FILENAME">/usr/lib/perl5/site_perl/</tt>
| Top-level directory for all Perl modules.
|-
| <tt class="FILENAME">./esmith/FormMagick/Panel/</tt>
| Subdirectory containing Perl modules which provide the implementations to support the panel definitions.
|}
</div></div><div class="SECT1">
----
==Web function scripts==
The <tt class="FILENAME">functions</tt> subdirectory contains all of the screen definitions for all panels. Each screen definition is a CGI script which displays the screen and also handles the CGI form submission. The scripts are written using the <code class="CLASSNAME">CGI::FormMagick</code> toolkit, which separates the screen layout from the panel implementation code, facilitates form validation and provides full support for localisation of the manager.
<div class="SECT2">
----
===An overview of FormMagick===
<div class="SECT3">
====Layout of a FormMagick script====
This section describes the FormMagick panel which is used in [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#EXERCISE5 the Section called ''Exercise 5: Adding a user interface screen'' in Chapter 12]. A typical FormMagick web function starts with the script preamble, which notes it as a perl script and informs the vi editor that the majority of the file is XML, rather than perl.
<nowiki>#!/usr/bin/perl -wT
# vim: ft=xml:</nowiki>
This is followed by the navigation settings metadata, which determine where the script should appear in the manager menu bar.
<nowiki>#----------------------------------------------------------------------
# heading : Demo
# description : Logger
# navigation : 1000 1000
#----------------------------------------------------------------------</nowiki>
Next is a small number of lines of perl which create a FormMagick object and then call the <code class="CLASSNAME">display</code> method to draw the page.
use strict;
use warnings;
use esmith::FormMagick::Panel::loggerdemo;
my $f = esmith::FormMagick::Panel::loggerdemo->new();
$f->display();
And finally there is the FormMagick XML page description, which starts at the <var class="LITERAL">__DATA__</var> marker and continues to the end of file. We will examine that in the next section.
</div><div class="SECT3">
----
====The FormMagick XML description====
The FormMagick XML is divided into a preamble and then a set of pages. The preamble contains references to the title, header and footer of the page. These are usually the same on all pages so that a consistent header and footer is displayed.
<form
title="FORM_TITLE"
header="/etc/e-smith/web/common/head.tmpl"
footer="/etc/e-smith/web/common/foot.tmpl">
The upper-case word <var class="LITERAL">FORM_TITLE</var> is a placemarker token for a phrase which needs to be localised. There is an associated lexicon file which provides the translation of this token into the appropriate language for the user accessing the panel, as specified by their browser settings. For example, here is the English lexicon entry for that token:
<entry>
<base>FORM_TITLE</base>
<trans>Logger demo</trans>
</entry>
If the user browses the panel with English as their chosen language, the panel will display in English. If they choose French, French will be displayed. If an unsupported language is chosen, FormMagick will fall back to US English. Adding another language is basically a matter of providing the lexicon for that language.
The rest of the XML description is a series of pages. In this example there is a single page. Each page starts with a <var class="LITERAL">page</var> tag, which gives the page a name for later reference and can optionally specify a <var class="LITERAL">pre-event</var> and <var class="LITERAL">post-event</var>.
<page name="First" pre-event="print_status_message()"
post-event="change_settings">
The <var class="LITERAL">pre-event</var> is a reference to a function in the panel implementation (described later) and called before the page is loaded. The <var class="LITERAL">post-event</var> is called after the user submits the information on the page, for example by pressing the <var class="LITERAL">Save</var> button.
Each page is then composed of a number of fields
<field
type="select"
id="loggerdemo_Interval"
options="10,20,30,40,50"
value="get_interval()">
<label>LABEL_LOGGERDEMO_INTERVAL</label>
</field>
<field
type="select"
id="loggerdemo_status"
options="'disabled' => 'DISABLED', 'enabled' => 'ENABLED'"
value="get_status()">
<label>LABEL_LOGGERDEMO_STATUS</label>
</field>
Each field describes a user interface widget (e.g. a select box) and provides the data required for that widget. These data may be static lists (the options of the first field above), a set of key/value pairs (the options of the second field above) or dyanamic data returned from a subroutine (the value parameters in each of the fields).
The command '''perldoc CGI::FormMagick''' provides detailed documentation about the supported field types.
It is also possible to call subroutines which generate the required HTML for a section of a page. For example, buttons are often added by calling the <var class="LITERAL">print_button</var> routine:
<subroutine src="print_button('SAVE')" />
<div class="NOTE"><blockquote class="NOTE">
'''Note: '''Buttons should be part of the FormMagick XML description, and hopefully will be in the future. The <var class="LITERAL">print_button</var> routine is a workaround for the lack of a button widget.
</blockquote></div>
Each page must finish with a closing page tag:
</page>
After all of the pages have been described there is a single XML tag to close the form.
</form>
</div></div><div class="SECT2">
----
===Navigation metadata===
The web manager's navigation frame is generated automatically by examining the contents of the <tt class="FILENAME">/etc/e-smith/web/functions/</tt> directory.
In order to be listed in the navigation frame, your CGI script must contain <var class="LITERAL">heading</var>, <var class="LITERAL">description</var> and <var class="LITERAL">navigation</var> lines, usually at the top of the script:
<nowiki># heading : Configuration
# description : E-mail
# navigation : 6000 6700</nowiki>
These define the category heading under which your add-on's admin interface should be listed, the title it should have, and the priority it should have in the listing order. The first number gives the priority of the heading (usually a multiple of 1000) and the second number gives the priority of this particular item within that heading group. In other words, a heading with a priority of 1000 will come before one with 6000 in the navigation panel, and within that heading category the individual items are listed in order from highest to lowest.
To figure out what numbers to give your own script, figure out where you want it to appear in the navigation panel then check source code for the scripts which appear before and after where you want to be. For instance, if you want your item to appear before "Remote Access" and after "Local Networks" in the navigation menu, you would look at <tt class="FILENAME">/etc/e-smith/web/functions/remoteaccess</tt> and <tt class="FILENAME">/etc/e-smith/web/functions/localnetworks</tt> and find the following:
<nowiki># heading : Security
# description : Remote access
# navigation : 5000 5200
# heading : Security
# description : Local networks
# navigation : 5000 5300</nowiki>
You might then put something these lines in your own script:
<nowiki># heading : Security
# description : Advanced security
# navigation : 5000 5250</nowiki>
<div class="TIP"><blockquote class="TIP">
'''Tip: '''When naming your script, use a name which closely resembles the description (and hence the name in the navigation panel). This makes it easier to correlate menu items to Perl scripts. Just take the descriptive name and remove capital letters, punctuation and spaces. For instance, "Advanced security" might become <tt class="FILENAME">/etc/e-smith/web/functions/advancedsecurity</tt>
</blockquote></div></div><div class="SECT2">
----
===Permissions and security===
The CGI scripts must have elevated permissions (setuid <var class="LITERAL">root</var>) in order to write to the configuration database, since they will be run by the web server (which runs as user <var class="LITERAL">www</var>). To ensure that these scripts can only be run by system administrators, the permissions on the parent directory and the scripts are set so that only the members of the <var class="LITERAL">admin</var> group can run them. These panels are also restricted in the web server configuration so that only the <var class="LITERAL">admin</var> user can access them.
</div></div><div class="SECT1">
----
==Common files==
The <tt class="FILENAME">common</tt> subdirectory contains any static files (such as images) which are used by multiple panels.
</div><div class="SECT1">
----
==Panel definitions==
The <tt class="FILENAME">panels</tt> directory contains the panel definitions. There is one subdirectory for each panel. Each panel must have html and cgi-bin subdirectories. The cgi-bin subdirectory should contain only symbolic links to the actual CGI scripts in the functions directory, and the html directory should contain the main index.html file for the panel, as well as any required navigation links.
<div class="NOTE"><blockquote class="NOTE">
'''Note: '''The word panel is also sometimes used to refer to an individual web manager web function.
</blockquote></div>
Keeping the CGI scripts for all panels in a shared directory makes it much easier to create auxiliary panels with slightly different options and permissions. You can just copy the entire panel directory, then customize the access permissions and navigation links. For example, it would be very straightforward to create a password-protected panel which only allowed the creation and deletion of user accounts. That task could be delegated to administrative staff.
</div></div></div><div class="PART"><div class="TITLEPAGE">
=III. How to create an SME Server package - step by step=
<div class="TOC">
; '''Table of Contents'''
; 11. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#GETTING-STARTED Getting started]
; 12. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#TUTORIAL Getting to know how to customize the SME Server]
; 13. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#APPLICATION-PACKAGING Packaging your application]
; 14. [http://wiki.contribs.org/The_SME_Server_Developer%27s_Guide#AEN1577 The SME Server development environment]
</div></div>
