NAME

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

SYNOPSIS

  use CGI::WML;

  $q = new CGI::WML;

  print
     $q->header(),
     $q->start_wml(),
     $q->template(-content=>$q->prev()),
     $q->card(-id=>"first_card",
              -title=>"First card",
              -content=>"<p>Hello WAP world!</p>"),
     $q->card(-id=>"second",
              -title=>"Second Card",
              -content=>"<p>I am No2</p>"),
     $q->end_wml();

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

 

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://wap.z-y-g-o.com/tools/

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",
                     -cookie($q->cookie(-name=>"example",
                                        -value=>"123"),
                     -nph=>1);

WARNING: If you are mixing HTML and WML output in the same script you'll need to explicity set "text/html" as the content type where appropriate. This is a change from pre 1.52 versions.

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', -lang=>"en-gb", -encoding=>"iso-8859-1", -meta=>{'scheme'=>'foobar', 'name'=>'mystuff'});

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

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=>$q->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 = $q->img( -src => '/icons/blue_boy.wbmp', -alt => 'Blue Boy', -localsrc => '$var', -vspace => '25', -hspace => '30 -align => 'bottom', -height => '15', -width => '10');

NOTE the Unwired Planet (UP) browser 3.1 from Phone.com uses the HDML mark up to display images. HDML is a propritarty mark up developed by Unwire Planet so it could be first to market with Wireless Internet. UP browsers are (AFAIK) the only ones supporting this mark up. Currently (May 2000) all Motorola phones are using this browser. Ericsson and Motorla will be deploying the UP 4.0 browser on future devices. Nokia has it's own 100% WAP 1.1 compliant browser that will be deployed on all future Nokia devices.

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

COMPILING WML DECKS

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

A fairly good WML to WBML converter/compiler is included for convinience purposes, although it is not intended to replace the compiler on the WAP gateway it may prove useful.

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.

AUTHOR

Angus Wood <angus@z-y-g-o.com>, with additions and improvements by Andy Murren <amurren@oven.com>

CREDITS

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

SEE ALSO

perl(1), perldoc CGI.

cpanm CGI::WML

perl -MCPAN -e shell
install CGI::WML