CGI::WML - Subclass LDS's "CGI.pm" for WML output and WML methods
use CGI::WML; $query = new CGI::WML; print $query->header(), $query->start_wml(), $query->template(-content=>$query->prev()), $query->card(-id=>"first_card", -title=>"First card", -content=>"<p>Hello WAP world!</p>"), $query->end_wml(); print $query->wml_to_wmlc(-wml=>$wml_buffer, -errorcontext=>2); ($page_title,$content) = $query->html_to_wml($buffer);
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/
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.
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');
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');
Use end_wml() to end the WML deck. Just included for completeness.
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>");
timer
The 'ID' and 'Content' elements are manditory, and have no defaults. All other parameters are optional.
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"));
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");
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
<go href="http://www.example.com/" method="get"/>
%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.
$query->do(-type=>"options", -label=>"Menu", -content=>qq(go href="#menu"/>)); gives
<do type="options" label="Menu" > <go href="#menu"/> </do>
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>
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");
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>));
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.
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.
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.
$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.
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.
($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.
Angus Wood <angus@z-y-g-o.com>, with loads of additions and improvements by Andy Murren <amurren@oven.com>
perl(1), perldoc CGI, tidy(1)
4 POD Errors
The following errors were encountered while parsing the POD:
You forgot a '=back' before '=head2'
=back without =over
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install CGI::WML, copy and paste the appropriate command in to your terminal.
cpanm
cpanm CGI::WML
CPAN shell
perl -MCPAN -e shell install CGI::WML
For more information on module installation, please visit the detailed CPAN module installation guide.