HAWHAW

Make your website mobile ...
... and keep on laughing though

Frequently-Asked Questions / HowTo / Tutorial

This document is a combination of FAQ, HowTo and tutorial all in one. It starts with some WAP fundamentals, then explains the intention of the HAWHAW toolkit and finally shows the various solutions, how a universal mobile website or application can be realized by usage of the HAWHAW components:

FAQ Revised: Sunday 25 May 2003 18:06:37


Table of Contents

1. WAP basics
2. HAWHAW basics
3. HAWHAW.INC - The HAWHAW PHP class library
4. HAWHAW XML - The markup language
5. HAWXY - The HAWHAW proxy
6. VoiceXML

1. WAP basics

1.1. What is WAP?

WAP stands for Wireless Application Protocol and is in fact a set of sub-protocols, e.g. WML. The intention of WAP is the exchange of a rather small amount of data between a wireless mobile device and a webserver (=WAP server). The small-sized display, the restricted input facilities and the low transmission rate of WAP devices are the main restrictions WAP-sites have to deal with.



1.2. Can I browse the web via WAP?

No, the web is made for big-screen browsers. Websites speak HTML, but WAP devices understand (compiled)WML. Some WAP gateways have the capability to transform the content of a HTML website into WML. But the success of such a conversion is highly depending on the originating website. Today's average website, optimized for 800x600 pixels, with a labyrinth of frames and kilobytes of javascript code, definitely can not be transformed for WAP by generic mapping rules. Nevertheless, it is possible to make a website, that can be accessed by both big-screen and WAP browsers. But these websites have to support this explicitely. HAWHAW is a toolkit to set-up such websites.



1.3. What is WML?

WML stands for Wireless Markup Language. WML has been defined by the WAP forum and is designed to meet the special requirements of wireless devices. Currently the version 1.1 is of relevance for most applications.



1.4. What is a WAP gateway?

The WAP gateway is the link between the WAP device and the webserver. The WAP device sends a request to the WAP gateway. The gateway creates a HTTP request and contacts the according webserver. The webserver answers in WML. The WAP gateway 'compiles' the WML response into a binary format before it is transmitted over-the-air to the WAP device. When the WAP device requests to browse a non-WAP-URL, the WAP gateway will receive a standard HTML response from the webserver. It is now an optional functionality of the WAP gateway, to convert this non-WAP response into a WAP-conform format before it is propagated to the WAP device. If you are the one who is responsible for the webserver's content, you should not assume that all your mobile visitors will access your server via such an well-configured WAP gateway. Therefore either your webserver has to create the appropriate WML output, or a HAWHAW proxy server has to do this conversion.



1.5. Do I need a special webserver for a static WAP site?

No, in principle each webserver can provide WAP content. You can upload WML files the same way as you upload your HTML files. One problem is, that the webserver has to create the correct WAP mime-types in the HTTP response. This can be easily configured by the server's administrator, and today many ISP's are supporting it by default.



1.6. Where can I find more detailled answers to WAP-related questions?

http://www.thewirelessfaq.com/ provides a good FAQ for all WAP-related issues.




2. HAWHAW basics

2.1. What stands the name 'HAWHAW' for?

HTML And WML Hybrid Adapted Webserver.



2.2. What is HAWHAW?

HAWHAW is a toolkit that helps webmasters to make their website mobile, i.e. accessible by a wide range of mobile devices and standard browsers. There are three components the HAWHAW toolkit consists of:

Each of these components will be explained in detail here in this document.

Each HAWHAW users can choose the component which fits best for his personal requirement:

PHP programmers can use the PHP class lib, to set-up taylormade mobile standalone applications on their PHP enabled webserver.

Webmasters can use the HTML-like HAWHAW XML markup language, to provide wireless accessible content without any programming skills or special webserver support.

Service providers can set-up their own HAWHAW proxy, which can be used by the before-mentioned webmasters for the required markup conversion.

The whole HAWHAW code, both for the HAWHAW PHP class library and the HAWHAW proxy server is open-source and available for free under GPL. Users of the HAWHAW XML markup language don't need any code at all, because they just have to edit HAWHAW XML files, which are accessed via other people's proxies.



2.3. Why should I use HAWHAW instead of direct coding WML?

The current situation out there is that many WAP applications are highly incompatible and not able to interwork with different mobile devices. This is mainly caused by strong differing browser implementations and network configurations. Starting to program WML means to painfully learn about all those pitfalls one by one and day by day. Using HAWHAW, the programmer can rely on the accumulated experience of many running mobile applications. The compatibility of a direct WML-coded application is highly dependent from the programmer's personal knowledge. The mark-up output of a HAWHAW-based application contains the knowledge of many running HAWHAW applications out there. This does not mean, that the HAWHAW-created output is totally perfect under all situations. But it will automatically become better and better because each feedback from a single application can result in an improvement of the underlying hawhaw.inc library.

