WireLess Mobile V1.x AOBE Applicative Transitions 

 

 

 

 

 

Relative documents :

 

·        WireLess Mobile 1.0 Channel Designer User's Manual

·        WireLess Mobile - Sample Channel Description


1          Introduction  3

2      Solution Architecture Design. 3

2.1        The Applicative Transitions Model 3

2.2        A complete example : the List Selector 4

2.3        Resources Storage. 6

2.4        Notation for Diagramming Applicative Transitions Systems 7

3      Standard Mechanisms Design. 9

3.1        Applicative transitions 9

3.1.1    The "call://" and "exec://" protocols. 9

3.1.2    The "retpage" and "go" arguments. 10

3.1.3    Examples. 10

3.1.4    Standard Applicative Transitions. 11

3.2        HTML pages generation. 12

3.2.1    HTML Templates. 12

3.2.2    HTML Templates Interpretation. 13

3.2.3    Templates Sections, CHtmlPageMaker and Applicative Transitions. 13

3.3        Database. 15

3.3.1    Schema. 15

3.3.2    The DB Query Processor 16

3.4        Gobal simplification. 17


1         Introduction

This document describes the AOBE Applicative Transitions technology and framework and its use to implement the Data base support in AOBE for PocketPC.

2         Solution Architecture Design

2.1      The Applicative Transitions Model

The Applicative Transitions Model is the heart of the solution :

 


2.2      A complete example : the List Selector

Here is how the List Selector looks like :

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

It is called from a link such as :

<a href="call://DisplayList@ qry=SelLst.qry&tpl=SelLst.tpl ">Mes listes</a>

 

Here is the HTML code of this page :

<html><body><font face="verdana">

<font size="3"><p align="center"><b>Select Active List</b></p></font>

<hr width="75%">

<form method="POST" action="call://SetActLst?qry=ActLst.qry&tpl=ActLst.tpl">

  <input type="radio" name="LSTNAM" value="Liste 1">Liste 1<br>

  <input type="radio" name="LSTNAM" value="Liste 2">Liste 2<br>

  <input type="radio" name="LSTNAM" value="Liste 3">Liste 3<br>

  <center><input type="submit" name="BTN_ACT" value="Select"> </center>

</form>

<hr width="75%">

<a href="CIDHP.html"><font face="Verdana" size="1">Home</font></a>

</font></body></html>

 

When the Select button is clicked -let's assume that the second radio button is checked- this generates the following named arguments list:

Tpl

qry

LSTNAM

BTN_ACT

ActLst.tpl

ActLst.qry

Liste 2

Select

 

Then the ActLst.qry DB query script file is loaded :

SELECT Items.REF, Items.NAM

FROM (ListItems RIGHT JOIN Lists ON ListItems.LSTnum=Lists.num)

      LEFT JOIN Items ON ListItems.ITMnum=Items.num

WHERE Lists.NAM='$LSTNAM$';

 

In this situation, $LSTNAM$ is replaced by  "Liste 2" and the query will select its contents. The result is a record set where each record has 2 components : the item's reference and the item's name.

 

The final page is generated using the following template :

<!--header-->

<html><body><font face="verdana">

<!--title-->

<hr width="75%" align="center"/>

<font size="3"><p align="center"><b>$1$</b></p></font>

<!--line:pre-->

<ul><font size="2">

<!--line:do-->

<li><a href="I-$1$.html">$2$</a></li>

<!--line:post-->

</font></ul>

<!--backlinks-->

<br /><hr width="75%">

<a href="$cid$HP.html"><font face="Verdana" size="1">Home</font></a>

<!--footer-->

</font></body></html>

 

 

 

2.3      Resources Storage

The #RES# directory contains all DB queries and HTML templates plus the Database. <CID> subdirectories are available for channel specific resources.

Search path: <BaseDir>/<CID> ΰ <BaseDir>/#FSUB#<CID> ΰ <BaseDir>/#FSUB#


 

2.4      Notation for Diagramming Applicative Transitions Systems

Using the following diagram cell allows to precisely design Applicative Transitions :

QueryVariables lists the $name$ variables used in the .qry DB query file.

DisplayVariables lists those used in the .tpl HTML template

Sometimes there's no .qry (ConfirmAction) or no .tpl (DoAction) part in the Applicative transition.

Here is the diagram of the standard model :

 



3         Standard Mechanisms Design

3.1      Applicative transitions

An applicative transition is an HTML navigation (either hyperlink or form submission) that corresponds to an Aladdino specific protocol : call:// or exec:// and is handled and interpreted by the AOBE application to perform something specific.

