WAP Tutorial - Building a Simple Article Application

This Tutorial takes you through the exact steps required to build a small working WAP application using Websydian.

The WAP Tutorial is split into two parts.  In the first part (See WAP Work!), you will implement a Grid Deck displaying records from a database table.  After this, you will implement functionality to create new records in the same database table.

In the second part (Going Further), actions are implemented at the Grid Table.  This is done by specifying a separate Select Action Card from which the different actions can be selected.

Part 1: See WAP Work!

Step One: Set-up the Development Environment

In the Tutorial, it is assumed that you use the Microsoft Personal Web Server and that the application is running on an ODBC database on a stand-alone work station.

Create Plex Model and Database

A new model needs to be defined, the Websydian libraries must be attached to it and various configuration settings must be specified.  See Step One of the Websydian Tutorial for a short description of how to accomplish that (you may specify other names for the CA Plex group model and local model).  Do also attach the WAPUTIL pattern library to your group model.

Specify Web Server Configuration

Specify a web server script alias to point directly to the Release-folder containing the generated run-time objects (and toggle on the Run EXE-files option).

Specify a WAPTUTOR web server alias pointing to the folder containing the generated CA Plex run-time objects

By pointing directly to the generation library, it is not necessary to move the generated Websydian functions to a Web server folder.

Modify CA Plex INI File

Before the WML Deck Templates can be generated, the Internet Address (the URL) of the WAP application Dispatcher program must be specified.  The CA Plex INI-file is located in the CA Plex bin folder, e.g. C:/Program files/plex400/BIN/Ob400rc.ini for CA Plex version 4.00.

In the default INI-file of CA Plex (e.g. ob4000rc.ini), add the following key in a new HTML section:

[HTML]
DISPATCHER_URL=/WAPTUTOR/DISPAT.EXE

The URL address will be used to create the action attribute of WML go instructions in the generated Deck Templates, e.g.:

<go href="/WAPTUTOR/DISPAT.EXE" method="post">

Install WAP Simulator

The Tutorial application should be run on a WAP simulator.  See also the notes in the Run WAP Applications on a Simulator section in the Installation and Operation part of the documentation.

Step Two: Specify Article Entity

A simple one-table database is used as an example database.  The table is to contain information about Articles where each Article record has an Article ID, Name, Price, and a Category:

Enter the following triples:

Specify literal values for the Category fields values

Generate and build tables, views, and server functions to test that the database connection is correctly set up.

Generate and build the table, views and server functions of the Article entity

Run the EditSuite.Grid function from the Generate & Build window and add some Article records

Step Three: Specify Article Grid List

The WML (Wireless Markup Language) language operates with a Deck/Card structure where the Deck corresponds to an HTML page being the portion of WML code sent to the WAP browser.  Each WML Deck contains one or more WML Cards, and the Card is what the user sees in the browser display.  In this way, it is possible to jump between the Cards within a WML Deck without accessing the HTTP server.

Define Deck Generator and Card Generator

A ListArticlesDeck function is specified based on the GridDeck pattern.  By inheritance from the GridDeck pattern, the ListArticlesDeck function will be defined as a Deck Generator function containing a GridCard Card Generator function.  In this way, the Deck/Card structure of WML is reflected in the design of Websydian.

Add the following triples to define a ListArticlesDeck function implementing a Grid list of articles:

By default, all fields will be displayed in the Grid.  The local view triples above omit all fields but the Art Name from the Grid so that only this field will be displayed.

Take a look at the ListArticlesDeck function in the object browser; ListArticlesDeck is a Deck Generator function containing a GridCard Card Generator function which does the actual listing of the Article data.  Only values of the Art Name field are displayed in the Grid table.

The Position and Next WAP Event Handler functions scoped under the GridCard Card Generator implement functionality to browse the Article table.

The inherited functions scoped under the _DeckTemplateGenerator and _CardTemplateGenerator functions should be ignored.

Define Dispatcher Function

A WAP Dispatcher function must be specified for your WAP application:

Add the following triples to specify a WAP Dispatcher function:

Each WAP Event Handler needs to be declared by a calls-triple from the Dispatcher function in the same way as in HTML applications built with Websydian.

The first Deck Generator to be called needs to be specified in the CallFirstPageGenerator function scoped under the MyDispatcher function:

Open the action diagram of the MyDispatcher.CallFirstPageGenerator function

In the Call to first page edit point, add a call to the ListArticlesDeck function (map the Article ID input with value *Blank)

Step Four: Generate and Build

Generate and Build Function Objects

Generate and build the objects contained in the subject area specific for your choice of variant. Please refer to Generate and Build Considerations for more details.

Generate and build the library packages (remember to toggle on the Show Library Objects option in the Generate and Build window)

Then, generate the specified WAP functions:

Generate and build the two functions and their scoped functions:

MyDispatcher
ListArticlesDeck

Ignore the two warnings from the generation of the MyDispatcher function.

Run Deck Template Generator

WML Decks are generated from Deck Templates which themselves are WML documents containing replacement markers that are substituted during the Deck generation process.  Deck Templates are generated automatically by running the _DeckTemplateGenerator function scoped under each Deck Generator.

Before running the Template Generators, a WML folder needs to be defined under the /Gen/Win32 folder (at the same level as the generated run-time objects).

Create a WML folder under the /Gen/Win32 folder

Run the ListArticlesDeck._DeckTemplateGenerator function from the Generate and Build window

A LstArt.wml file should now have been created in the /Gen/Win32/Wml folder.  You may open the generated Deck Template with Notepad or with another text editor.

Create EXE for Dispatcher Function and Modifiy INI File

An EXE-file must be generated for the WAP Dispatcher function and the corresponding INI-file must be modified in order for the application to be able to locate the WML Templates and connect to the database.

Create an EXE-file for the MyDispatcher function

Open the INI-file of the generated WAP Dispatcher function, and add the following section (HTML used as section name):

[HTML]
PATH=..\WML\

Set the DSN, Userid and Password keys in [ODBC settings] (if running on an ODBC database), e.g.:

[ODBC Settings]
DSN=WapTutor
Userid=dba
Password=sql

These settings only need to be specified once after having built the Dispatcher EXE-file.  The settings will not be overwritten by re-building the WAP Dispatcher function.

Step Five: Run the WAP Application

Now, it is time to run your first WAP application.

Start up your Web server and your WAP simulator

In the Location box of the Simulator, enter the URL:

http://localhost/WapTutor/Dispat.exe

You can now browse the Article data that you entered through your Windows panel (an Article ID positioner value can be entered in the input field below the Articles grid list).

Step Six: Add a Create Card

In this section, a NewArticle Card is added to the Article Deck.

Define NewArticle Card Generator

Users have to be able to enter new Article records from their WAP device.  To implement this, a NewArticle Card Generator is defined scoped under the ListArticlesDeck Deck Generator and based on the InsertCard pattern:

Add the following triples to specify a NewArticle Card Generator function:

The calls-triple to ListArticleDeck.GridCard tells the Back Jump action which Card to jump back to.

Call back to Article Deck after Insert Action

After a record has been inserted in the Article table, the Article Grid should be displayed again with its new contents:

Open the action diagram of the MyArticle.NewArticle.Insert WAP Event Handler function

In the edit point 0 call to build of document, add a call to the ListArticlesDeck function (map with *Blank)

Add Jump to New Article Card

Next, a menu point action is specified for the GridCard function to jump to the NewArticle Card.  This is done by specifying a Jump function having a calls-triple to the NewArticle Card:

Add the following triples to specify a Jump to the NewArticle Card:

Step Seven: Generate - Build - Test

Generate and build the ListArticlesDeck function and its scoped functions

Generate and build the MyDispatcher function

Ignore the warnings about the missing call statements.

The Article Deck has been changed and therefore the Deck Template Generator must be run again:

Run the ListArticlesDeck._DeckTemplateGenerator function from the Generate & Build window

Run the WAP application again and try to add a few Article records

Part 2: Going Further

In this second part of the Tutorial, Update and Delete functionality is added to your small WAP application.  Hereby, you will learn about some important concepts and techniques in development of Enterprise WAP applications using Websydian.

