This document describes the project inosid for developers.

sigui provides a toolkit for developing graphical interfaces for browser based applications.

This is a template and plugin driven approach which can be extended and modified easily.

There is a skeleton offering flow control, handling of configuration, storing of user specific data and so on.

Each page of the application is handled by a plugin implemented by a class derived from Page to administrate this page.

The basic html page is defined in a template. The content area of the page will be created from the plugin.
This allows using one template for all pages (equal design).

The standard http process only allows access to the input field values if a button inside the form has been pushed. Therefore the navigation uses buttons instead of links.

Without this construction the user must push a "store" button and the data will be lost if he does not (very uncomfortable).

With the navigation by buttons the plugin can store the field values and then it changes the page.

• Builds the content area of the page.
• Validates the input fields.
• Sets the error messages.
• Stores the field values in the user data.

The plugin class must overwrite the abstract methods of the class Page. See page.php.

The following methods are predefined but can be overwritten.

• getTemplateName(): Return the template name. Default: "standard.html"
• getInputFields(): Returns an array with the names of the input fields. Default: []

There are helper functions in the base class Page...

• setReplacement(): Sets a value for a marker.
• setFieldError(): Sets an error message for a field if validation has failed.
• setField(): Sets a field value.
• i18n(): gets a language dependent string, e.g. an error message. Note: only for plugin specific strings.
• setDefaultOption(). Sets the selected option of a selection field. Example: NetworkPage.__construct()
• setEmptyToDefault(): Sets an empty text field to a default value. Example: NetworkPage.__construct()
• fillOptions(): replaces the marker ###OPT_X### (X is the fieldname) with the options defined in plugin.opt_x.
• setFieldError(): Sets an error message.
• setReplacement(): Prepare a replacement of a marker inside the content area.
• setField(): Sets the value of an input field.
• isValidContent(): Tests character set of a field value.
• validPassword(): Checks a password.
• validPasswords(): Checks a pair of passwords.
• navigation(): Handles prev and next button.
• readContentTemplate(): Reads the content template().

.. and in the class Session:

• i18n(): gets a language dependent string, e.g. an error message.
• getField(): Returns the field value.
• readFileFromBase(): Loads a template.
• $session->userData->getValue(): Gets a value from the user data.
• $session->userData->setValue(): Puts a value into the user data.
• $session->configuration->getValue(): Gets a value from the configuration.

The template contains markers which will be replaced by the core modules or the plugin.

• ###CONTENT### (needed): Content area. This will be replaced by the plugin.
• ###INFO### (needed): An area for messages.
• ###URL_STATIC### (optional): the URL prefix for static files, e.g. http://localhost/inosid/
• ###URL_SCRIPT### (optional): the URL of the main script, e.g. http://localhost/inosid/install.php
• ###URL_FORM### (optional): the URL of the form action, e.g. http://localhost/inosid/install.php
• The template must contain a <form> element to handle the buttons.
• There must be markers for buttons for navigating: ###BUTTON_PREV### and ###BUTTON_NEXT###. Reason for placing markers instead of the button itself: The first page needs no previous button, the last page needs no next button. The button definitions must be set in the configuration: gui.button.prev and gui.button.next.
• ###txt_x###: x is a name containing letters, digits or '_'. The substitution is defined in the configuration file (language dependent): the key is plugin.txt_x (plugin is the name of current plugin) or default.txt_x (for all plugins).

The content area will be filled by a plugin. It should use a template to divide design and code. The plugin should use markers to communicate with the template.

The filling of the input fields with values inserted earlier will be done by the core modules. Therefore the names of the fields must be known.

Note: X stands for an uppercase field name.

• ###VAL_X###: The field value must be filled by this marker.
• ###ERROR_X###: A placeholder for the error message for the field X.
• ###OPT_X###: The options of a selection field X.
• ###txt_y###: Texts which will be replaced by values defined in the configuration. The key is <plugin>.txt_y (<plugin> is the name of the current plugin).
• ###PART_X###: X is the name of the template defined in plugin/y.parts.content.txt. See Conditional GUI Areas

The file inosid.conf contains configuration data which are used for all clients.