3.1.1       The "call://" and "exec://" protocols

<a href="call://function?arg1=value 1&arg2=value 2">text</a>

<form method="post" action="call://function?arg1=value 1&arg2=value 2">

 … inputs …

<input type="submit" name="call://fnc1?arg1=value+1&arg2=value+2" value="Execute fnc1"/>

</form>

<a href=" exec://app.exe /n name /u login /p password">text</a>

<form method="post" action=" exec://app.exe /n name /u login /p password ">

 … inputs …

<input type="submit" name="exec://\program files\appdir\app.exe" value="Launch App"/>

</form>

This is the same as for "call://" except that :


3.1.2       The "retpage" and "go" arguments

These special arguments only concern the "call://" protocol.

3.1.3       Examples

<a href="call://DisplayList?qry=ActLst.qry&tpl=ActLst.tpl">Bookmarks</a>

With this URL, the navigation will call the DisplayList function which will perform the DB query specified in ActLst.qry and then display the results using the ActLst.tpl. The "sys-ActLst.html" file will be generated. Note that no real argument is passed to the function.

<form method="post" action="call://DisplayList?qry=SearchByName.qry&tpl=SearchItems.tpl">

Search : <input name="PATTERN/><br>

<center><input type="submit" value="OK"/></center>

</form>

This also calls the DisplayList function which will perform the SearchByName DB query and build the resulting Html page using the SearchItems.tpl Html template. Both the DB query and the template are parameterized by the PATTERN argument.

<form method="post" action="call://DisplayList?qry=SearchItems.qry&tpl=SearchItems.tpl&SearchField=NAM">

Find <input name="PATTERN/><br>

<left><input type="submit" name="BTN_ACT" value=" Name"/></left>

<right><input type="submit" name="call://DisplayList?qry=SearchItems.qry&tpl=SearchItems.tpl&SearchField=OTHER" value="Princip."/></right>

</form>

This form corresponds to the Channel Home Page's Find Form that allows to seach items by name or by principle (stored in the OTHER DB field). In this example, for both buttons, the same function will be called with the same script (SearchItems.qry) and HTML template. The only difference is the value of the SearchField argument. The DB query script is supposed to use this argument (and also the PATTERN argument of course).

Note that clicking "Princip." button will result in the following formdata argument :

call%3A%2F%2FDisplayList1%3Fqry%3DSearchItems%2Eqry%26tpl%3DSearchItems%2Etpl%26SearchField%3DOTHER=Princip%2E,

the name of the button has to be URL-decoded back to :

call://DisplayList?qry=SearchItems.qry&tpl=SearchItems.tpl&SearchField=OTHER

Here is the link from the ActLst.html page :

<a href="call://DisplayList?qry=ActLst.qry&tpl=ActLst.tpl&SetRetpage=dynamic">Change List</a>

 

And here is the generated List Selector page's form :

 <form method="post" action="call://DoAction?qry=SetActLst.qry&go=GetRetpage ">

<input type="radio" name="LSTNAM" value="Liste 1"/> Liste 1<br>

…

<input type="radio" name="LSTNAM" value="Liste N"/> Liste 1<br>

<left><input type="submit" name="BTN_ACT" value="Select List"/></left>

</form>

