OOBD Web UI Design Guideline

This guideline describes, what you need to know to create a package containing lua scipts and webpages ready to run in OOBD

The webUI of OOBD consists of three elements:

• A HTTP server
• A directory, where the scipts are stored in
• An optional, but highly recommended directory, which serves as common pool for all these javascript libraries, which are likely to be used for the script webpages.

When a browser connects to the root URL (simply means “/”), OOBD sends a on-the-fly generated xml file containing the available scripts. The xml file contains also a reference to a xslt style sheet (/theme/default/xslt/start.xsl). These both are rendered by the browser to a menu of the available scripts.

In the OOBD settings a library folder can be configured. In there all global web files can be stored. It contains two folders: libs and theme (more details see below). The theme folder can contain subfolders, one for each theme. It also contains a folder named “default”, which supplies the default theme as long as no other theme is choosen.

A new theme is selected by adding a parameter to any URL send to OOBD as http://youroobdaddress/xxxxx?theme=newtheme. The new theme is stored and used for the futher page requests.

OOBD maps the URLs to the libs and theme folders:

• everything which starts with “/libs/” is mapped to the libs - folder inside the Library folder, which is configured in the settings
• everything which starts with “/theme/default/” is mapped to the theme/<youractualtheme> - folder inside the Library folder, which is configured in the settings
• To use a fixed theme, use “/theme/yourtheme/” instead of “/theme/default/”

The invidual script application can exist in for different versions:

1. as well known compiled lua file with the extension .lbc or .pgp
2. as directory with the suffix .epa
3. as package file, also with the suffix .epa

when a lbc or .pgp file is choosen, the browser loads the default file, referenced as /theme/start.html (where /theme is mapped, as you remember), so the apperance is driven by the theme. This html file needs to have the functionality to handle the openPage, addElement and PageDone commands coming from the scripts. To see how this works, please have a look into the samples supplied.

Both directory and file are equal regarding their content, but while the directory is mainly for the development work, the package file is for the final distribution, as it contains all nessesary files, it's just the zipped content of the directory.

As soon as such an epa package is selected, it acts as root directory for all following page calls, just except the a.m. directory mapping.

Such a package can contain a lot of needfull information or data, like screenshots, symbol, author, copyrights, version etc. All this is collected in the manifest file, which is located in the package root directory.

This file is formated as JSON string.

 { "script": "helloworld.lbc" }

The parameters used by OOBD to start a script and to send back a adjacend web page are actual

where the script parameter is optional, so the startpage can be used to send another menu first which e.g. links to several scripts on one package

As this manifest file can also be loaded as manifest by the web application, it's also a good place to store the application specific settings into it.

Whenever the root page (“/”) is called, this acts like a reset to OOBD. All available packages are readable, so when using a link like /package-name/internal/path/to/file, the file inside the page can be accessed by the URL. This is helpful to store data inside the package, which can be used in the main page to give further information about that package, like an icon, a screenshot or other data. This capability to look into a package is the so called passthrough mode.

This changes as soon as a packet is adressed not by it's filename, but by his id (which is, in fact, the base64 encoded format of the filename). When this happens, that package becomes the new virtual root directory of the webserver until the pure root page (“/”) is addressed.

The diagram below illustrates the handshake between browser and OOBD (only god knows what happens to the renderer…)

It shows the fundamental principle:

1. the browser loads one single html page.
2. this page opens a websocket to OOBD
3. this websocket triggers the execution of a single script
4. Every action needs to happen within this single page, as changing to another page means the loss of the websocket connection, which terminates the script execution