# List of the page names separated by ','. 
# The series defines the effect of the Back and Next buttons.
# The page name is the name of the plugin. 
.gui.pages=home,boot,user,network,run

The configuration has a part for global definitions: these definitions starts with '.'. The other parts are plugin dependent. The definitions in these parts start with the plugin name.

When the user changes the pages (using the back or the next button) the field values will be stored in a file. The filename is client specific: the remote ip address is part of the name. This is not perfect but good enough.

user.user=jonny
user.pass=123
user.pass2=123

If the http header ($_GET or $_POST) contains a button the input field will be set from the http header. Otherwise the fields will be set from the user data. Therefore the field values in the content template must contain markers: ###VAL_X### (X is the uppercase fieldname).

The field validation should be done inside the plugin method onButtonClick().

If a field value is valid the value must be stored in user data: $this->session->userData->setValue(pluginName, fieldName, fieldValue)

Otherwise an error message should be set: $this-<setFieldError(fieldName, errorMessage)

siguibui projects can maintance menus.

At this moment only projects with static pages handle automatically menus.

The content and the structure of a menu depends on the language and will be defined in the file config/menu_<language>.conf.

# Format: <indent-level>  <id> <link> <text>
*	sm1	welcome	siduction OS Manual
**	sm1a	welcome#welcome-gen	siduction OS Manual ⇒
***	-	credits#cred-team	Credits
**	sm1b	welcome#how-to	How to use this manual ⇒
***	-	welcome#how-to	How to use this manual
***	-	welcome#table-contents	Table of Contents
**	sm1c	help#help-gen	Getting Help ⇒
***	-	help#help-gen	Where and how to get help
***	-	help#paste	IRC !paste
**	-	wel-quickstart#welcome-quick	siduction Quick Start Guide
*	sm2	cd-dl-burning	ISO Content, Releases, Download Mirrors and Burning
**	sm2a	cd-content#cd-content	ISO Content and system requirements ⇒
***	-	sys-admin-release#rolling	Release Notes
**	sm2b	cd-dl-burning#download-siduction	siduction Mirrors, Downloading and Burning ⇒
***	-	cd-dl-burning#md5	md5 Checksum
***	-	cd-dl-burning#burn-nero	Burning in Windows
***	-	cd-dl-burning#burn-linux	Burning in Linux
***	-	cd-no-gui-burn#burning-no-gui	burniso script
***	-	cd-no-gui-burn#burn-no-gui-gen	Burning without a GUI
***	-	cd-dl-burning#download-siduction	siduction Download Mirrors

• The indent-level defines the hierarchy of the menu.
• The id is a value which can be used in the XML to mark uniquly a tag.
• The link defines the page which will displayed after this menu item has been clicked.
• The text will be displayed in the menu. It is the language dependent part.

The design of the menu can be defined in config/menu.parts.txt. It contains a definition for each hierarchical level.

Only in very special cases the following example must be changed.

LEVEL_0:
 <ul>
###ENTRIES###
 </ul>

ENTRY_0:
  <li###class_current###>
   <a href="###link###">###title###</a>
###SUBMENUS###
  </li>

LEVEL_1:
   <ul ###id###>
###ENTRIES###
   </ul>

ENTRY_1:
    <li###class_current###>
     <a href="###link###">###title###</a>
###SUBMENUS###
    </li>

LEVEL_2:
     <ul class="sub2-menu"###id###>
###ENTRIES###
     </ul>

ENTRY_2:
      <li###class_current###><a href="###link###">###title###</a></li>

CLASS_CURRENT:
 class="current-item"

ID:
 id="###id###"

END:

• LEVEL_<level> defines the body of a menu list with the same level.
• ENTRY_<level> defines the body of a menu item at this level.
• ###ENTRIES### will be replaced by all bodies of the menu list.
• ###SUBMENUS### will be replaced by the submenus of the menu item (if there are any).
• ###CLASS_CURRENT### will be replaced by the template CLASS_CURRENT if the menu item belongs to the tree of the current displayed menu item.
• ###link###, ###text### are the properties of the menu item.
• ###id### will be replaced by the template ID if the menu item has an id not equal to '-'.