The first link tells that one wants to return to the current page "when appropriate", and the second one (form's action) tells that after performing "DoAction" this will be the appropriate time to return to the retpage.

As asserted in the first link (SetRetpage=dynamic), the page will be rebuilt upon return.

<form method="post" action="exec://app.exe /n name /u login /p password">

<input type="checkbox" name="CHECK1">choix 1</input><br>

Prιcision<input name="TED1" size="14"/></br>

<center><input type="submit" value="OK"/></center>

</form>

Upon validation of the OK button in the form above (we assume it is located in the CID1 directory), Aladdino will create the <basedir>\CID1\exec_args.afd file containing the following two lines :

CHECK1=choix 1

TED1=input text

and then invoke : app.exe /n name /u login /p password. This is URL-decoded from : exec://app.exe%20%2Fn%20name%20%2Fu%20login%20%2Fp%20password

 

3.1.4       Standard Applicative Transitions

These functions are described more in details in the CappMgr class (implementation section).

3.1.5       Writing Querys on Win32 and WinCE

Because of ADOCE (WinCE) and ADO (Win32) need different syntaxes, Querys must not be exactly the same on WinCE and win32.

Each string must be delimited by “” on WinCE and by ‘’ on Win32.

Numbers does’t have to be delimited.

 


 HTML pages generation

The ideal way to generate HTML in a flexible manner is to use XSL style sheets. But this is not possible in our context as we do not have any XML documents yet. This is why we introduce Aladdino HTML Templates.

3.1.6       HTML Templates

The HTML templates are a privileged way to generate HTML pages for AOBE and other Aladdino WinCE software.

Here are 2 examples of the same list with two different looks.

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

and here are their corresponding HTML templates

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 


3.1.7       HTML Templates Interpretation

An HTML template is a viewable HTML document that is internally split into tagged sections that have the following profile : <!--function:step -->

The step may be omitted, its default value is "do"

Precisions :

o                   $prvpage$ : URL of the previous page

o                   $curpage$ : URL of the current page

o                   $cid$ : channel ID (for programming)

o                   $itemref$ : current item's reference (if applicable)

o                   $prvitemref$ : previous item's reference (if applicable)

3.1.8       Templates Sections, CHtmlPageMaker and Applicative Transitions

When the system processes a "call://" applicative transition, it is lead to calling one of the DisplayList, ConfirmAction or DoAction internal functions.

The  DisplayList and ConfirmAction functions call the CHtmlPageMaker section output methods in a particular order as illustrated by the following schemes. Note that an individual template may not implement all of the sections. The only mandatory sections are the header and footer.

 

 

 

 

 

 

 

 

 

 

 

 

 



3.2      Database

3.2.1       Schema

The schema is made of 4 tables. All items & lists are stored together regardless of the channel they belong to. It is designed to be stable, flexible and to save space.

 

3.2.2       The DB Query Processor

The DB Query processor is relatively simple. Basically the sequence of operations is :

<varname> corresponds to any variables from the CNamesArgs collection. A specific <varname> value is managed : NBRESULT. It corresponds to the number of records in the resulted recordset.

<operatortag> corresponds to any following arithmetical operator :

         EQ corresponding to ==

NE corresponding to !=

GE corresponding to >=

GT corresponding to >

LE corresponding to <=

LT corresponding to <

<testvalue> corresponds to either an integer or a string value. In case of string, comparison is case unsensitive.

NOTE: The NBRESULT variable is unavailable. It always returns a null value.

 

 

The great thing about the DB Query Processor is that it allows to adapt to any DB schema. With the same application exe, you just change the queries text and its done…

The only constraint is that all variables mentioned in the query's script are actually defined by the source HTML page, either as arguments or as form inputs.

 

The following script file lists the contents of a List given its name. It contains only one section with no introduction line and is therefore implicitly a SQL query :

SELECT Items.REF, Items.NAM

FROM (ListItems RIGHT JOIN Lists ON ListItems.LSTnum=Lists.num) LEFT JOIN Items ON ListItems.ITMnum=Items.num

WHERE Lists.NAM="$LSTNAM$"

 

This one creates a new list :

.#.SQL

SELECT Channels.num FROM Lists INNER JOIN Channels ON Lists.CIDnum=Channels.num WHERE Channels.CID="$CID$" AND Lists.NAM="$NEWLST$"

.#.EVAL

(EXITIF NBRESULT NE 0)

.#.SQL

SELECT Channels.num FROM Channels WHERE Channels.CID="$CID$"

.#.EVAL

(SET CIDNUM $1$)

.#.SQL

SELECT num FROM Lists ORDER BY num DESC

.#.EVAL

(SET LSTNUM $1$)

(INCREMENT LSTNUM)

.#.SQL

INSERT INTO Lists (num, NAM, CIDnum, CREDAT)

VALUES ($LSTNUM$, "$NEWLST$", $CIDNUM$, '10/10/2001')

 

This one updates the default list for a channel :

.#.SQL

SELECT Lists.num FROM Lists INNER JOIN Channels ON Lists.CIDNum=Channels.num WHERE NAM="$SELLST$" AND CID="$CID$" ORDER BY Lists.num

.#.EVAL

(SET LSTNUM $1$)

.#.SQL

SELECT DefLstNum FROM Channels WHERE CID="$CID$"

.#.EVAL

(DBUPDATE $1$ LSTNUM)

 

3.3      Global simplification

 

 

 

 

The "SWITCH to internal function" is a classical switch to one of the legal internal functions :

 

DisplayList uses a record-set for FindItems, DisplayActLst, DisplayListSelector

 

ConfirmAction only uses the first record of the record set (if any) for ConfirmDeleteList, AddItemInList.

 

DoAction does not use CHtmlPageMaker object. It is supposed to navigate to a specified URL (retpage or else).