User Tools

Site Tools


doc:webui_guide

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision
Previous revision
doc:webui_guide [2015/12/27 23:01] admindoc:webui_guide [2017/02/04 18:28] (current) – [The Communication Handshake] admin
Line 11: Line 11:
  
  
-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 is rendered by the browser to show what can be used as script.+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 ==== ==== 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. 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://xxxxx?theme=newtheme''. The new theme is stored and used for the futher page requests.+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: 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 "/libs/" is mapped to the libs - folder inside the Library folder, which is configured in the settings  
-  * everything which starts with "/theme" is mapped to the theme/<youractualtheme> - 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/"
  
  
 ===== Structure of a script package ===== ===== Structure of a script package =====
  
-The invidual script application can exist in three different versions: +The invidual script application can exist in for different versions: 
-  as well known compiled lua file with the extension .lbc +  as well known compiled lua file with the extension .lbc or .pgp 
-  as directory with the suffix .epa  +  as directory with the suffix .epa  
-  as package file, also with the suffix .epa+  as package file, also with the suffix .epa
  
-==== the .lbc file ==== +==== the .lbc and .pgp file ==== 
-when a lbc 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+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 ==== ==== the .epa directory or file ====
Line 37: Line 38:
  
 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. 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 ==== ==== 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: 
 +  - the browser loads **one** single html page.
 +  - this page opens a websocket to OOBD
 +  - this websocket triggers the execution of a **single** script
 +  - 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>
 +----
  
-The capability of using a web browser as a graphical frontend to OOBD opens a endless field of possibilies of how the interface can look like and how it acts. To not having all these different ways interfearing which each other, these rules should be followed. 
  
 ===== Folder Structure ===== ===== Folder Structure =====
Line 49: Line 157:
  
 <code> <code>
-+(webroot++(The Library Directory, configured in OOBD
-|   +---lib +    +---libs 
-|   |   +---name +    |   +---name 
-|   |       +---version +    |       +---version 
-|   |           +--- the lib files +    |           +--- the lib files 
-|   +---theme +    +---theme 
-|       +---name +         +---theme1 
-|       |   +---version +         |   +--- the theme files 
-            +--- the theme files +         | 
-      +---(default/1+         +---theme1 
-+---yourapp +           +--- the theme files 
-    +---MANIFEST +         | 
-    +---secret+         +---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         +---yourcontent
 +        +---secret (PGP protected data, not implemented yet)
 +            +---yoursecretcontent
 </code> </code>
 +----
 ===== The meaning of the folder structure ===== ===== The meaning of the folder structure =====
  
-OOBD web sites will be distributed as container files. To not generate overhead by packing the common content in each single container, the folders are packed separately +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 
  
  
-==== lib ====+==== 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 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 ''name'' gives the name of the library, the ''version'' it's version, however the library provider is counting its version.
  
-The lib content should be 1:1 to the original without any own modifications and tweaks+The libs content should be 1:1 to the original without any own modifications and tweaks
  
 ==== theme ==== ==== 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. 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 ''version'' it's version, however the theme provider is counting its version.+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 theme content should be 1:1 to the original without any own modifications and tweaks
  
-The ''default/1'' theme and version is a virtual folder. It's mapped by the webserver to the actual selected standard theme. So when using ''default/1'' as theme, your app will look like the rest of OOBD.+The ''default'' theme is used, if no other theme is requested
  
  
Line 96: Line 215:
  
  
- 
-===== How to use generated tables in WebUI ===== 
- 
-OOBD supplies tools to automatic translate diagnostic specifications into OOBD syntax. It would be quite anouing when these imports would have a fixed design and view. To avoid these, the process shall be as follows: 
-  * the translation shall only transfer the data which is mandatory to supply the web elements. The output shall be pure xml, containing a xlst style sheet directive in it's header. 
-  * the xslt style sheet shall just contain the logical layout and support logic (like some javascript magic), but no design elements. For the design, the xslt file shall reference to an theme instead. Using ''default/1'' also here gives the common program look & feel. 
- 
- 
- 
-===== Theme Structure ===== 
- 
-FIXME to be defined :-) 
- 
-===== The MANIFEST ===== 
- 
-FIXME to be defined :-) 
doc/webui_guide.1451253667.txt.gz · Last modified: 2015/12/27 23:01 by admin