<graphviz dot right> digraph G { rankdir=TB;ratio = fill;

subgraph cluster_0 {
	style=filled;
	color=lightgrey;
	node [style=filled,color=white];
	label = "Browser";

b1[fontsize=11,label=“request\nRoot URL”, shape=box, fixedsize=false, width=.55, peripheries=1]; b2[fontsize=11,label=“Show\nScripts”, shape=box, fixedsize=false, width=.55, peripheries=1];

b3[fontsize=11,label=“request\nScript URL”, shape=box, fixedsize=false, width=.55, peripheries=1];

b4[fontsize=11,label=“render\nContent”, shape=box, fixedsize=false, width=.55, peripheries=1] ; b5[fontsize=11,label=“open\nWebsocket”, shape=box, fixedsize=false, width=.55, peripheries=1] ; b6[fontsize=11,label=“Normal\nOperation”, shape=Mcircle, fixedsize=false, width=.55, peripheries=1] ; b7[fontsize=11,label=“Quit\nPage”, shape=box, fixedsize=false, width=.55, peripheries=1] ; b8[fontsize=11,label=“close\nWebsocket”, shape=box, fixedsize=false, width=.55, peripheries=1];

b2 → b3 ; b4 → b5 → b6 → b7 → b8;

}

subgraph cluster_1 {
	node [style=filled];
	label = "OOBD";
	color=green

o1[fontsize=11,label=“prepare\nList”, shape=box, fixedsize=false, width=.55, peripheries=1];

o2[fontsize=11,label=“open\nScript\nPackage”, shape=box, fixedsize=false, width=.55, peripheries=1] ; o3[fontsize=11,label=“identify\nHTML\nPage”, shape=box, fixedsize=false, width=.55, peripheries=1] ; o4[fontsize=11,label=“deliver\nContent”, shape=box, fixedsize=false, width=.55, peripheries=1] ; o5[fontsize=11,label=“wait for\nWebsocket\nConnection”, shape=circle, fixedsize=false, width=.55, peripheries=1] ; o6[fontsize=11,label=“start\nScript”, shape=box, fixedsize=false, width=.55, peripheries=1] ; o7[fontsize=11,label=“Normal\nOperation”, shape=Mcircle, fixedsize=false, width=.55, peripheries=1]; o8[fontsize=11,label=“stops\nScript”, shape=box, fixedsize=false, width=.55, peripheries=1] ;

o2 → o3; o3 → o4 → o5 → o6 → o7 →o8 ;

}

start → b1;

b1 → o1 → b2; b3 → o2 ;

o4 → b4 ; b5 → o5 ;

b8 → o8 ;

o8 → end

start [shape=Mdiamond];
end [shape=Msquare];

} </graphviz>

To be prepared for later extensions, the following folder structure shall be taken as given as base for own developments. This structure is not hard coded as such, it will be mapped by the webserver to it's real physical location.

+(The Library Directory, configured in OOBD)
    +---libs
    |   +---name
    |       +---version
    |           +--- the lib files
    +---theme
         +---theme1
         |   +--- the theme files
         |
         +---theme1
         |   +--- the theme files
         |
         +---default
             +--- the default theme files

+(The Library Directory, configured in OOBD)
    +---yourapp.lbc (a normal lbc file) 
    |
    +---yourapp.epa (zipped directory)
    |
    +---yourapp.epa 
        +---manifest
        +---yourcontent
        +---secret (PGP protected data, not implemented yet)
            +---yoursecretcontent

OOBD web applications will be distributed as container files. To not generate overhead by packing the common content in each single container, the folders are packed separately

The todays webkits like jQuery, Dojo etc. consist of huge numbers of files. To not have them packed multiple time in each container, they are stored separately.

The name gives the name of the library, the version it's version, however the library provider is counting its version.

The libs content should be 1:1 to the original without any own modifications and tweaks

Modern HML designs allow a common look & feel, controlled by css, a common set of icons etc. By using themes you can easy design and maintaing a lot of app designs without updating them all individually.

The name gives the name of the theme

The theme content should be 1:1 to the original without any own modifications and tweaks

The default theme is used, if no other theme is requested.

in here you store everything, which is unique to your app, means not a common theme or a webkit library

Afer building it, your app container will need to contain at least some content which is public readable, like it's full name, description, Icon, descripted by the MANIFEST.

in the secret subfolder you can stored what you would like to have encrypted by the normal OOBD pgp encryption process