NAME

CGI::WML - Subclass LDS's "CGI.pm" for WML output and WML methods

SYNOPSIS

  use CGI::WML;

  $query = new CGI::WML;

  $content =  $query->p("Hello WAP world");

  print
     $query->header(),
     $query->start_wml(),
     $query->template(-content=>$query->prev()),
     $query->card(-id=>"first_card",
              -title=>"First card",
              -content=>$content),
     $query->end_wml();

  print
     $query->wml_to_wmlc(-wml=>$wml_buffer,
                         -errorcontext=>2);

  ($page_title,$content) = $query->html_to_wml($buffer);

DESCRIPTION

This is a library of perl functions to allow CGI.pm-style programming to be applied to WAP/WML. Since this is a subclass of Lincoln Stein's CGI.pm all the normal CGI.pm methods are available. See perldoc CGI if you are not familiar with CGI.pm

The most up to date version of this module is available at http://cgi-wml.sourceforge.net/

FUNCTIONS

The library provides an object-oriented method of creating correct WML, together with some canned methods for often-used tasks. As this module is a subclass of CGI.pm, the same argument-passing method is used, and arguments may be passed in any order.

CREATING A WML DECK

header()

This function now overrides the default CGI.pm 'Content-type: ' header to be 'text/vnd.wap.wml' by default. All the standard CGI.pm header functions are still available for use.

print $query->header();

        -or-