Existing HAWHAW sites will therefore benefit from future HAWHAW evolution steps. Without any additional development effort you can upgrade your running applications. Users of the HAWHAW PHP class library simply download a higher version of the HAWHAW class lib. HAWHAW XML users are upgraded automatically in the very moment, when the involved HAWHAW proxy upgrades to an higher version. This way your site or application is best prepared for future requirements, caused by new available WAP phones, handheld devices, GPRS, UMTS, XHTML etc.



2.4. How about HDML?

HDML is a WML predecessor and still widely used in North America and Japan. Whenever the HTTP request header indicates that the client browser supports HDML 3.x only, appropriate HDML output will be generated by HAWHAW.



2.5. How about PDA's?

Each HAWHAW-based application supports the AvantGoTM browser and automatically creates "handheld-friendly" HTML output whenever the string "AvantGo" is detected in the HTTP request header.

To learn more about AvantGoTM please visit the AvantGo homepage.

Other browsers currently supported are the "Pendragon" and the "ReqWireless" browser. If you use another PDA browser not mentioned here and you want it to be supported by HAWHAW, feel free to send a feature request.



2.6. How about i-ModeTM?

i-ModeTM currently is THE killer application in Japan and is on the jump to conquer other countries too. Whenever HAWHAW detects an i-Mode browser, cHTML output will be generated.

To learn more about i-ModeTM please visit the NTT DoCoMo homepage.

2.7. How about MML?

MML (Multimedia Markup Language) is a markup language used by japanese mobile devices from J-Phone Communications Co Ltd. If HAWHAW detects an MML device, cHTML-like MML output will be generated.



2.8. How about VoiceXML?

From the W3C recommendation:

VoiceXML, the Voice Extensible Markup Language. VoiceXML is designed for creating audio dialogs that feature synthesized speech, digitized audio, recognition of spoken and DTMF key input, recording of spoken input, telephony, and mixed initiative conversations. Its major goal is to bring the advantages of web-based development and content delivery to interactive voice response applications. VoiceXML is a XML language defined by the W3C, which allows create voice applications. Users of voice applications need access to some "voice browser".

Each mobile application that has been created with the HAWHAW PHP class library is voice-enabled, as HAWHAW can detect voice browsers and then automatically generates VoiceXML output. Furthermore HAWHAW offers many voicespecific add-on's, making it easy to use HAWHAW as development tool for intelligent voice applications, that can be controlled by any phone in the world

More information about HAWHAW's VoiceXML support can be found in the special VoiceXML chapter here in this document.



2.9. Do I need knowledge about XML, WML, HDML, HTML, cHTML, VoiceXML etc.?

Depends on which way you're going:

If you go the easiest way by using HAWHAW XML, you only have to know how to write and upload simple HTML files. You don't need any knowledge about XML, because all those few things you need to know are explained in the HAWHAW XML reference.

If you want to use the HAWHAW PHP class library, you need some knowledge about PHP and server-sided programming. HTML experience is required too, but obviously there is no PHP programmer out there, who have not heard about HTML before. You don't need any knowledge about WML, HDML or whatever markup language your HAWHAW application is able to generate. All those markup detailles are hidden by HAWHAW behind a simple API. You only have to learn how to use the function calls of this API.

If you want to set-up your own HAWHAW proxy, you really should know what you are doing! Even though almost every homepage owner with PHP support could set-up a HAWHAW proxy on his/her webserver, this should not be done just for fun. Running a HAWHAW proxy, your litte webserver becomes some sort of central internet server and you will act more like a service provider than as a simple webmaster.



2.10. Do I have to take care about mime-types?

HAWHAW normally sends the correct mime-types in the HTTP response headers. This is sufficient as long as you don't use wireless bitmap images. If you want to use images, things get a little bit more complicated. First you have to create your image in WBMP format. You can do this with a special WBMP editor or with one of the available conversion tools. The important thing is, that after uploading the .wbmp file, the webserver has to be instructed to created the mime-type "image/vnd.wap.wbmp" for these kind of file. If not already done by your webspace provider, in case of an Apache webserver this can be done by adding the following instruction to the webservers config file (or .htaccess):

AddType image/vnd.wap.wbmp .wbmp