If there are more than one menu the part names must be completed by a prefix, e.g. TOP_MENU_LEVEL_0, TOP_MENU_ENTRY_0 and so on.

A good example for a project with static pages is the siduction manual. There are more than 50 pages. Realized with true static pages the work for maintance is too large: If there is a change in the html-structure of the menu, each of the pages must be changed too.

The solution is a project derived from siguibui. The common design of all pages will be defined only once.

Every static page should exist in each language. This forms the directory tree.

static
	en
		welcome-en.htm
		content-en.htm
	de
		welcome-de.htm
		content-de.htm
	pt-br
		welcome-pt-br.htm
		content-pt-br.htm

Because of data migration and easy development the content file of the static page can be a valid HTML or XML file. The system extracts the pure content (without header, menu...) and puts this content into the template config/<project>.html.

The extraction is driven by pattern matching:

There are 2 parameters in config/<project>_<language>.conf to control this extraction:

static.content.start=id="main-page"
static.content.end.ignoreddivs=1

• static.content.start: This defines a text pattern where the interesting content starts. A good choice is the class or id of the spanning div.
• static.content.end.ignoreddivs is a count. So much <div> in top of <body> will be ignored.

All texts are stored in the configuration files, none in the program code and none in the templates.

For each supported language there must be a configuration file. The file name convention: <name>_<language>.<ext>, e.g. inosid_de.conf

Templates can contain markers ###txt_X### (X is being a name with letters, digits and '_'). Entries in the configuration must contain <plugin>.txt_X or default.txt_x. <plugin> is the name of a plugin. If the plugin using the template has a so defined entry this value will be substituted. If not, the plugin independent variant will be used.

Rules are needed to integrate the plugins. For a simple explanation, an example: user (a page asking for username and password)

• Name of the plugin: user
• Name of the file containing the plugin class: userpage.php
• Name of the plugin class: UserPage
• Prefix of the data in the data file: "user."
• Name of the content template: "user.content.txt"

This chapter offers solutions for tasks belonging to development with the toolkit.

The example project is named net-center.

There is a script build/build.sh which creates an installable Debian package. This is a good base for starting a new project.

Task:
A input field for a ipaddress should be added to the page wlan.

Solution:

• plugin/wlan.content.txt (insert the html code):
  ###txt_ipaddress###: <input type="text" name="ipaddress" value="###VAL_IPADDRESS###">
• config/net-center.conf (insert the texts which should be translated):
  wlan.txt_ipaddress%=IP Address
• config/net-center_de.conf (insert the german translations):
  wlan.txt_ipaddress%=IP-Adresse
• plugin/wlanpage.php:
  • Register the inputfield:
    function getInputFields():
    $rc = array('mode', 'ipaddress', 'device');
  • Possible, but not meaningful for ipaddress: Set a default value from the configuration if the field is not set.
    In the function _construct():
    $this->setEmptyToDefault('ipaddress', 'wlan.DEFAULT_IP');
