NAME

PerlCodeLibrary - a selection of functions for use by perl code embedded in a WebMake file.

SYNOPSIS

<{perl

  $foo = get_content ($bar);
  [... etc.]

  # or:

  $foo = $self->get_content ($bar);
  [... etc.]

}>

DESCRIPTION

These functions allow code embedded in a <{perl}> or <{perlout}> section of a WebMake file to be used to script the generation of content.

Each of these functions is defined both as a standalone function, or as a function on the PerlCode object. Code in one of the <{perl*}> sections can access this PerlCode object as the $self variable. If you plan to use WebMake from mod_perl or in a threaded environment, be sure to call them as methods on $self.

METHODS

$expandedtext = expand ($text);

Expand a block of text, interpreting any references, user tags, or any other WebMake markup contained within.

@names = content_matching ($pattern);

Find all items of content that match the glob pattern $pattern. If $pattern begins with the prefix RE:, it is treated as a regular expression. The list of items returned is not in any logical order.

@objs = content_names_to_objects (@names);

Given a list of content names, convert to the corresponding list of content objects, ie. objects of type HTML::WebMake::Content.

$obj = get_content_object ($name);

Given a content name, convert to the corresponding content object, ie. objects of type HTML::WebMake::Content.

@names = content_objects_to_names (@objs);

Given a list of objects of type HTML::WebMake::Content, convert to the corresponding list of content name strings.

@sortedobjs = sort_content_objects ($sortstring, @objs);

Sort a list of content objects by the sort string $sortstring. See ''sorting.html'' in the WebMake documentation for details on sort strings.

@names = sorted_content_matching ($sortstring, $pattern);

Find all items of content that match the glob-style pattern $pattern. The list of items returned is ordered according to the sort string $sortstring. If $pattern begins with the prefix RE:, it is treated as a regular expression.

See ''sorting.html'' in the WebMake documentation for details on sort strings.

This, by the way, is essentially implemented as follows:

my @list = $self->content_matching ($pattern);
@list = $self->content_names_to_objects (@list);
@list = $self->sort_content_objects ($sortstring, @list);
return $self->content_objects_to_names (@list);

$str = get_content ($name);

Get the item of content named $name. Equivalent to a $ {content_reference}.

@list = get_list ($name);

Get the item of content named, but in Perl list format. It is assumed that the list is stored in the content item in whitespace-separated format.

set_content ($name, $value);

Set a content chunk to the value provided. This content will not appear in a sitemap, and navigation links will never point to it.

Returns the content object created.

set_list ($name, @values);

Set a content chunk to a list containing the values provided, separated by spaces. This content will not appear in a sitemap, and navigation links will never point to it.

Returns the content object created.

set_mapped_content ($name, $value, $upname);

Set a content chunk to the value provided. This content will appear in a sitemap and the navigation hierarchy. $upname should be the name of it's parent content item. This item must not be metadata, or other dynamically-generated content; only first-class mapped content can be used.

Returns the content object created.

del_content ($name);

Delete a named content chunk.

@names = url_matching ($pattern);

Find all URLs (from <out> and <media> tags) whose name matches the glob-style pattern $pattern. The names of the URLs, not the URLs themselves, are returned. If $pattern begins with the prefix RE:, it is treated as a regular expression.

$url = get_url ($name);

Get a named URL. Equivalent to an $ (url_reference).

set_url ($name, $url);

Set an URL to the value provided.

del_url ($name);

Delete an URL.

$listtext = make_list ($itemname, @namelist);

Generate a list by iterating through the @namelist, setting the content item item to the current name, and interpreting the content chunk named $itemname. This content chunk should refer to ${item} appropriately.

Each resulting block of content is appended to a $listtext, which is finally returned.

See the news_site.wmk sample site for an example of this in use.

define_tag ($tagname, \&handlerfn, @required_attributes);

Define a tag for use in content items. Any occurrences of this tag, with at least the set of attributes defined in @required_attributes, will cause the handler function referred to by handlerfn to be called.

Handler functions are called as fcllows:

handler ($tagname, $attrs, $text, $perlcode);

Where $tagname is the name of the tag, $attrs is a reference to a hash containing the attribute names and the values used in the tag, and $text is the text between the start and end tags.

$perlcode is the PerlCode object, allowing you to write proper object-oriented code that can be run in a threaded environment or from mod_perl. This can be ignored if you like.

This function returns an empty string.

define_empty_tag ($tagname, \&handlerfn, @required_attributes);

Define a tag for use in content items. This is identical to define_tag above, but is intended for use to define ''empty'' tags, ie. tags which occur alone, not as part of a start and end tag pair.

The handler in this case is called with an empty string for the $text argument.

define_preformat_tag ($tagname, \&handlerfn, @required_attributes);

Identical to define_tag, above, with one difference; these tags will be interpreted before the content undergoes any format conversion.

define_empty_preformat_tag ($tagname, \&handlerfn, @required_attributes);

Identical to define_empty_tag, above, with one difference; these tags will be interpreted before the content undergoes any format conversion.

define_wmk_tag ($tagname, \&handlerfn, @required_attributes);

Define a tag for use in the WebMake file.

Aside from operating on the WebMake file instead of inside content items, this is otherwise identical to define_tag above,

define_empty_wmk_tag ($tagname, \&handlerfn, @required_attributes);

Define an empty, aka. standalone, tag for use in the WebMake file.

Aside from operating on the WebMake file instead of inside content items, this is otherwise identical to define_tag above,

$obj = get_root_content_object();

Get the content object representing the ''root'' of the site map. Returns undef if no root object exists, or the WebMake file does not contain a &lt;sitemap&gt; command.

$name = get_current_main_content();

Get the ''main'' content on the current output page. The ''main'' content is defined as the most recently referenced content item which (a) is not generated content (perl code, sitemaps, breadcrumb trails etc.), and (b) has its map attribute set to "true".

Note that this API should only be called from a deferred content reference; otherwise the ''main'' content item may not have been referenced by the time this API is called.

undef is returned if no main content item has been referenced.

$main = get_webmake_main_object();

Get the current WebMake interpreter's instance of HTML::WebMake::Main object. Virtually all of WebMake's functionality and internals can be accessed through this.