Please note, that some configurations of WAP devices and WAP gateway will refuse to display anything but an error message, if you try to use WBMP files with the wrong mime-type! It is not only the image that is not displayed!

The mime-type handling applies for both HAWHAW XML and HAWHAW PHP class lib users.




3. HAWHAW.INC - The HAWHAW PHP class library

3.1. What is PHP?

PHP (recursive acronym for PHP: Hypertext Preprocessor) is a server-side, cross-platform, open-source scripting language. The syntax is similar to C, Java or Perl. PHP was originally written 1994 by Rasmus Lerdorf and runs today on innumerable webservers all over the world.

The PHP website http://www.php.net/ contains a lot of valuable information (installation, manual, FAQ, mailing lists, etc.).

3.2. Is there a programming reference available?

Yes, in the reference section of the HAWHAW homepage you can find an online reference and a downloadable zip-file for offline browsing. Please read the reference and this FAQ, before you ask questions.



3.3. Where can I download the HAWHAW class library?

The HAWHAW class lib is available in the download section of the HAWHAW homepage. Create a directory of your choice in your webserver's document tree and store the hawhaw.inc file in this directory.



3.4. How does a simple HAWHAW application look like?

Create a new file in the same directory where hawhaw.inc is located. Use an editor of your choice to write the following PHP script:

<?php
require("hawhaw.inc");
$myPage = new HAW_deck("FAQ Demo");
$myText = new HAW_text("Hello WAP!");
$myPage->add_text($myText);
$myPage->create_page();
?>

Store this file as test.php. (Alternatively you can save your file as test.wml if you have administered your webserver to activate PHP for .wml extensions.)

What is the meaning of these few instructions? Before you can use any HAWHAW function calls, you have to include the hawhaw.inc file. Afterwards you have to define one so-called HAW_deck object. The whole HAWHAW API follows a strict object-oriented approach. There are some objects like HAW_deck or HAW_text. And there are object functions, to perform actions on those objects. So what we do in line 3 of our tiny example is: We define $myPage as an object of the class HAW_deck. When you take a look at the HAWHAW reference, you will see that the constructor of HAW_deck optionally awaits some title for your 'deck'. Btw, a deck is an expression that is often used in the WAP terminology. In HAWHAW's context you don't have to distinguish between deck and page. It is the same.

When you examine the HAW_deck constructor in the reference in detail, you will notice, that there is another optional input parameter alignment. If you would have called

$myPage = new HAW_deck("FAQ Demo", HAW_ALIGN_CENTER);

the whole deck would have been displayed centered. Every time when there is a predefined value mentioned in the argument list of a function, this value is provided by default as long as you don't supply this parameter explicitely.

So, what we have now is an empty HAW_deck object. Let's bring some content into it: In line 4 a HAW_text object is defined. The reference entry for HAW_text tells you that you have to provide the text (you guessed that, right?) and (optionally) a text format. But to define this object does not automatically make it a part of your HAW_deck object! Therefore you have to call the HAW_deck object's object function add_text(), as done in line 5. Perhaps you ask now why this association is not done automatically, but you will understand it, when you want to re-use HAW_text or HAW_image objects in many positions of your HAW_deck object.

Okay, now we're almost through. We have defined our HAW_deck object and we have filled it with one HAW_text object. Now we only have to make the whole thing visible. Therefore we have to call the HAW_deck object function create_page(). So what we have learned is: For EACH page created by HAWHAW, we have to create ONE HAW_deck object, fill it we some content (like text in this example or images, links etc. as we will see in the succeeding paragraphs), and finally throw it out by calling create_page().

Now point your webbrowser to test.php: What you see is the most simple HAWHAW application ever possible.

3.5. What is the maximum size of a HAW_deck?

It is in the programmer's responsibility to restrict the amount of data contained in one HAW_deck object. Many WAP clients can not handle more than 1400 byte of compiled data. You should control the size of your HAWHAW-created pages with one of the SDK's, e.g. the UP.SDK can display this helpful information. For usability reasons it is no bad idea to restrict the content of each output page consequently. Your visitors with small WAP displays will be happy about it.



3.6. How can I handle links?

A link is defined with a HAW_link object:

$myLink = new HAW_link("News", "news.wml");
$myPage->add_link($myLink);

It's similar to the text definition some lines above. You have to define a HAW_link object. The first argument is the text string which appears as link. The second argument is the URL of the link destination. After you have defined your HAW_link object you have to associate it to your HAW_deck object. Take a look at the HAW_link definition in the reference for more information about links.

