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 with HAWHAW.

FAQ Revised: Sunday 09 December 2012 16:21:30


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. HAWHAW.NET - The ASP.NET solution
7. HawTags - The JSP tag library
8. VoiceXML
9. Nihao
10. Hastenix

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.



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.




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. These are the main components the HAWHAW toolkit consists of:

  • hawhaw.inc - The PHP class library
  • HAWHAW XML - The markup language
  • HAWXY - The HAWHAW proxy
  • HAWHAW.NET - The HAWHAW ASP.NET solution
  • HawTags - The HAWHAW JSP Tag Library

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.

ASP.NET developers can use HAWHAW.NET in order to create mobile applications in their favorite .NET language and deploy them on IIS.

Java developers can use the HawTags JSP tag library in order to create and deploy mobile applications that run on every JSP-compliant servlet container.



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.

With 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.

HAWHAW was developed according to the Wireless Application Protocol Wireless Markup Language Specification Version 1.1 and according to the HDML Language Reference V3.0. It additionally supports the Openwave GUI extensions for WML 1.3. If HAWHAW's browser detection recognizes that the requesting device supports the proprietary Openwave WML extensions, special WML output will be submitted. There is no extra effort required to support GUI elements like select boxes, radio buttons or submit buttons. WAP devices which understand WML 1.1 only, will receive the standardized WML tags instead. So there's no need for the application programmer to deal with different code for various browsers.



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 "Pendragon", "ReqWireless" and Windows CE based browsers. 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 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 XHTML?

XHTML Mobile Profile (WAP 2.0) is the standard for modern mobile devices. If HAWHAW detects a XHTML-capable phone, dedicated XHTML output is created. From HAWHAW version 5.4 on there comes color to phone! HAWHAW application programmers are able to design colored applications which are viewed best on a XHTML device or PDA with color display, while these applications run well on each old monochrome WAP 1.1 device too.



2.9. 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.10. Is HAWHAW output barrierfree?

From Version V5.6 onwards HAWHAW supports the Lynx browser, which is used by many people for many different reasons. Especially for visually impaired or otherwise handicapped people, a pure text browser like Lynx is of great importance.

HAWHAW's HTML output for bigscreen browsers and Lynx is CSS-based. This means that assistive technology devices are able to extract the content properly, no matter how the content is displayed by means of a simulator skin for normal web browsers. Output for Lynx will be optimized in order to validate Bobby-AAA-approved. Some Bobby requirements can not be fulfilled automatically, as e.g. the declaration of the document language. But most requirements are fulfilled out of the box, without further coding effort.



2.11. Do I need knowledge about XML, WML, HDML, HTML, cHTML, XHTML, 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.12. 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.



2.13. How do all these HAWHAW components interwork?

HAWHAW beginners often are confused how the various HAWHAW components work together and which component is based what. The following image tries to visualize the HAWHAW ecosystem and its surrounding:

The HAWHAW ecosystem




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. Some old WAP devices can not handle more than 1400 byte of compiled data. For usability reasons it is no bad idea to restrict the content of each 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 (X)HTML output look fancy?

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

  • window's background color
  • windows's wallpaper
  • display's width
  • display's height
  • display's background color
  • display's wallpaper
  • display's border size
  • character font
  • font size
  • font color

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

Anyway, in times of XHTML and CSS the old-fashioned way to manipulate the page style via the HAWHAW API slowly becomes deprecated. Since hawhaw.inc V5.14 you are able to assign the URL of a CSS-file to a HAW_deck object. Furthermore it is possible to assign a CSS class definition to each HAW_text and HAW_link object, so that it references a given format entry in your CSS-file. Following this approach you will obey the golden rule that tells to differentiate between content and style. Additionally you can use the full power of CSS to create stylish pages for CSS-capable mobile devices.



3.11. Can I change the simulator skin?

Calling the HAW_deck's function use_simulator(), will activate the HAWHAW default simulator. As the simulator works by means of CSS, you can use user-defined simulator skins very easy! All you have to do is to provide the URL of your personal CSS file in the function call:

...
$myDeck = new HAW_deck("Skin Test");
$myDeck->use_simulator("http://www.foo.com/myskin.css");
...

To get an idea how the CSS file should like, you can take a look at the CSS file of HAWHAW's default simulator skin.

All you need to modify is:

  • the background-url of your skin image file
  • the size of your skin image
  • the relative position, where the text output should appear within the skin image

Some different stategies how to deal with skins and device simulators are described in the HAWHAW article: Device simulator skinning with PHP.

3.12. Is session handling supported?

Session handling for mobile devices is a little bit tricky. Cookies sometimes are not supported by devices/gateways and transient session ID's are to be considered as potential security issue. It is up to the programmer to decide which way to go by setting the according control flags in php.ini.

The HAW_deck class offers a function called enable_session() which is helpful in case that trans_sid session handling applies: As XML does not allow unescaped '&' characters, the arg-separator has to be modified. Otherwise a WAP browser's WML decoder will crash, because WML is a XML-based language and therefore has to escape ampersand characters as &amp;. An additional problem are the PHP-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 in order 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.13. Can I combine HAWHAW with WURFL?

Yes, of course. WURFL is the perfect solution if you want to optimize your application for many mobile devices with different features and capabilities. In order to access the huge WURFL database with PHP, Tera-WURFL should be the tool of your choice.

HAWHAW optionally can be configured to use Tera-WURFL for the determination of the appropriate markup language. Please note that Tera-WURFL is NOT required, as HAWHAW has its own logic to determine the preferred markup language of a mobile device. But if you already have Tera-WURFL installed and running on your webserver, it is very easy to integrate it into HAWHAW. All you have to do is to declare the location of your Tera-WURFL installation in the configuration part of hawhaw.inc. In this case HAWHAW's generic logic for markup determination is replaced by a WURFL-based markup determination. Both solutions have pro's and con's and it is up to the user which way to go.



3.14. How can I integrate Google AdSense for Mobile?

You can use HAWHAW's AdSense4Mobile plugin:

  • Download the plugin here.
  • Copy/Paste your individual PHP code snippets (WML, XHTML and cHTML) from the AdSense setup page into the plugin script (or provide appropriate include-files).
  • Create a mobile application as follows:
    <?php
      require("hawhaw.inc");
      require("HAW_plugin_AdSense4Mobile.php");
      $myPage = new HAW_deck();
      $myContent = new HAW_text("Here comes mobile content ...");
      $myPage->add_text($myContent);
      
      $adBlock = new HAW_plugin_AdSense4Mobile();
      $myPage->add_plugin($adBlock);
    
      $myPage->create_page();
    ?>


3.15. How can I enhance HAWHAW with application-specific plugins?

Please read the HAWHAW article about plugin development.



3.16. 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 commands 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.



4.2. Who can use HAWHAW XML?

HAWHAW XML can be used by every webspace owner, 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. HAWHAW XML users do neither need any PHP skills nor a PHP-enabled webserver.



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 through the proxy 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 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://x.hawhaw.net/www.foo.com/mywap.xml

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