• plugin/*.php (fetch the current value of the field:)
  $curValue = $this->session->userData->getValue('wlan', 'ipaddress');

Note:
If the field value should be empty on a redisplay the makro ###VAL_...### must not be set.

Task:
A combobox for a mode should be added to the page wlan. There are two alternatives (dhcp and static address) which do not change. But the values depend on the current language. Therefore they must be stored in the configuration file.

Solution:

• plugin/wlan.content.txt (insert the html code):
  <select name="mode" size="2">
###OPT_MODE### </select>
• config/net-center.conf (insert the alternatives which should be translated):
  wlan.opt_mode%=DHCP;Static IP
• config/net-center_de.conf (insert the german translations):
  wlan.opt_mode%=DHCP;Statische IP
• plugin/wlanpage.php:
  • Register the inputfield:
    function getInputFields():
    $rc = array('mode', 'ipaddress', 'device');
• plugin/*.php (fetch the current value of the field:)
  $curValue = $this->session->userData->getValue('wlan', 'mode');

Task:
A combobox for a device should be added to the page wlan. The values (e.g. wlan0 and wlan1) are dynamic: they must be calculated by the program.

Solution:

• plugin/wlan.content.txt (insert the html code):
  <select name="device" size="1">
###OPT_DEVICE### </select>
• plugin/wlanpage.php:
  • Register the inputfield:
    function getInputFields():
    $rc = array('mode', 'ipaddress', 'device');
  • Set a default value (if no value is set). More exactly: set the default index.
    function _construct():
    $this->setDefaultOption('device', 0, true);
  • Store the calculated values into the user configuration:
    Anywhere but before the call of build():
    $this->session->userData->setValue('wlan', 'opt_device', '-');
  • Write the alternatives into the html:
    function build():
    $this->fillOptions('device', true);
    Note for conditional HTML code: the field must be available in $this->content
• plugin/*.php (fetch the current value of the field:)
  $curValue = $this->session->userData->getValue('wlan', 'device');

Task:
The value of the field ipaddress on the page wlan must be checked for a correct syntax. In the case of an error a message must be displayed.

Solution:

• plugin/wlan.content.txt (insert the field code and an field specific error makro):
  <field name="ipaddress" value="###VAL_IPADDRESS###">
###ERROR_IPADDRESS###
• plugin/wlanpage.php:
  • Register the inputfield:
    function getInputFields():
    $rc = array('mode', 'ipaddress', 'mode');
  • Implement the validation:
    function onButtonClick():
    if (strcmp($button, 'button_next') == 0){
 $value = $this->getFieldValue('ipaddress');
 if (! preg_match('^(\d{1,3}\.){3}\d{1,3}', $value))
  $this->setFieldError($this->i18n('err_ipaddr'));
}
    
  • Note: The call of onButtonClick() is done before the creation of the page (WlanPage._construct())!
• config/net-center.conf (insert the error message):
  wlan.err_ipaddress%=No valid IP address, e.g. 192.168.7.1
• config/net-center_de.conf (insert the german translations):
  wlan.err_ipaddress%=Keine gültige IP-Adresse, z.B. 192.168.7.1
• Instead of a field specific error message location a central location can be used. In this case the makro must be '###ERROR_MESSAGE###' and the method setErrorMessage() must be called for displaying.

Task:
A certain screen area should be displayed only under some conditions. The example is a division to show the last command log message. This will be showed only if a command is executed.

Solution:

• Create a file plugin/wlan.parts.content.txt. This one file will be used for all conditional templates
• Choose a name for the part, e.g. LAST_LOG.
• plugin/wlan.parts.content.txt:
  LAST_LOG:
<h2>###txt_header_last_log</h2>
<div class="log">###txt_last_log###
</div>
• plugin/wlan.content.txt:
  Put a the makro ###PART_LAST_LOG### to the html code where the log message should be displayed.
• plugin/wlanpage.php:
  • Load the makros in function build():
    $this->readContentTemplate();
$this->readHtmlTemplates();
  • Switch the last log part on or off:
    if ($hasMessage)
  $this->clearPart('LAST_LOG');
else {
  $this->replacePartWithTemplate('LAST_LOG');
  $lastLog = $this->session->readFile('last.log');
  $this->content = str_replace('###txt_last_log###', $lastLog, $this->content);
}
  • You can also replace a given makro with more then one alternative templates.
    if (! $hasMessage)
  $this->replacePartWithTemplate('LAST_LOG', 'NO_LOG_MESSAGE');
else
  $this->replacePartWithTemplate('LAST_LOG');
Note:
    $this->replacePartWithTemplate('LAST_LOG')
    is an abbrevation of
    $this->replacePartWithTemplate('LAST_LOG', 'LAST_LOG')

Syntax of a template definition file:

file ::= {<template-definition> }+
template-definition ::= <header> <body>
header ::= <name> ':' '\n'
body ::= { <body-line> }+
body-line ::= <html-code-or-makros> '\n'

Example of a template definition file:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="###LANGUAGE###">
<head>
	<title>###txt_title###</title>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
	<style type="text/css" media="all">@import url("../config/content.css");</style>
###META_DYNAMIC###
</head>
<body class="body-main">
<div><img class="header-img" alt="header logo siduction" src="../images/siduction-logo-web.png" />
</div>
<div id="content">
###CONTENT###
</div> <!--content -->
</body>
</html>