BTW, if you were able to follow until here, you have already learned enough to write your first real HAWHAW PHP class lib application. Approximately 80 per cent of all HAWHAW users out there create their apps with the three classes HAW_deck, HAW_text and HAW_link only.



3.7. What is a linkset?

Several HAW_link objects can be grouped together into one HAW_linkset. Dependent from the recognized WAP browser, HAWHAW will generate different WML code for UP-browsers respectively non-UP-browsers. This approach improves the "usability" of your application because the menu navigation from the user's viewpoint will be simple as possible, no matter what kind of WAP device he uses.



3.8. How can I use images?

The HAW_image class does the job. Unfortunately the image file format for WAP devices is not compatible to the wellknown GIF, JPG or PNG formats, known in the HTML world. If you want to offer an application, where images are displayed on both web and WAP, you have to provide two different formats. The first argument of the HAW_image constructor is the name of the WBMP file. There are some tools available for free, to edit WBMP files or to convert them from other graphic formats. The second argument tells HAWHAW the name of the image, which should be used by a HTML client. The third argument is the alternative image description, which is used when a device can not display the image at all. And additionally there is an optional fourth argument available. Here you can specify the name of a monochrome BMP image. It is said, that some WAP devices can display such file formats only.

Apropos format conversion: In PHP you can theoretically make the conversion between GIF, JPG, PNG and WBMP on-the-fly using PHP's image functions. But this approach is highly dependent from your personal PHP installation (GD-library support installed, GD version, PHP version, GIF-support, WBMP-support, etc.). Considering server performance and PHP portability, I recommend to use separate static files.

3.9. How are forms defined?

Interactivity is essential for all mobile applications. When links are not sufficient any more for user interaction, forms are required to collect the user's input and to submit it to your application. HAWHAW therefore provides the HAW_form class. A HAW_form element can contain objects similar to the HAW_deck element, like HAW_text, HAW_image and HAW_link. But additionally the following objects can be associated to a HAW_form object:

For more information about all these classes and how to associated them to a HAW_form, respectively HAW_deck object, please refer to the demo section of the HAWHAW homepage. Here you will find some examples, how forms can be used to submit user input from a mobile device to your PHP script.



3.10. How can I make the HTML output look fancy?

If you believe the classic HAWHAW HTML style does not fulfil your aesthetic demands, no problem! The HAW_deck class offers a lot of object functions to modify the style of a HTML created page. You can modify the

Example 8 of the demo section can give you an idea what's possible and how the according script does look like.

3.11. Is session handling supported?

PHP session treatment for WML applications is not the same as for normal websites! Many wireless devices do not support cookies as the prefered medium to transmit session ID's. Therefore the session ID has to be attached to URL's. But normal PHP installations are normally not prepared to consider WML specific requirements. One major problem is, that the argument separator often is predefined as '&'. This will crash a WAP browser's WML decoder, because WML is a XML-based language and therefore has to escape ampersand characters as &amp;. An additional problem are the predefined url-rewriter tags. These are normally based on HTML. In WML there a tags defined, where url-rewriting has to be done too, e.g. <go href=...> or <option onpick=...>. Therefore the url-rewriter tags have to be re-defined for WAP applications before session handling is properly supported.

To make session handling easy, the HAW_deck class offers a method called enable_session(). When you want to write a session-based application, you should start your decks like this:

$myPage = new HAW_deck("Session App");
$myPage->enable_session();
...
start_session();
...

The enable_session() function call performs some important ini_set(...) commands to modify your session settings for the duration of your script's execution. Please note that PHP session handling is not available in PHP version 3.x and was quite buggy in the early 4.x releases. Therefore it is highly recommended to use PHP 4.1.1 or higher for session-based HAWHAW applications.



3.12. Why does my device simulator not work?

Two conditions must be fulfilled for the use_simulator() function to work properly:

1.) Your host must have an active internet connection. This is required as the simulator image files are retrieved from the HAWHAW server. If your PHP box is offline or the HAWHAW host is down, no device is shown on the screen. Nevertheless, your content will shown without restrictions. It's only that your output is presented on a empty page instead of the simulator display.

2.) The device simulator works only on browsers which are capable to display scrollable table elements. Today unfortunately only the Microsoft Internet Explorer is supporting this feature properly. This problem is solved as HAWHAW checks whether the requesting browser is able to interprete the required HTML extensions. If not, the use_simulator() function is ignored and classic HAWHAW output is created instead.



3.13. Can I use HAWHAW in a WINNT environment?

Yes, as PHP can run under Windows, there is no problem to use HAWHAW in an PHP-enabled Windows environment.