(Note: If your webserver admin has made the webserver HAWHAW-XML-enabled, you don't have to deal with proxy handling at all.)



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://x.hawhaw.net/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. Can I browse a HAWHAW XML file without proxy?

As browsers don't know about HAWHAW XML, direct browsing without proxy usually does not work. But there is an exception:

XSLT-capable browsers can be instructed to use a special HAWHAW XSL transformation sheet and will display a page in the same style as it would be presented in case of a proxy request. All you have to do is to add the following XSLT command:

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="http://www.hawhaw.de/xml/hawhaw.xsl" ?>
<hawhaw>
  <deck>
    <text>Hello world!</text>
  </deck>
</hawhaw>

If you store this HAWHAW XML file on your computer and open it locally with the Internet Explorer, you will see the same result as if the file would be stored on a web server and would be retrieved via a HAWHAW proxy. Try out if you don't believe!

Interestingly this mechanism works for MSIE only. It seems that XSL transformations are generally blocked for security reasons, if XML document and XSLT document are not residing under the same domain. While Mozilla does not allow local XML files to use remote XSLT sheets, MSIE behaves tolerant. I'm not sure if this is a bug or a feature ...

Anyway, you can work around this issue by downloading the HAWHAW XSLT sheet and storing in the same directory where your HAWHAW XML file is located.



4.8. How can I validate HAWHAW XML code?

There is a HAWHAW XML DTD available at http://www.hawhaw.de/xml/hawhaw.dtd

Browsers and XML validators can validate HAWHAW XML files against this DTD by adding the following document type declaration to the file header:

<?xml version="1.0"?>
<!DOCTYPE hawhaw SYSTEM "http://www.hawhaw.de/xml/hawhaw.dtd">
...

A good generic XML validation tool is Validome.

Most XML editors (see below) can also validate HAWHAW XML files during editing.



4.9. Can I use an XML editor?

Of course! The online availability of HAWHAW XML DTD and XSLT stylesheet enables XML editors to support comfortable WYSIWYG editing of HAWHAW XML files ( Screenshot 155 KB).

Just search the web to find your favorite XML editor.



4.10. 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.11. Is there a list of HAWHAW proxies available?

Yes, if your HAWHAW XML file is accessible as http://www.foo.com/test.xml you can use one of the following HAWHAW proxy URL's:

http://x.hawhaw.net/www.foo.com/test.xml
http://www.workbench.de/hawxy.php?code=www.foo.com/test.xml
http://mobiledev.info/xml/hawxy.php?code=www.foo.com/test.xml


4.12. 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.13. My PHP script throws a parse error in line 1, what's wrong?

Your web server probably has activated the PHP 'short_open_tag' option. This is a common problem when PHP interacts with XML and is not HAWHAW-specific. The opening XML tag

<?xml version="1.0"?>

is interpreted by the PHP parser as invalid PHP command. The clean solution is to turn off the 'short_open_tag' option by means of php.ini or .htaccess. If this is not possible, the following workaround does the trick:

<?php echo "<?xml version=\"1.0\"?>\n"; ?>




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?

You can use the HAWHAW skinning mechanism and provide your personal simulator skin for all HAWHAW XML output which is presented via your proxy. Skinning of the simulator is very simple by means of a HAWXY config parameters: You just have to provide an image and can project HAWHAW output onto a given section within this image. More info can be found in the HAWHAW PHP section.

You can make your whole webserver HAWHAW-XML-enabled, and therefore avoid dealing with long and user-unfriendly proxy URL's.

You can place banners on top of the device simulator. Every webmaster who publishes HAWHAW XML files via your proxy, will bring additional visitors to your site.

Last but not least you can set-up your own HAWHAW proxy in order to avoid dependencies from third party proxies.



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

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 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 e.g. allows to:

  • restrict the maximum XML file size
  • determine the default simulator skin
  • determine a special skin for the output of error messages
  • activate logging
  • place your personal banner(s)
  • maintain 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 localize the proxy?

The HAWHAW proxy throws error messages in english language per default. All text output is defined in the PHP array $err. Localization for other languages than english can simply be done by translating the strings defined in $err.



5.9. 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.10. 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:

RewriteEngine on
# 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]


5.11. How can I enable my webserver to serve local HAWHAW XML files?

The previous two paragraphs were dealing with scenarios when an admin intends to offer a HAWXY service to the world. Now we are talking about the case, that a HAWXY service should be provided for local documents only:

An admin can enable the whole webserver or some directories to serve HAWHAW XML files automatically. This means that all clients with webspace on this server don't have to deal with a HAWHAW proxy and long URL's at all! Again URL-rewriting does the trick:

RewriteEngine on
# Automatic parsing of all *.haw HAWHAW XML files on webserver
# http://foo.com/xml/hawxy.php?code=www.foo.com/userdir/test.haw
# -> http://foo.com/userdir/test.haw
# DO NOT CHANGE NEXT LINE (do not rewrite requests from HAWXY (endless loop!))
RewriteCond %{HTTP_USER_AGENT}  !^HAWXY.*$
# MODIFY THE FOLLOWING LINE ACCORDING YOUR SERVER NAME
RewriteRule (.*)\.haw$ /xml/hawxy.php?code=http://www.yourserver.com/$1.haw [L,QSA]

The rewrite rule above makes sure that all *.haw files in the document tree will internally be addressed via the HAWHAW proxy. All the clients have to do is to upload their HAWHAW XML files with the proper .haw extension.

This mechanism also allows usage of embedded PHP commands within the HAWHAW XML file. E.g. if a client wants to offer a time service like that on http://www.hawhaw.de/xml/e/time.haw, he simply has to upload a time.haw file like this:

<?xml version="1.0" encoding="UTF-8"?>
<hawhaw>
  <deck title="Time" align="center">
    <text>German time:</text>
    <hr/>
    <text bold="yes">           <?php echo date("D M j"); ?> </text>
    <text big="yes" bold="yes"> <?php echo date("G:i:s"); ?> </text>
    <hr/>
  </deck>
</hawhaw>

Please note that PHP must be instructed to parse *.haw files by means of:

# MIME-type is installation-specific !!!
AddType application/x-httpd-php .haw

Additionally it is highly recommended to turn off PHP short_open_tags in php.ini or .htaccess! Otherwise clients have to deal with strange error messages caused by the opening XML tag. More info about this issue is available here.




6. HAWHAW.NET - The ASP.NET solution

6.1. What is HAWHAW.NET?

HAWHAW.NET is an alternative solution to Microsoft's Mobile Controls for ASP.NET. It allows to create ASP.NET applications with C#, Visual Basic or any other programming language supported by the .NET framework.

HAWHAW.NET makes HAWHAW available within a native ASP.NET environment. It allows to implement universal mobile applications for a huge variety of mobile and non-mobile devices, supports many different markup languages, creates mobileReady-compliant output out of the box and comes with a built-in device simulator.

.NET developers can combine the rich HAWHAW feature set for mobile applications with the various characteristics of the ASP.NET platform, as there are: Viewstate and event handling, code-behind model, databinding, single-form model, postback processing, etc.



6.2. Is HAWHAW.NET a re-implementation of the PHP code?

No, the hawhaw.inc PHP library has been compiled as-is to a .NET assembly and on top of that just a set of custom webserver controls have been defined in order to perform a mapping from given ASP.NET tags to the according HAWHAW classes.

This solution finally has been made possible by the extraordinary Phalanger project, that brings together both the PHP and the .NET worlds and allows the usage of HAWHAW in a native ASP.NET environment.

There has been written no mobile-specific code at all for HAWHAW.NET, as all this functionality has been derived from the underlying hawhaw.inc library. This makes this approach very robust and future-proof, as .NET developers automatically will benefit from ongoing improvements done by the PHP community.



6.3. How does an .aspx file look like?

A very simple mobile ASP.NET application will look like this:

<%@ Page Language="C#" Inherits="HawhawPage" %>
<%@ Register Assembly="Hawhaw" Namespace="Hawhaw" TagPrefix="Haw" %>
<Haw:Deck runat="server">
  <Haw:Label runat="server" Text="Hello world!" />
</Haw:Deck>

More examples can be found in the demo section of the HAWHAW homepage.



6.4. How can I get started?

Download the HAWHAW.NET zip-file from the download section of the HAWHAW homepage. Unzip and store it somewhere within your development webserver's document tree. Open Visual Web Developer or Visual Studio and select the 'Open Website' menu item from the File menu. Select the directory where you've unzipped to. Then open one of .aspx pages in the Examples directory and display it with your default browser either by pressing Ctrl-Shift-W or by clicking the according toolbar button.

That's all! The page should compile and be rendered as shown in the HAWHAW demo.

If you create new web sites, pls. make sure that the Bin directory hosts the 4 required assemblies and that your web.config is enhanced according to the entries of the web.config that is contained in the zip-file.



6.5. How about Toolbox support?

HAWHAW.NET smoothly integrates into the Visual Web Developer's toolbox. Create a new toolbox tab named HAWHAW (via right mouse-click on the toolbox). Then simply drag the Hawhaw.dll file from the file explorer onto this tab. The toolbox gets enhanced automatically and shows all available HAWHAW.NET server controls. The displayed icons then can be drag'n'dropped onto an opened .aspx page as usual.



6.6. Is there a HAWHAW.NET reference available?

Currently there is no reference available, but the toolbox support plus the property view information makes creation of HAWHAW.NET pages rather self-explanatory.

In order to get more information about a given property you can check the hawhaw.inc reference, as all HAWHAW.NET controls respectively properties internally are mapped to their corresponding PHP values.

The following table shows the relationship between HAWHAW.NET server controls and HAWHAW PHP classes. Some namings have been adapted acording to existing .NET standards in order to make life easier for .NET developers, so don't get confused when 'label' here means 'text' there and things like that.

HAWHAW.NET PHP class
AdBanner HAW_banner
Button HAW_submit
CheckBox HAW_checkbox
Deck HAW_deck
DropDownList HAW_select
Form HAW_form
HorizontalRule HAW_rule
Image HAW_image
Label HAW_text
Link HAW_link
LinkSet HAW_linkset
PhoneCall HAW_phone
RadioButtonList HAW_radio
Table HAW_table
TableRow HAW_row
TextArea HAW_textarea
TextBox HAW_input


6.7. Where is the source code?

HAWHAW.NET is not yet OpenSource, but probably will be in the future. Be patient ...




7. HawTags - The JSP tag library

7.1. What is HawTags?

HawTags is a JSP (Java Server Pages) custom tag library according to the Java Servlet Specification.

With HawTags Java developers can write HAWHAW-based web applications and deploy them on servlet containers like Resin or Tomcat.



7.2. Is HawTags a re-implementation of HAWHAW?

No, HawTags is based on the original HAWHAW PHP software. It is not a Java port of HAWHAW. HawTags is build upon Quercus, a pure Java-based PHP implementation from Caucho Technology.

The HawTags Java code is a wrapper on top of the hawxy.php software. The HawTags tag library creates a temporary HAWHAW XML document from a JSP page and transforms it to appropriate markup output by means of hawxy.php and hawhaw.inc.

HawTags users can benefit from the newest HAWHAW PHP code, by simply adding new releases of the HAWHAW PHP code to their .war files.



7.3. Do I have to be a PHP expert?

No, now that you have learned how HawTags interacts with HAWHAW's PHP code, you can forget it immediately again. HawTags users deal with nothing but Java code. The whole PHP stuff is handled internally by the jar-files.



7.4. How can I get started?

Download the latest HawTags distribution from HAWHAW's download section. Follow the instructions in the README.txt file.

(If you download the source distribution, you have to ant-build hawtags.jar first)



7.5. Is there a HawTags reference available?

The HawTags reference is online available here. For a downloadable version please refer to the download section of the HAWHAW homepage.



7.6. Where can I find some coding examples?

In the demo section of the HAWHAW homepage you will find the JSP source code that implements the HAWHAW demo.

Further examples can be found in the HAWHAW XML reference. As the syntax of HAWHAW XML and HawTags is nearly the same, the HAWHAW XML examples are easy to understand for HawTags users.




8. VoiceXML

8.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.



8.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.



8.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.



8.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 successfully tested with the development suites at Voxeo and Tellme Studio. When you have registered to such kind of development suite, you can test your voice application from your phone. Some suites offer VoIP access, so you can test your applications free of charge besides the costs for your (broadband) internet connection.

If you have an Asterisk Open Source PBX running on one of your Linux machines, you should take a look at the Hastenix chapter here in this document.



8.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.



8.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.



8.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.



8.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.



8.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");



8.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.



8.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 is 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.



8.12. Is there an interactive HAWHAW VoiceXML demo available?

Yes there is! Voxeo provides some dial-in numbers, where you can interactively browse through the HAWHAW demo from your phone!

+1 407 386 3678

Attention: This is an international call to the US and will be charged accordingly! Discrimination digits and country code can vary from country to country. If you are calling e.g. from Germany, you have to dial: 001 407 386 3678
(where 00 in Germany are the discriminating digits for international calls and 1 is the german country code for phone calls to USA)

Skype users can call the demo free-of-charge by clicking on the following number: +990009369991420757

Free World Dialup users can do the same by directing their IP phone towards this address:

FWD **869 1 999 142 0757

Before you call the demo from your phone, please make yourself familiar with its content by browsing through the demo section of the HAWHAW homepage.



8.13. 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, phone answering machines and much more intelligent applications.

Voice recording is done by means of the HAW_voicerecorder class. After voice input has been completed, the voice browser sends a wav-file encrypted as multipart/form-data towards the url you have specified in the constructor of the HAW_voicerecorder object. 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 (MP3: 784KB)



8.14. Are there SDK's or special editors available to create a voice service?

There are quite a lot of tools around which give assistance while creating VoiceXML code. HAWHAW is not comparable with these VoiceXML editors, as HAWHAW is to be understood as some kind of middleware included in an application you have to write.

If you are looking for a solution how to implement a simple voice service, you should take a look at TikiWiki. This open source CMS/groupware project offers a HAWHAW-powered voice-enabled wiki, that allows to create linked voice content that is very easy to maintain.

There is a VoiceTiki Demo and a dial-in number available, so you can compare the output on your visual browser with the interactive voice navigation on your phone.



8.15. 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.


9. Nihao

9.1. What is Nihao?

  1. Ni hao (你好) is the Mandarin Chinese word for 'Hello' and literally translates to 'you good'.

  2. Nihao stands for Norbert's HAWHAW objects for the iPhone and basically is a CSS-file plus some images that enable programmers to write web applications with the look-and-feel of native iPhone applications.

HAWHAW/Nihao applications are accessable from each sort of (mobile) browser and appear within a nice simulator when viewed on a web browser.



9.2. What kind of widgets are supported?

Links, toolbars and toolbar buttons as shown here.

List groups and back-buttons as shown here.

Form elements and submit-buttons as shown here.

Text panels and call-buttons as shown here.

Toolbar buttons currently render fine on Webkit-based browsers only (iPhone, iPod Touch, Safari, ...). Internet Explorer, Firefox & Co. don't have the required CSS functionality to allow a perfect simulation of iPhone-style buttons. Any ideas are welcome ...



9.3. Is Nihao a clone of iUI?

Nihao is inspired by iUI and re-uses a lot of iUI's image files and CSS definitions. It would be great if Nihao could merge with iUI, but this is nearly impossible as HAWHAW and iUI use a very different programming model and a very different subset of HTML.

Nihao does not use any Ajax/Javascript like iUI does. While iUI loads various sub-pages within one HTML document, HAWHAW/Nihao uses a standard navigation model from url to url. This is common practice for most web applications but also is a blocking point for smooth page transformations, which are offered by iUI.

HAWHAW's/Nihao's main advantage compared to iUI is that it supports a huge amount of access technologies and browser types. While iUI is strictly targeted to iPhone users and offers an awesome real native iPhone application feeling to them, Nihao is more a compromise solution for a broader audience.

Check out both solutions and then decide which way to go!



9.4. How can I get started?

You can download Nihao from the download section of the HAWHAW homepage.

The distribution contains sample applications for all HAWHAW flavours:

  • HAWHAW PHP library (hawhaw.inc)
  • HAWHAW XML
  • HawTags
  • HAWHAW.NET (see readme file for details)


9.5. Which browsers are supported by Nihao?

While HAWHAW/Nihao applications reach their best browsing experience on the iPhone, they are accessible on all devices supported by HAWHAW.



9.6. Can my iPhone interprete HAWHAW XML without proxy?

Yes, believe it not: The iPhone is able to interprete HAWHAW XML markup code without any HAWHAW proxy conversion! Like modern web browsers the iPhone is XSLT-capable and therefore can deal with HAWHAW XML documents as provided here:

http://nihao.hawhaw.de/samples/xml/remix.xml

Please consider this access option more as a gimmick because it has some drawbacks: There is no browser detection involved at all. The XSLT transformation creates some sort of hardcoded XHTML, which can not be interpreted by many browsers and devices. And finally the heart of HAWHAW, the PHP library hawhaw.inc, is totally bypassed and replaced by a single XSLT file.

Therefore the preferred way to get access to this demo therefore is via a HAWHAW proxy like this:

http://x.hawhaw.net/nihao.hawhaw.de/samples/xml/remix.xml

That said it's finally up to you how you decide to publish HAWHAW XML applications. One thing to keep in mind is that for many browsers it is a mandatory requirement that the XSLT file is located on the same web server under the same domain and even in the same path as the XML file. Otherwise the XSL transformation does simply not happen ...

9.7. Why is the iPhone skin simulator not part of the Nihao distribution?

For copyright reasons. Per default the layout.css file uses a simulator image from the HAWHAW web site. It is up to you to use any local simulator image of your choice instead.




10. Hastenix

10.1. What is Hastenix?

Hastenix stands for 'Hawhaw Adapter for aSTErisk aNd voIceXml' and is an AGI perl script for the Asterisk Open Source PBX.

The Hastenix script enables your Asterisk to interprete HAWHAW-created VoiceXML.



10.2. What can I do with Hastenix?

With Hastenix you can create interactive voice applications on your Asterisk softswitch. Hastenix supports text-to-speech conversion, recognition of DTMF input, recording/replaying of speech input, transfer of phone calls and much more.

Hastenix interpretes the VoiceXML output of a HAWHAW-based web server application and controls your Asterisk accordingly by means of the AGI interface.

A great example for what can be done with Hastenix is the german info site: LPG & CNG Tankstellenverzeichnis. This site provides a Hastenix-based telephony info service that allows car drivers to retrieve information about gas fueling stations in certain locations. German speakers (or at least listeners) can test the "Ask Katrin!" telephony service at: +49-521-3031881



10.3. Is Hastenix a full-blown VoiceXML browser for the Asterisk?

No, not approximately. HAWHAW's VoiceXML output uses a rather small subset of the VoiceXML complexity, and even not all HAWHAW elements are fully supported yet. If you have a running VoiceXML application deployed at a professional VoiceXML provider's site, chances are poor that you get your application running on your Asterisk by means of the Hastenix script.

The term "Hastenix" is german slang and means "You have nothing". In fact you have much more than nothing, but don't expect to get a standard-compliant VoiceXML browser.



10.4. What are the system requirements to run Hastenix?
  • Linux box with Asterisk 1.2 or higher
  • Perl 5.8 or higher with thread support installed
  • Festival, Cepstral/Swift, MBROLA, or any other text-to-speech converter installed
  • HAWHAW-enabled webserver (can run locally on the asterisk box or remote somewhere on the internet)


10.5. Where can I download Hastenix?

You can download the Hastenix perl script here.



10.6. What is the installation procedure?
  1. Check system requirements (see above)
  2. Download hastenix.pl and store it in your agi directory, e.g. /var/lib/asterisk/agi-bin
  3. Edit the configuration part on top of hastenix.pl
  4. Edit your dialplan in extension.conf.
    Instruct your asterisk to get input from an existing HAWHAW application, e.g. from the official HAWHAW demo at http://wap.hawhaw.de/:
      exten => 567,1,AGI,hastenix.pl|http://wap.hawhaw.de/
      exten => 567,2,Hangup
    
  5. Dial your hastenix extension (here 567), listen to the voice output and watch the Asterisk console window for error messages.
  6. Download and install missing perl modules from CPAN if required.
  7. If everythings works fine, you should be able to hear the HAWHAW welcome message. After a short delay you get redirected to the examples menu, where you should press the "1" key in order to get forwarded to the first HAWHAW example. After the text has been spoken, your Asterisk should terminate the call automatically.
  8. Write your own HAWHAW-based voice applications, deploy them on your webserver and modify your extension.conf accordingly (see above).



10.7. Are there any coding examples for HAWHAW-based voice applications?

Please take a look at the common HAWHAW coding examples from the HAWHAW demo. You can use both hawhaw.inc for PHP-coded applications or HAWHAW XML for XML-based applications.

Please note that the following subjects are not yet supported by hastenix.pl:

  • All kind of voice input. All navigation has to be done by means of DTMF instead. If you use linksets, HAWHAW automatically assigns DTMF keys for each link within the linkset (see pass2 of the HAWHAW demo). If you use stand-alone links within your HAW_deck object, you have to assign a DTMF key by means of the set_voice_dtmf() method.
  • Sophisticated VoiceXML functions like set_voice_help(), set_voice_noinput(), set_voice_property(), set_voice_navigator() etc.
  • Forms are supported only with restrictions: For the input of a sequence of DTMF digits you can define a form that contains one HAW_input element (plus multiple HAW_hidden elements) like this:
    $myInput = new HAW_input("input", "", "Please enter some digits:",  "*N");
    
    That kind of form will trigger Hastenix to collect the user's DTMF input and submit the form after the # key has been pressed. Alternatively the maxlength-property of HAW_input can be set, which results in a submit as soon as the required number of DTMF digits have been received. Other form elements like select boxes, radio buttons, check boxes etc. are not supported.

Hastenix supports speech recording! For more information how speech recording can be implemented with HAWHAW and PHP, please continue here in this document. Please note that Hastenix will send the recorded speech input in GSM-format to your webserver.

Hastenix can play audio files which are stored on your webserver. If you provide audio files consequently, you can run Hastenix even without any text-to-speech converter installed on your Asterisk box. In this case you should set the $TTS configuration variable in hastenix.pl to 'none'. The URL of the audio files has to be defined by means of the set_voice_text() function which is available for several HAWHAW classes:

...
$myText = HAW_text("Welcome to Hastenix!");
$myText->set_voice_text("Welcome to Hastenix!", "http://www.foo.com/welcome.gsm");
...

You can provide sound files in each format your Asterisk box is able to deal with. The preferred asterisk format is GSM.



10.8. How does call transfer work?

Hastenix supports call transfers. Take a look at example 9 in the HAWHAW demo section to see how the HAW_phone object is to be used therefore generally.

To make a call transfer happen with Hastenix, you have to enhance the PHP script slightly as follows:

...
$phone = new HAW_phone("0175/12345678", "MOBILE");
$phone->set_voice_text("press 1 to get forwarded to my mobile phone");
$phone->set_voice_dtmf("1");
$PhonePage->add_phone($phone);
...

Additionally you have to edit the $DIALOUT variable in the hastenix.pl configuration part in order to tell Asterisk how outgoing calls have to be routed, e.g.:

my $DIALOUT = 'Dial SIP/*@mysipprovider-out|30';

Hastenix replaces the * character by the phone number provided in the HAW_phone object, before Asterisk is told to setup the outgoing call.

You should enable HAWHAW-controlled call transfer only if the HAWHAW scripts on the remote webserver are under your total control. Otherwise other people can instruct your Asterisk to establish arbitrary phone connections and you will be charged for them! You have been warned! To inhibit call transfer you can set the $DIALOUT variable like this:

my $DIALOUT = 'Busy';



Copyright (c) 2012 Norbert Huffschmid

http://www.hawhaw.de/

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

This FAQ was once generated by makefaq.

Valid HTML 4.0!