Table of Contents

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 Basics

The webUI of OOBD consists of three elements:

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.

The Themes, the Libs and the Default

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:

Structure of a script package

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

the .lbc and .pgp file

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.

the .epa directory or file

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.

the manifest file

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

Parameter Meaning Default
script Lua script, which is executed at start start.lbc
startpage HTML page, which is loaded at start /theme/default/startpage.html

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.

"PassThrough" and "SetRoot" Behaviour

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 Communication Handshake

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>


Folder Structure

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

The meaning of the folder structure

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

libs

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

theme

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.

yourapp

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

secret

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