In some Windows installations HAWHAW's output is destroyed by some PHP warnings of notice level. In this case you should turn off notices by editing your php.ini file:
error_reporting= E_ALL & ~E_NOTICE; display all errors and warnings



3.14. What means the PHP warning "Cannot add header information - headers already sent ..."?
HAWHAW automatically creates the correct mime-type in the HTTP response header according to the detected browser. The HTTP header has to be created before any other content is sent. When your application initiates some output, PHP will create a standard header with a mime-type text/html by default. When then HAWHAW tries to create the appropriate header command, it's too late: Header and output are already sent out, there's no way to modify the header afterwards. HAWHAW applications should never use commmands like echo or printf because all required output is done by HAWHAW when you call the HAW_deck's object function create_page(). Make sure that there are not empty lines in your script outside of your PHP tags. One single blank character or carriage return before <?php can be enough to create the wrong HTTP header.


4. HAWHAW XML - The markup language

4.1. What is HAWHAW XML?

HAWHAW XML is an XML-based Markup Language which makes it easy to create applications and websites for mobile devices. It is no standard. It is rather an approach in early experimental stage!



4.2. Who can use HAWHAW XML?

HAWHAW XML can be used by every webmaster, who wants to provide wireless content. Writing a HAWHAW XML file is quite similar compared to writing a HTML file. There is no special XML knowledge required. Following this tutorial and with assistance of the HAWHAW XML reference you are enabled to provide wireless content on your homepage within a few hours.



4.3. Which devices can interprete HAWHAW XML?

As HAWHAW XML is converted by a HAWHAW proxy into the appropriate markup language, many devices can access HAWHAW XML files without problems.



4.4. How is the HAWHAW proxy to be used?

There is no device configuration necessary, as you might know it from your standard browser. HAWHAW XML files are retrieved via special URL's.

Example: You have stored a HAWHAW XML file in your webspace at http://www.foo.com/mywap.xml

Entering this URL directly with a wireless device or a standard browser will not be a big success as the (mobile) browser will receive an unknown markup language.

So instead you have to enter the URL that looks like this: http://hawhaw.net/x/www.foo.com/mywap.xml

The first part of the URL specifies the proxy to be used (here: hawhaw.net/x/). The second part of the URL is the location of your XML file.



4.5. What does the HAWHAW proxy?

Simplified your browser requests some document and awaits it in a format he is able to understand, e.g. a WAP phone awaits Wireless Markup Language (WML), standard (big-screen) browsers await HTML, other devices await cHTML, HDML, etc.. When the HAWHAW proxy receives the browsers request, he retrieves the HAWHAW XML file from your webserver. After he checked the file for syntactically correctness, the HAWHAW proxy determines from what kind of device the request was coming and then creates the optimized response to answer the request.

In other words, the HAWHAW proxy converts the HAWHAW XML response into the appropriate response the browser is able to understand.



4.6. How does a HAWHAW XML file look like?

Edit a file like this ...

<?xml version="1.0"?>
<hawhaw>
  <deck>

    <text>Hello world!</text>
  </deck>
</hawhaw>

... and upload it to your webspace. Then enter this URL with your standard web browser:

http://hawhaw.net/x/www.foo.com/test.xml