Step Eight: Specify Selection Card

Delete and Update is implemented by first selecting a record from the Article Grid table and then select the action to be accomplished to that record.  In WML, this can be done by jumping from the Grid Card displaying the Article list to a separate Selection Card displaying the selected record.  From the Selection Card, it can then be chosen whether to continue with a Delete or an Update operation.

Add the following triples to specify a Select Action Card:

WsyUserOutput is a special Websydian variable telling that the fields specified in it must be inserted in the Deck Template as WML variables.  In this way, the fields in the WML Card will be substituted by the field values of the chosen Grid record.

Next, a Select Jump must be specified from the Article Grid table:

Add the following triples:

It is necessary to declare the Article.Fetch view as local WebInput fields in order to transfer the values of the selected Grid record fields to the Select Action Card, i.e. to assign the field values to the corresponding WML variables.

Step Nine: Specify Delete Event Handler

You can now specify a Delete WAP Event Handler scoped under the Select Action Card Generator function.

Add the following triples to specify a Delete Event Handler function:

Action diagram logic must be specified for the Delete WAP Event Handler function.  This includes calling the DeleteRow function followed by a call to the next Deck to be generated.

Open the action diagram of the Delete Event Handler function:

In the edit point 0 Process of input, add a call to the Article.Update.DeleteRow function (map with WebInput)

In the 0 call to build of document edit point, add a call to the ListArticlesDeck function (map with value *Blank)

Calling a WAP Event Handler must always result in a call to a Deck Generator producing the next Deck to be sent to the WAP client.  In this case, the Article Grid is displayed again positioned from the first record in the table.

Step Ten: Specify an Update Deck

The next step is to implement update functionality for the Article records.  This is done by specifying a separate UpdateArticleDeck function based on the high-level UpdateDeck pattern.  UpdateArticleDeck contains a single UpdateCard Card through which all non-key fields of an Article record can be altered.  The UpdateArticleDeck function must be called from the Select Action Card.

Add the following triples to specify a new UpdateArticleDeck function:

A WAP Event Handler function must be specified to direct control from the Select Action Card to the UpdateArticleDeck Deck.

Add the following triples to specify an Update WAP Event Handler function calling the new Update Deck:

A call statement must be specified from the Update Event Handler to the UpdateArticleDeck function:

Open the action diagram of the ListArticlesDeck.Select Action.Update Event Handler function

Add a call to the UpdateArticleDeck function in the 0 call to build of document edit point (map with WebInput)

After an Article record has been updated, control must be transferred back to the ListArticlesDeck:

Open the action diagram of the UpdateArticleDeck.UpdateCard.Update Event Handler function

Add a call to the ListArticlesDeck function in the Call deck generator edit point (map with value *Blank)

The Back Jump function scoped under the UpdateArticleDeck.UpdateCard function is disabled, and no alternative Back or Cancel WAP Event Handler is implemented in this Tutorial.

Declare New WAP Event Handlers

The Delete and Update WAP Event Handler functions must be declared by the WAP Dispatcher function by adding calls-triples to each of the three Event Handlers.

Add the following triples to declare the new WAP Event Handlers:

Step Eleven: Generate - Build - Test 2

Generate and build the following functions:

ListArticlesDeck (except NewArticle and scoped functions)
UpdateArticleDeck
MyDispatcher

Generate the Deck Templates and run the application.

Run the ListArticlesDeck._DeckTemplateGenerator and UpdateArticleDeck._DeckTemplateGenerator functions from the Generate & Build window

Run the WAP application again and try to modify and delete some Article records

Remarks

In this Tutorial, you have built a small application corresponding more or less to the WapEditDialog Utility pattern already being part of the Websydian product.  A part of your design was a Grid Card followed by a SelectAction Card, which is also implemented by the SelectDeck Utility pattern.

You have now seen some of the principles of development of integrated WAP applications with Websydian.  Now, go ahead - experiment on your own, take a look at the implemented patterns, read and look-up in the documentation - and it will not be long before you are in full control of your own Enterprise WAP development.