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:
- 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:
- hawhaw.inc - The PHP class library
- HAWHAW XML - The markup language
- HAWXY - The HAWHAW proxy
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.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:
- HAW_input
- HAW_select
- HAW_radio
- HAW_checkbox
- HAW_hidden
- HAW_textarea
- HAW_submit
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
- page's background color
- page's wallpaper
- display's width
- display's height
- display's background color
- display's border size
- character font
- font size
- font color
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 &. 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.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.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:
- determine the maximum XML file size
- translate error messages to a language other than english
- activate logging
- place your personal banner(s)
- edit a blacklist
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.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:
- set_voice_help($text, $audio_src, $url)
- set_voice_nomatch($text, $audio_src, $url)
- set_voice_noinput($text, $audio_src, $url)
$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.
Comments, corrections and any kind of feedback is highly appreciated.