Online documentation - Websydian v6.0 |
Users Guide | Patterns Reference | WebsydianExpress | Search |
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 | |
Step Two: | Specify Article Entity | |
Step Three: | Specify Article Grid List | |
Step Four: | Generate and Build | |
Step Five: | Run the WAP Application | |
Step Six: | Add a Create Card | |
Step Seven: | Generate - Build - Test | |
Part 2: Going Further |
||
Step Eight: | Specify Selection Card | |
Step Nine: | Specify Delete Event Handler | |
Step Ten: | Specify an Update Deck | |
Step Eleven: | Generate - Build - Test | |
Remarks |
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.
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 AllFusion Plex group model and local model). Do also attach the WAPUTIL pattern library to your group model.
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 AllFusion 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.
Before the WML Deck Templates can be generated, the Internet Address (the URL) of the WAP application Dispatcher program must be specified. The AllFusion Plex INI-file is located in the AllFusion Plex bin folder, e.g. C:/Program files/plex400/BIN/Ob400rc.ini for AllFusion Plex version 4.00.
In the default INI-file of AllFusion 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">
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.
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:
Article | is a ENT | RelationalTable EditDialog |
known by FLD | Article ID | |
has FLD | Art Name Art Price Category |
|
Article ID | is a FLD | Identifier |
length NBR | 6 | |
Art Name | is a FLD | ShortDescription |
Art Price | is a FLD | Price |
Category | is a FLD | Status |
value VAL | Discount Normal Luxury |
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
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.
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:
ListArticlesDeck | is a FNC | GridDeck |
replaces VW ...by VW |
UIBasic.Grid Article.Fetch |
|
impl name NME | LstArt | |
file name NME | LstArt | |
ListArticlesDeck.GridCard | name NME | List Articles |
local view VW ...for VAR ...omit FLD |
Article.Fetch OmitGridFields Art Name |
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.
A WAP Dispatcher function must be specified for your WAP application:
Add the following triples to specify a WAP Dispatcher function:
MyDispatcher | is a FNC | WapEventDispatcher |
file name NME | Dispat | |
impl name NME | Dispat | |
calls FNC | ListArticlesDeck.GridCard.Position ListArticlesDeck.GridCard.Next |
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)
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.
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.
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.
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).
In this section, a NewArticle Card is added to the Article Deck.
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:
ListArticlesDeck | includes FNC | NewArticle |
ListArticlesDeck.NewArticle | is a FNC | InsertCard |
replaces VW ...by VW |
UIBasic.Insert Article.Update |
|
replaces VW ...by VW |
UIBasic.Detail Article.Update |
|
name NME | Add New Article | |
ListArticlesDeck.NewArticle.Back | calls FNC | ListArticlesDeck.GridCard |
MyDispatcher | calls FNC | ListArticlesDeck.NewArticle.Insert |
The calls-triple to ListArticleDeck.GridCard tells the Back Jump action which Card to jump back to.
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)
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:
ListArticlesDeck.GridCard | includes FNC | Add Article |
ListArticlesDeck.GridCard.Add Article | is a FNC | Jump |
calls FNC | ListArticlesDeck.NewArticle |
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
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.
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:
ListArticlesDeck | includes FNC | Select Action |
ListArticlesDeck.Select Action | is a FNC | CardGenerator |
local FLD ...for VAR |
Article ID WsyUserOutput |
|
local FLD ...for VAR |
Art Name WsyUserOutput |
|
local FLD ...for VAR |
Art Price WsyUserOutput |
|
option NME ...value SYS |
NewContext No |
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:
ListArticlesDeck.GridCard | includes FNC | Select |
ListArticlesDeck.GridCard.Select | is a FNC | Jump |
option NME ...value SYS |
WSYD Grid event Yes |
|
calls FNC | ListArticlesDeck.Select Action | |
local view VW ...for VAR |
Article.Update WebInput |
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.
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:
ListArticlesDeck.Select Action | includes FNC | Delete |
ListArticlesDeck.Select Action.Delete | is a FNC | WapEventHandler |
local FLD ...for VAR |
Article ID WebInput |
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.
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:
UpdateArticleDeck | is a FNC | UpdateDeck |
replaces VW ...by VW |
UIBasic.Update Article.Update |
|
replaces VW ...by VW |
UIBasic.Detail Article.Fetch |
|
file name NME | UpdArt | |
impl name NME | UpdArt | |
UpdateArticleDeck.UpdateCard | name NME | Update Article |
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:
ListArticlesDeck.Select Action | Includes FNC | Update |
ListArticlesDeck.Select Action.Update | is a FNC | WapEventHandler |
local FLD ...for VAR |
Article ID WebInput |
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.
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:
MyDispatcher | calls FNC | ListArticlesDeck.Select Action.Delete ListArticlesDeck.Select Action.Update UpdateArticleDeck.UpdateCard.Update |
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
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.