print $query->header(-expires=>"+1m",
                     -Refresh=>'20; URL='/newplace.wml');

start_wml() Use the start_wml method to create the start of a WML deck, if you wish you can pass paramaters to the method to define a custom DTD, XML language value and any 'META' information. If a DTD is not specified then the default is to use WML 1.1

$query->start_wml(-dtd => '-//WAPFORUM//DTD WML 5.5//EN', -dtd_url => 'http://www.wapforum.org/DTD/wml_5.5.xml', -lang => 'en-gb', -encoding => 'iso-8859-1', -meta => {'scheme'=>'foobar', 'name' =>'mystuff'} );

There is no direct support for the HTTP-EQUIV type of <meta> tag. This is because you can modify the HTTP header directly with the header() method. For example, if you want to send the Cache-control: header, do it in the header() method:

$q->header(-cache_control=>'No-cache; forua=true');

end_wml()

Use end_wml() to end the WML deck. Just included for completeness.

CREATING WML CARDS

card()

Cards are created whole, by passing paramaters to the card() method, as well as the card attributes, a timer may be added to the start of the card.

$query->card(-id=>"card_id", -title=>"First Card", -ontimer=>"#next_card", -timer=>$query->timer(-name=>"timer1",-value=>"30"), -newcontext=>"true", -onenterforward=>"#somecard", -onenterbackward=>"#othercard", -content=>"<p>Hello WAP world</p>");

The 'ID' and 'Content' elements are manditory, and have no defaults. At least one paragraph tag is also required. If you get everything else correct and nothing is diplayed, that may be the reason. All other parameters are optional.

An other way of making the above card would be this:

$content = $query->p("Hello WAP world");

$query->card(-id=>"card_id", -title=>"First Card", -ontimer=>"#next_card", -timer=>$query->timer(-name=>"timer1",-value=>"30"), -newcontext=>"true", -onenterforward=>"#somecard", -onenterbackward=>"#othercard", -content=>$content);

TEMPLATES

The template() method creates a template for placing at the start of a card. If you just need to add a back link, use the prev() method.

$query->template(-content=>$query->prev(-label=>"Go Back"));

TIMERS

A card timer is used with the card() method to trigger an action, the function takes two arguments, the name of the timer and it's value in milliseconds.

$query->timer(-name=>"mytimer", -value=>"30");

GO BLOCKS

A <go block is created either as a single line

$query->go(-method=>"get", -href=>"http://www.example.com/"); <go href="http://www.example.com/" method="get"/> or as a block

%pfs = ('var1'=>'1', 'var2'=>'2', 'varN'=>'N');

$query->go(-method=>"post", -href=>"http://www.example.com/", -postfields=>\%pfs);

<go href="http://www.example.com/" method="get"> <postfield name="var1" value="1"/> <postfield name="var2" value="2"/> <postfield name="varN" value="N"/> </go>

depending on wether it is passed a hash of postfields.

DO

$query->do(-type=>"options", -label=>"Menu", -content=>qq(go href="#menu"/>)); gives

<do type="options" label="Menu" > <go href="#menu"/> </do>

PREV

A canned 'back' link, takes an optional label argument. Default label is 'Back'. For use in templates

$query->prev(-label=>"Reverse");

<do type="accept" label="Reverse"><prev/></do>

INPUT

Create an input entry field. No defaults, although not all arguments need to be specified.

$query->input(-name=>"pin", -value=>"1234", -type=>"text", -size=>4, -title=>"Enter PIN", -format=>"4N", -maxlength=>4, -emptyok=>"false");

ONEVENT

An onevent element may contain one of 'go','prev','noop' or 'refresh' and be of type 'onenterforward', 'onenterbackward' or 'ontimer'.

$query->onevent(-type=>"onenterforward", -content=>qq(<refresh> <setvar name="x" value="1"/> </refresh>));

IMG

An image can be created with the following attributes:

 alt       Text to display in case the image is not displayed
 align     can be top, middle, bottom
 src       The absolute or relative URI to the image
 localsrc  a variable (set using the setvar tag) that refers to an image
           this attribute takes precedence over the B<src> tag
 vspace    
 hspace    amount of white space to inserted to the left and right 
           of the image [hspace] or above and below the image [vspace] 
 height    
 width     These attributes are a hint to the user agent to leave space
           for the image while the page is rendering the page.  The 
           user agent may ignore the attributes.  If the number length 
           is passed as a percent the resulting image size will be
           relative to the amount of available space, not the image size.

my $img = $query->img( -src => '/icons/blue_boy.wbmp', -alt => 'Blue Boy', -localsrc => '$var', -vspace => '25', -hspace => '30 -align => 'bottom', -height => '15', -width => '10');

NOTE the localsrc element, and formatting elements are not supported consistently by the current generation of terminals, however they should simply ignore the attributes they do not understand.

Dial Tags

When using cell phones in WAP you can make calls. When a dial tag is selected the phone drops out of the WAP stack and into what ever is the protocol used for phone calls. At the conclusion of the call the phone should return to the WAP stack in the same place that you linked to the phone number.

The tag looks much like a regular link, but has some special syntax.

$query->dialtag(-label =>"Joe's Pizza", -number=>"12125551212");

The recieving terminal must support WTAI for this link to work.

WML SHORTCUTS

p b br table etc. etc. Just like the original CGI.pm, this module includes functions for creating correct WML by calling methods of a query object.

WML Shortcuts may be called in two ways;

With a single parameter, which will be the content of the tag, for example;

       Perl code                           WML Result
     ---------------------            ---------------------
     $query->b("Bold text);               <b>bold</b>
     $query->p("Hello");                  <p>Hello</p>

     $query->p($query->b("Hello"));       <p><b>Hello</b></p> 

     $query->br();                        <br/> # "No-close" tags are
                                                # automatically dealt with

Alternatively, they can be called with a list of arguments, specifying content and attibutes.

      Perl code                           WML Result
      ---------------------            ---------------------
      $query->p(-align=>"left",        <p align="left">Hi there</p>
                -content=>"Hi there");
      
 When being called with the second syntax, the 'content' parameter
 specifies the content of tags. 

 All WML 1.1 tags are available via this method.

COMPILING WML DECKS

$query->wml_to_wmlc(-wml=>$buffer, -errorcontext=>2); # default 0

A WML to WBXML converter/compiler is included for convinience purposes, although it is not intended to replace the compiler on the WAP gateway it may prove useful, for example measuring what the compiled document size will be.

     $size = length($query->wml_to_wmlc(-wml=>$wml,
                                        -errorcontext=>0));

NOTE WBXML string tables are used to compress the document size down as small as possible, giving excellent document size performance. Because of this though, the size returned by the function may be smaller than the size of the WBXML document created by the WAP gateway. Turning this feature off will be an option in future releases.

The function takes two arguments, a buffer of textual WML and an optional argument specifiying that should the XML parser fail then X many lines of the buffer before and after the point where the error occured will be printed to show the context of the error.

ERRORCONTEXT WARNING Setting this to any non-zero value will cause your program to exit if the routine is passed WML which is not "well formed" this is due to the fact that XML::Parser calls die() upon such events.

If you wish to test wether a WML document is well formed, then set this value to zero and check the return value of the function. The function returns undef upon failiure and issues a warning, anything other than undef indicates success.

HTML TO WML CONVERSION

($title,$content) = $query->html_to_wml($buffer);

-or-

($title,$content) = $query->html_to_wml(\*FILEHANDLE);

A limited HTML to WML converter is included in this package. Be warned that only pretty well marked-up HTML will convert cleanly to WML. Dave Ragget's excellent tidy utility [ see http://www.w3.org/People/Raggett/tidy/ ] will clean up most HTML into a parseable state.

The main purpose of this function is for converting server error messages and the "Compact HTML" used on "I-Mode" systems to readable WML, not for general page translation.

Potential users of this function are encouraged to read the source to this module to gain a better understanding of the underlying mechanics of the translation.

AUTHOR

Version 0.06 - 0.09

Andy Murren <amurren@users.sourceforge.net>

Versions 0.01 - 0.05

Angus Wood <angus@z-y-g-o.com>, with loads of additions and improvements by Andy Murren <amurren@users.sourceforge.net>

CREDITS

Wilbert Smits <wilbert@telegraafnet.nl> for the header() function content-type override.

CHANGES

See Changes file distributed with the module.

SEE ALSO

perl(1), perldoc CGI, tidy(1)

cpanm CGI::WML

perl -MCPAN -e shell
install CGI::WML