WAP/WML interfaces
part of the ArsDigita Community System by
- Administration page: /admin/wap/
- Top-level user page: /wap/
- Data model file: /doc/sql/wap.sql
- Tcl procs: /tcl/wap-defs
The Big Picture
We want to make site content available to wireless devices like cell phones. The prototypical application is a WAP-accessible phone directory which lets you look up a phone number by keying in the first few letters of the person's name or email address, and then serves up the number providing a link to call that number.
The Medium-Sized Picture
A WAP device connects to a gateway which issues HTTP requests on behalf of the device. No modifications of the web server itself are needed---content is served over HTTP---but new headers and markup are needed. Pages are built according to the Wireless Markup Language DTD, proposed and maintained by the WAP Forum.
Besides learning new syntax, the major considerations when building WAP pages are:
-
Page flow: WAP devices typically have small screens without much room for information. Rather than requiring that a slow request be made for each page, WML provides a mechanism for transmitting several discrete page views, or cards, in a single document, or deck. There are also provisions for passing state information (i.e. variables) between cards in deck (and possibly between different decks).
-
Verbosity: Small displays mean you don't have room for lengthy explanations.
-
Applications: You can help the phone do nifty stuff like dial phone numbers thanks to the WTAI Specification.
-
Code reuse: There's no absolute way to get around the pain of managing parallel sets of pages. If nothing else, you'll want to serve up less content to smaller screens and perhaps more to larger screens. But there are ways to minimize the pain by separating content from presentation (insert favorite X* acronym here).
The Gory Details
- User login is handled by cookies in the usual way.
- To save the user a bit of typing at login time we provide autocompletion of the email address using a default domain if the user's input lacks an @ (see wap_default_email_domain)
- We build a top level index for wap services in /wap/i.wap, which should ultimately integrate with the module registry to dynamically build a page of available services.
- All wap services will live under the /wap directory (subject to change).
- The /admin directory contains tools for managing a list of known WAP user agents, which can help you determine what type of device is knocking at your door.
- Documented procedures: see wap-defs section of ACS API documentation
Note for programmers who have worked with the ACS-3.3 version:As of ACS-3.4, wap_begin_output and wap_begin_output_no_cache return a string to the caller, rather than writing directly to the connection. This change was made so that we can return the WML document with a single call to ns_return, in keeping with 3.4 standards.
The Steps
To add wap services to your module:
- Add a link to your service in the top level page at /wap/i.wap (this needs to be integrated with the module registry).
- Learn to code WML. You might want to read the WML specification.
- For logic, make use of the API functions in wap-defs. Useful procs: util_guess_doctype, wap_maybe_redirect_for_registration, wap_returnredirect, wml_return
- For debugging, you may want to run a WAP-enabled browser on your PC. These can be downloaded from
Alternatively, the telnet method works quite well too.
Parameters
[ns/server/yourservername/acs/wap]
; do we serve the generated /wap/index page or something
; else from the file system? This should be the FULL PATH relative
; to page root.
SpecialIndexPage=/wap/i.wap
; how long between lookups of the known user agent list?
WapUserAgentDbRefresh=300
; where to import user-agents strings from
WapImportSiteURL=http://wap.colorline.no/wap-faq/useragents.php3
; what tcl procedure to use to parse the data returned
; from the page listed above
WapImportParseProc=wap_import_parse
; how long between http GET's?
WapImportRefreshTimeout=120
; how many characters in the User-Agent string
; should we compare against?
WapUAStringCompareLength=4
; are we doing HTML browser-based debugging?
WapHTMLDebugMode=0
; to save typing when logging in
WapDefaultEmailDomain=arsdigita.com
More