(You have to adapt the URL, if you are not foo.com and you have not uploaded to http://www.foo.com/test.xml :)



4.7. Is there a HAWHAW XML reference available?

The HAWHAW XML reference is online available at http://www.hawhaw.de/ref/xml/en/. For a downloadable version please refer to the reference section of the HAWHAW homepage.

In the reference you find a description of all HAWHAW XML tags and many examples how to use them.



4.8. Is there a list of HAWHAW proxies available?

No, but if you want your HAWHAW proxy listed here, just send me a short mail.



4.9. Is it possible to combine HAWHAW XML with PHP, ASP, or other server-sided scripting languages?

Yes, the platform independence is one major advantage of the HAWHAW XML approach. Even though there is no server-sided processing required to use HAWHAW XML, you can integrate every scripting language of your choice in your HAWHAW XML file. One principle of server-sided processing is, that the receiving browser only sees the result of the processing and not the script itself.

Considering this, it becomes clear that a HAWHAW proxy has not to deal with your script code at all. A HAWHAW proxy awaits HAWHAW XML markup. It is in your responsibility whether you store this HAWHAW XML output in a static file or whether you create this output dynamically. The demo section of the HAWHAW homepage shows some examples how PHP scripts can be integrated in a HAWHAW XML file.

The extension of your HAWHAW XML files is of no importance. The extension .xml is recommended for static files. If you integrate PHP code in your file, it has advantages to choose an .php extension, for ASP just name it .asp.

4.10. Is VoiceXML supported?

There is only some basic support. If the underlying hawhaw.inc library detects some voice browser, valid VoiceXML is put out. But there are currently no special HAWHAW XML attributes available, comparable to those set_voice_... methods which are offered by the PHP library.




5. HAWXY - The HAWHAW proxy

5.1. What means HAWXY?

HAWHAW XML proXY

(... or HAWHAW XML gatewaY, whatever you prefer)



5.2. What is a HAWHAW proxy?

A HAWHAW proxy retrieves HAWHAW XML files from remote webservers and performs an "on-the-fly" conversion into a format, which is optimized for the requesting browser. The HAWHAW proxy is located between the requesting browser and the HAWHAW XML webserver. URL's entered at the user's browser consist of two components: The leading part, which addresses the proxy. And the trailing part, which tells the proxy where the remote HAWHAW XML file is located.

5.3. Do I have to set-up a HAWHAW proxy to make my HAWHAW XML files accessible?

No, you don't. You can use any existing HAWHAW proxy of your choice instead.



5.4. Why should I set-up my own HAWHAW proxy?

Maybe because you like HAWHAW and therefore want to be a part of the HAWHAW network?

Another motivation could be that you want to increase traffic at your site: Acting as HAWHAW proxy, you can place your own banner on top of the HAWHAW HTML device simulator. Every webmaster who publishes HAWHAW XML files via your proxy, will therefore bring additional visitors to your site.

Last but not least a third possibility could be to set-up your own HAWHAW proxy to avoid dependency from third party proxies.



5.5. Why is the HAWHAW proxy implemented as PHP script?

Sure, a C-implementation would have some advantages under performance considerations. But on the other hand it would mean a re-implementation of the logic which is already implemented in the HAWHAW PHP class library. The big advantage of the PHP approach is that the original HAWHAW PHP class lib is the core of the HAWXY script. HAWXY in fact does know nothing about markup languages. In principle it is just a XML parser, who serves the HAWHAW PHP class lib's API. If the HAWHAW PHP class lib will be enhanced and improved, HAWXY will automatically benefit from all changes.



5.6. Which are the requirements to run a proxy?

You need a PHP-enabled webserver (PHP3 or PHP4) configured with the --with-xml option. Additionally it is highly recommended, that your webserver allows URL rewriting. Otherwise your served clients have to deal with long and user-unfriendly URL's.



5.7. How can I install the proxy on my server?

Go to the download section of the HAWHAW homepage and download the hawxy.php script. Edit the configuration part of the script according your preferences. HAWXY configuration allows to:

Finally you store the script in your webspace, e.g. under http://foo.com/xml/hawxy.php, and you are ready.

Make a test with some remote HAWHAW XML file, e.g. stored at http://www.bar.com/hawhaw/test.xml:

http://foo.com/xml/hawxy.php?code=www.bar.com/hawhaw/test.xml



5.8. How can I activate the shortened URL handling?

You can use Apache's "URL Rewrite Handling" to make the URL above look like this:

http://foo.com/x/www.bar.com/hawhaw/test.xml

Modify your httpd.conf or store a .htaccess file in your document root, like this:

RewriteEngine on
# Abbreviated URL for UNREGISTERED remote XML sites
# http://foo.com/xml/hawxy.php?code=www.bar.com/hawhaw/test.xml
# -> http://foo.com/x/www.bar.com/hawhaw/test.xml
# DO NOT CHANGE NEXT LINE:
RewriteCond %{REQUEST_URI} /x/(.*)/(.*)$
# CHANGE NEXT LINE ONLY IF HAWXY IS NOT LOCATED AS "/xml/hawxy.php":
RewriteRule x/(.*)$ /xml/hawxy.php?code=$1 [L]

URL rewriting is not a trivial thing and can not be explained here in this document. If your are interested to learn more about this very powerful feature, please refer to the Apache documentation.



5.9. How can I activate shortcut URL's?

You are still not satisfied with the shortened URL's described in the previous paragraph? No problem, you can offer "shortcut URL's" for registered site owners. Let's assume the site owner of bar.com has set-up some HAWHAW XML files, where the entry point is located at http://www.bar.com/hawhaw/index.xml. With the appropriate URL Rewrite command, bar.com's wireless site can be entered like this:

http://foo.com/wap/bar

To achieve this URL shortcut handling you have to enhance httpd.conf or .htaccess as follows:

# Shortcut URL for REGISTERED remote XML sites
# http://foo.com/xml/hawxy.php?code=www.bar.com/xml/index.xml
# -> http://foo.com/wap/bar
# ADAPT THE FOLLOWING LINE AND ADD ADDITIONAL ONES ACCORDING YOUR NEEDS
# (DO NOT REMOVE THE '$' SIGN AS IT IS PART OF A REGULAR EXPRESSION!):
RewriteRule wap/bar$ /xml/hawxy.php?code=http://www.bar.com/hawhaw/index.xml [L]




6. VoiceXML

6.1. What can I do with VoiceXML?

From the W3C recommendation:

VoiceXML's main goal is to bring the full power of web development and content delivery to voice response applications, and to free the authors of such applications from low-level programming and resource management. It enables integration of voice services with data services using the familiar client-server paradigm. A voice service is viewed as a sequence of interaction dialogs between a user and an implementation platform. The dialogs are provided by document servers, which may be external to the implementation platform. Document servers maintain overall service logic, perform database and legacy system operations, and produce dialogs. A VoiceXML document specifies each interaction dialog to be conducted by a VoiceXML interpreter. User input affects dialog interpretation and is collected into requests submitted to a document server. The document server replies with another VoiceXML document to continue the user's session with other dialogs.

HAWHAW is a tool to setup VoiceXML document servers easily.



6.2. What is a voice browser?

A voice browser is not a browser like those visual browsers you might know. Voice browsers are located somewhere in the internet and are typically called by phone. If you want to offer a voice-enabled application to the public, you need to cooperate with a VoiceXML provider. His task is to provide a dedicated phone number for your application. When a user dials this number, the provider's voice browser retrieves your VoiceXML document from your webserver, converts text to speech and plays the conversion result to the calling user.

The user listens to your application's output and controls your application by voice or keypad input. The voice browser performs voice/DTMF recognition. If a valid input was received the voice browser sends your input to your webserver, where it is evaluated by your application.

From your application's point of view it makes no difference, if a form was filled and submitted by a HTML/WAP browser or a voice browser. In all cases the markup which is created by HAWHAW will result in the same query parameters received by your form evaluation script.



6.3. Why should I use HAWHAW to create VoiceXML applications?

With HAWHAW you can create VoiceXML applications without to know anything about this markup language. But the killing point is: A HAWHAW application is not restricted to voice browsers only. It is accessible by all those other browser types supported by HAWHAW.



6.4. How can I test HAWHAW VoiceXML?

While you're developing your VoiceXML application you don't need an expensive business relation with a VoiceXML provider. There are some sites which offer development environments for free. HAWHAW has been tested with Tellme Studio. When you have registered to their service you can test your voice applications from your phone. National calls from inside US towards the development server are free of charge. If you have a good internet connection you can connect to their site worldwide via VoIP without any connection fee besides those for your internet connection.



6.5. How will a HAWHAW application become voice-enabled?

There is nothing special to do. All HAWHAW applications create automatically proper VoiceXML output, whenever a voice browser request is received. Nevertheless, HAWHAW offers some special functions to optimize VoiceXML output. All these functions follow the naming convention set_voice_...() and can be found in the reference section of the HAWHAW homepage. The most important of these special functions are described in the following chapters.



6.6. What are event handlers?

In VoiceXML there are some event handlers defined to handle error conditions. If some input is expected, but the user keeps silent, the voice platform will say per default something like "I'm sorry, I didn't hear you". If the users input does not match an expected grammar he will probably hear something like "Sorry, I didn't get that".

HAWHAW offers three functions (in various HAWHAW classes) in order to override these default texts with your individual text:


$text is some ASCII string, which will be text-to-speech-converted by the voice platform. Alternatively you can record an audio wav-file, which will be played, if the event handler throws the according event. And last but not least you can define a $url which will be visited, when the given event occurs.

All these event handler functions can be used more than once per objects:
...
$myInput->set_voice_help("Please say you ID")
$myInput->set_voice_help("Please say you ID. As you know it is 8 digits long.")
$myInput->set_voice_help("Please say you 8 digit ID.")
...

The first time the users says "help", he will hear the first help message. Saying "help" once more, will cause the second help text to be put out. And all following "help" requests will result in playing the third help message.

Event handlers are assigned "best qualified". You can assign an event handler for your HAW_deck object and for all of your input elements. If you have assigned an event handler for the HAW_deck object, it will apply for all input elements as long as you do not assign a different event handler for this given input element.



6.7. How can voice output be modified?

Per default, all output that your HAWHAW application creates for visual browsers will be text-to-speech converted automatically by the voice platform's speech synthesizer. But chances are good, that sometimes you want to modify this output.

E.g. your application puts out something like a string from the HAWHAW demo: sqrt(16)=4

As speech synthesizers normally have no degree in mathematics, the speech output will not be what you are expecting. For a better understanding your HAWHAW application can do something like this:

$myFormula = new HAW_text("sqrt(16)=4");
$myFormula->set_voice_text("squareroot of 16 is equal 4");


Alternatively you can record a wav-file and instruct the voice platform to play it:

$myFormula->set_voice_text("squareroot of 16 is equal 4", "formula.wav");

In the latter case the text string is of no significance as long as no technical problems prevent the voice platform from playing the audio file.

If want to build a voice application without any synthesized speech output, this is no problem at all. You can record all of your application's speech output, store it in wav-files and assign these files to the according HAWHAW objects which are created by your application. Of course the development effort will arise with this approach, but voice visitors will perceive a more natural voice dialog.



6.8. What about images?

As you can imagine, images are not really helpful for voice users. Per default there is no voice output for images at all. But the HAW_image object offers methods to assign text/audio output to images, if an application requires this.

6.9. What about links?

On a visual browser links can be distinguished from plain text by special text formatting, mouse pointer behaviour or other means. For voice users things are more difficult. Per default, links are text-to-speech converted as any other text. This may be acceptable for voice users who are very familiar with an application and exactly know what they have to say to control a given application.

For normal voice users your application has to make links "recognizable". To achieve this, the HAW_deck object offers a method to play a userdefined jingle before any link text is put out:

$myDeck->set_voice_jingle("http://www.foobar.com/sounds/jingle.wav");



6.10. How can the voice platform's <property> elements be modified?

<property> tags in VoiceXML are a very powerful means to control the voice platform's behaviour in many aspects. The HAW_deck objects offers a method to manipulate the given platform's default settings, e.g.:

myVoiceDeck->set_voice_property("bargein", "false");

Attention:
Usage of this method is recommended for experienced VoiceXML developers only. For more information please refer to the VoiceXML recommendation.



6.11. Is it possible to define speech grammars?

For most HAWHAW input elements (links, linksets, select elements, radio buttons and checkboxes) it is not necessary to define special speech grammars, as the voice browser either can use simple built-in grammars or can compare voice input with a given text. The situation is different when you want to use a HAW_form element, e.g. for some application's user login. Let's assume you want to grant access for users Alice, Bob and Carol only. On a visual browser, people can enter their name and their individual password. User input is transmitted from the browser towards the webserver and the application compares the received user parameter with the strings "Alice", "Bob" and "Carol".

But how should this work in case of speech recognition? Alice is asked for her username and says "Alice". But how should a voice recognition system know, whether Alice said "Alice" or "Ellis"? It can't, as long as it has no additional information about valid voice input. Therefore it possible to define customized grammars and assign them to a HAW_input object by means of the set_voice_grammar() method.

Note:
Usage of user defined speech grammars is recommended for experienced VoiceXML developers only. For more information please refer to the VoiceXML recommendation.



6.12. Is it possible to record speech input?

Yes it is, and this is probably one of the most powerful voice features offered by HAWHAW! You can use it to implement voice mailboxes, speech controlled guestbooks and much more intelligent applications.

While visual browsers will render a text input field, HAWHAW will create an appropriate VoiceXML <record> tag for voice browsers. You can activate voice recording with a special method of the HAW_textarea class:
$myTextarea->set_voice_recording("receive_voiceinput.php");

After voice input has been completed, the voice browser sends a wav-file encrypted as multipart/form-data to your receive_voiceinput script. PHP handling is identical to file upload, i.e. you can store the wav-file in a database, replay it to the user, or do whatever you want.
A simple voice recording application sounds like this: (MP3: 784KB)
This is the underlying PHP script.
And here the application can be invoked with a normal browser: http://www.hawhaw.de/e/recording.php.

You are kindly invited to visit this url with a voice browser, even just to say "Hello!"



6.13. Is there an interactive HAWHAW VoiceXML demo available?

In the demo section of the HAWHAW homepage there are some demo recordings you can listen to. They show how it works to control the HAWHAW demo scripts with a voice browser. Currently there is no interactive voice demo available. Offers from VoiceXML providers are welcome!



6.14. Where can I learn more about VoiceXML?

A good starting point is the W3C VoiceXML Version 2.0 recommendation.

A collection of the most important VoiceXML links can be found at Ken Rehor's World of VoiceXML.


Copyright (c) 2003 Norbert Huffschmid

Comments, corrections and any kind of feedback is highly appreciated.

This FAQ was generated by makefaq.