XAO::DO::Web::Utility - Miscellaneous utility displayable functions


Currently is only useful in XAO::Web site context.


This is a collection of various functions that do not fit well into other objects and are not worth creating separate objects for them (at least at present time).


Utility object is based on Action object (see XAO::DO::Web::Action) and therefor what it does depends on the "mode" argument.

For each mode there is a separate method with usually very similar name. See below for the list of mode names and their method counterparts.

'tracking-url' => tracking_url (%)

Displays tracking URL for given carrier and tracking number.

Arguments are "carrier" and "tracknum". Supported carriers are:

  • 'usps'

  • 'ups'

  • 'fedex'

  • 'dhl'

  • 'yellow' (see


 <%Utility mode="tracking-url" carrier="usps" tracknum="VV1234567890"%>

Would display:
'config-param' => config_param (%)

Displays site configuration parameter with given "name". Example:

 <%Utility mode="config-param" name="customer_support" default=""%>

Would display whatever is set in site's modules for variable "customer_support" or "" if it is not set.

'pass-cgi-params' => pass_cgi_params (%)

Builds a piece of HTML code containing current CGI parameters in either form or query formats depending on "result" argument (values are "form" or "query" respectfully).

List of parameters to be copied must be in "params" arguments and may end with asterisk (*) to include parameters by template. In addition to that you can exclude some parameters that wer listed in "params" by putting their names (or name templates) into "except" argument.

Form example:

 <%Utility mode="pass-cgi-params" result="form" params="aa,bb,cc"%>
 <INPUT NAME="dd">

Would produce:

 <INPUT TYPE="HIDDEN" NAME="aa" VALUE="current value of aa">
 <INPUT TYPE="HIDDEN" NAME="bb" VALUE="current value of bb">
 <INPUT TYPE="HIDDEN" NAME="bb" VALUE="current value of cc">
 <INPUT NAME="dd">

Actual output would be slightly different because no carriage return symbol would be inserted between hidden <INPUT> tags. This is done for rare situations when your code is space sensitive and you do not want to mess it up.

Query example:

 <A HREF="report.html?sortby=price&<%Utility
                                   %>">Sort by price</A>

If current page arguments were "sku=123&category=234&sortby=vendor" then the output would be:

 <A HREF="report.html?sortby=price&sku=123&category=234">Sort by price</A>

For 'query' results it is convenient to also provide a 'prefix' parameter that would be included in the output only if there are parameters to copy. This allows to cleanly format URLs without extra '?' or '&' symbols.

All special symbols in parameter values would be properly escaped, you do not need to worry about that.

'current-url' => show_current_url ()

Prints out current page URL without parameters. Accepts the same arguments as Page's pageurl method and displays the same value.

'base-url' => show_base_url ()

Prints out base site URL without parameters. Accepts the same arguments as Page's base_url() method and displays the same value.

'number-ordinal-suffix' => number_ordinal_suffix (%)

Displays a two-letter suffix to make a number into an ordinal, i.e. 2 into "2-nd", 43 into "43-rd", 1001 into "1001-st" and so on.

Takes one argument -- 'number'.

'show-pagedesc' => show_pagedesc (%)

Displays value of pagedesc structure (see XAO::Web) with the given "name". Default name is "fullpath". Useful for processing tree-to-object mapped documents.

'select-time-range' => select_time_range(%)

Displays a list of <OPTION ...> tags for the given time range.

Exact output depends on "type" argument that can be:


Lists days of month from optional "start" day (default is "1") to optional "end" day (default is the number of days in the current month).


Two optional arguments "start" and "end" set start and end date for the time range. The format is YYYY-Q, where YYYY is a year in four digits format and Q is quarter number from 1 to 4.

If "end" is not set the current quorter is assumed.

    Special argument "current" will have select_time_range() add "SELECTED" option to the appropriate entry in the final list. The format is the same as for "start" and "end".

    Default sorting is from most recent down, but this can be changed with non-zero "ascend" argument.


     <SELECT NAME="qqq">
     <%Utility mode="select-time-range"

    Would produce something like:

     <SELECT NAME="qqq">
     <OPTION VALUE="2001-1">2001, 1-st Qtr
     <OPTION VALUE="2000-4">2000, 4-th Qtr
     <OPTION VALUE="2000-3" SELECTED>2000, 3-rd Qtr
     <OPTION VALUE="2000-2">2000, 2-nd Qtr
     <OPTION VALUE="2000-1">2000, 1-st Qtr




Copyright (c) 2005 Andrew Maltsev

Copyright (c) 2001-2004 Andrew Maltsev, XAO Inc.

<> --


Recommended reading: XAO::Web, XAO::DO::Web::Page.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 589:

You forgot a '=back' before '=head1'

You forgot a '=back' before '=head1'

You forgot a '=back' before '=head1'