Documentation of InOSid

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

1.3. Navigation

There are two methods for navigations: menu driven or button driven.

1.3.1.Navigation by Buttons

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.

1.3.2.Menu

The menu must be described by a content and by design:

The content is written to a textfile.

The HTML code is defined in a template.

2. Plugins

2.1. Tasks of a Plugin

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

A plugin has a class (derived from Page) and and a "snippet file" containing the HTML parts of the page.

2.2. Methods to Overwrite (always)

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

2.3. Methods to Overwrite (optional)

The following methods are predefined but can be overwritten.

defineField(): Defines the input fields.
changeContent(): Replaces placeholders in the snippet.
handleButton(): Processes the button pushes.

2.4. Plugin services

The most important helper functions in the base class Page...

addField(): adds an input field with default value, data type...
getField(): gets the field value from the form
putField(): sets a value of an input field
putError(): shows an error message, field or page specific
buildTable(): constructs a HTML table
fillStaticSelected(): defines a combobox with texts from the configuration
fillDynamicSelected(): defines a combobox with calculated texts
autosplit(): converts a string into an array with a automatically found separator
gotoWait(): handles the change to the page "wait"
execute(): executes an external command using the shell server
setRefresh(): initiates the repeated call of the page
addPage(): puts a page into the page chain
delPage(): removes a page from the page chain

.. and in the class SessionBase:

The most important helper functions in the base class Page...

getConfig(): returns a language independent value from the configuration database. The key must be defined
getConfigOrNone(): returns a language independent value from the configuration db. If the key is not found None is returned
getConfigWithoutLanguage(): returns a language dependent value from the configuration database. The key must be defined
getConfigOrNoneWithoutLanguage(): returns a language dependentvalue from the configuration db. If the key is not found None is returned
log(): logs an info message
trace(): logs a debug message
error(): logs an error message
replaceVar(): replaces placeholders in a string with its values. The definition of the placeholder values are in:
- local variables: a dictionary in Page
- configuration db
- special variables: a second dictionary
setLocalVar(): sets a name-value pair for replaceVar()
redirect(): initiates the change to another page
readFile(): reads a file and returns the content
putUserData(): puts a field value outside of the current page
readProgress(): evaluates a progress file
translateTask(): translates an english message (from an external program) into the current language

3. Template and Snippets

3.1. Template pageframe.html

The HTML pages will be built from the template file template/configuration.

This file contains HTML code and placeholders:

{{META_DYNAMIC}}: empty or code for automatic reload.
{{CONTENT}}: will be replaced with the content produced by the current page.
{{INFO}}: empty or log/error message(s)

3.2.Snippets

The snippet file contain HTML snippets. A snippet is a name and HTML code. Inside the code there can be placeholders.

Convention: snippet names are noted in upper case.

The file must define a snippet named "MAIN".

Snippets will automatically read from Page. The derived class can get a single snippet by self._snippet.get(snippetName).

3.3. Placeholders

{{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://example:8086/home
{{URL_FORM}} (optional): the URL of the form action, e.g. http://example:8086/home
The template must contain a <form> element to handle the buttons.
Placeholders can be defined in the configuration database: Convention: the name is devided into page name and variable name, e.g. {{home.txt_title}}

4. Content Template

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.

5. Configuration

5.1. Language Independent Configuration Data

The file conf/applicationX.conf contains configuration data valid for all languages, e.g. the page chain.

# 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

Convention: the placeholder name is divided into page name and variable name.

1. Introduction

1.1. Purpose

1.2. Architecture