<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html lang="en">
<head>
<title>
WebMake: Documentation: HTML::WebMake::PerlCodeLibrary
</title>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1" />
<meta name="generator" content="WebMake/2.3" />
<style type="text/css">
body {
background-color: #ffffff;
color: #000000;
line-height: 110%;
margin-left: 10px;
margin-right: 10px;
}
p, table, td, th {
font-family: verdana,lucida,helvetica,sans-serif;
font-size: 11px;
line-height: 110%;
}
pre {
margin-left: 3%;
white-space: pre;
}
code, samp, pre, p pre {
font-family: "lucida console", "Courier New", courier, "fixed-width", monospace;
font-weight: bold;
}
H1 {
font-size: 150%; font-family: Garamond, "Book Antiqua",Times,serif;
background: #FFCC66; text-align: center;
padding: 0.5em 1em 0.5em 1em; border-width: 1px;
border-color: black; border-style: solid; line-height: 120%;
}
H2 {
font-size: 125%; font-family: Garamond, "Book Antiqua",Times,serif;
background: #FFDD77; text-align: center;
padding: 0.5em 1em 0.5em 1em; border-width: 1px;
border-color: black; border-style: solid; line-height: 100%;
}
H3 {
font-size: 100%; font-family: Garamond, "Book Antiqua",Times,serif;
background: #FFEE88; text-align: center;
padding: 0.5em 1em 0.5em 1em; border-width: 1px;
border-color: black; border-style: solid;
}
H4 { font-size: 75%; font-family: Garamond, "Book Antiqua",Times,serif; }
H5 { font-size: 50%; font-family: Garamond, "Book Antiqua",Times,serif; }
H6 { font-size: 25%; font-family: Garamond, "Book Antiqua",Times,serif; }
A:link {
font-weight: bold;
color: #004000;
text-decoration: underline;
}
A:visited {
font-weight: bold;
color: #008000;
text-decoration: underline;
}
A:active {
font-weight: bold;
color: #800000;
text-decoration: underline;
}
dt {
font-size: medium;
font-weight: bold;
padding-top: 8px; padding-bottom: 8px;
}
dd {
padding-top: 8px; padding-bottom: 8px;
}
</style>
</head>
<body bgcolor="#ffffff" text="#000000" link="#3300cc" vlink="#660066">
<!-- font tag for compat with non-CSS browsers -->
<font face="lucida,verdana,sans-serif">
<div align="center">
<img src="images/WebMakeTitle.png" alt="WebMake" width="500" height="122" />
</div>
<table width="100%">
<tr>
<td valign="top">
<strong><a href="http://webmake.taint.org/">WebMake</a>
Documentation</strong> (version 2.3)
</td>
<td valign="top">
<div align="right">
[ <a href="Main.pm.html">Back</a> | <a href="index_09-man.html">Forward</a> | <a href="index.html">Index</a>
| <a href="allinone.html">All In One</a> ]
</div>
</td>
</tr>
</table>
<!-- yes, it's that Mozilla black-border code again ;) -->
<!-- stolen from www.mozilla.org via rc3.org -->
<table border="0" cellpadding="0" cellspacing="0" width="100%">
<tr>
<td bgcolor="#aaaaaa">
<table border="0" cellspacing="4" cellpadding="4" width="100%">
<tr>
<td bgcolor="#ffffff">
<table border="0" cellspacing="4" cellpadding="4" width="100%">
<tr>
<td>
<h1>HTML::WebMake::PerlCodeLibrary</h1><a name="__index__"></a><!-- INDEX BEGIN -->
<ul>
<li>
<a href="#name">NAME</a>
</li>
<li>
<a href="#synopsis">SYNOPSIS</a>
</li>
<li>
<a href="#description">DESCRIPTION</a>
</li>
<li>
<a href="#methods">METHODS</a>
</li>
</ul>
<!-- INDEX END -->
<hr />
<h1><a name="name">NAME</a></h1><p>
PerlCodeLibrary - a selection of functions for use by perl code embedded in a
WebMake file.
</p>
<hr />
<h1><a name="synopsis">SYNOPSIS</a></h1><pre>
<{perl</pre><pre>
$foo = get_content ($bar);
[... etc.]</pre><pre>
# or:</pre><pre>
$foo = $self->get_content ($bar);
[... etc.]</pre><pre>
}></pre><hr />
<h1><a name="description">DESCRIPTION</a></h1><p>
These functions allow code embedded in a <{perl}> or <{perlout}> section of a
WebMake file to be used to script the generation of content.
</p>
<p>
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 <code>$self</code> variable. If you plan to use
WebMake from mod_perl or in a threaded environment, be sure to call them as
methods on <code>$self</code>.
</p>
<hr />
<h1><a name="methods">METHODS</a></h1><dl>
<dt>
<strong><a name="item_expand">$expandedtext = expand ($text);</a></strong><br />
</dt>
<dd>
Expand a block of text, interpreting any references, user tags, or
any other WebMake markup contained within.
</dd>
<dt>
<strong><a name="item_content_matching">@names = content_matching ($pattern);</a></strong><br />
</dt>
<dd>
Find all items of content that match the glob pattern <code>$pattern</code>. If
<code>$pattern</code> begins with the prefix <strong>RE:</strong>, it is treated as a regular
expression. The list of items returned is not in any logical order.
</dd>
<dt>
<strong><a name="item_content_names_to_objects">@objs = content_names_to_objects (@names);</a></strong><br />
</dt>
<dd>
Given a list of content names, convert to the corresponding list of content
objects, ie. objects of type <code>HTML::WebMake::Content</code>.
</dd>
<dt>
<strong><a name="item_get_content_object">$obj = get_content_object ($name);</a></strong><br />
</dt>
<dd>
Given a content name, convert to the corresponding content object, ie. objects
of type <code>HTML::WebMake::Content</code>.
</dd>
<dt>
<strong><a name="item_content_objects_to_names">@names = content_objects_to_names (@objs);</a></strong><br />
</dt>
<dd>
Given a list of objects of type <code>HTML::WebMake::Content</code>, convert to
the corresponding list of content name strings.
</dd>
<dt>
<strong><a name="item_sort_content_objects">@sortedobjs = sort_content_objects ($sortstring, @objs);</a></strong><br />
</dt>
<dd>
Sort a list of content objects by the sort string <code>$sortstring</code>.
See ''sorting.html'' in the WebMake documentation for details on
sort strings.
</dd>
<dt>
<strong><a name="item_sorted_content_matching">@names = sorted_content_matching ($sortstring, $pattern);</a></strong><br />
</dt>
<dd>
Find all items of content that match the glob-style pattern <code>$pattern</code>. The
list of items returned is ordered according to the sort string <code>$sortstring</code>.
If <code>$pattern</code> begins with the prefix <strong>RE:</strong>, it is treated as a regular
expression.
<p>
See ''sorting.html'' in the WebMake documentation for details on sort strings.
</p>
<p>
This, by the way, is essentially implemented as follows:
</p>
<pre>
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);</pre>
</dd>
<dt>
<strong><a name="item_get_content">$str = get_content ($name);</a></strong><br />
</dt>
<dd>
Get the item of content named <code>$name</code>. Equivalent to a $ {content_reference}.
</dd>
<dt>
<strong><a name="item_get_list">@list = get_list ($name);</a></strong><br />
</dt>
<dd>
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.
<p>
Note that you may have to assign this list to an array, to force it to be
interpreted by perl as an array instead of as a scalar. This is annoying,
but seems unavoidable.
</p>
</dd>
<dt>
<strong><a name="item_set_content">set_content ($name, $value);</a></strong><br />
</dt>
<dd>
Set a content chunk to the value provided. This content will not appear in a
sitemap, and navigation links will never point to it.
<p>
Returns the content object created.
</p>
</dd>
<dt>
<strong><a name="item_set_list">set_list ($name, @values);</a></strong><br />
</dt>
<dd>
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.
<p>
Returns the content object created.
</p>
</dd>
<dt>
<strong><a name="item_set_mapped_content">set_mapped_content ($name, $value, $upname);</a></strong><br />
</dt>
<dd>
Set a content chunk to the value provided. This content will appear in a
sitemap and the navigation hierarchy. <code>$upname</code> 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.
<p>
Returns the content object created.
</p>
</dd>
<dt>
<strong><a name="item_del_content">del_content ($name);</a></strong><br />
</dt>
<dd>
Delete a named content chunk.
</dd>
<dt>
<strong><a name="item_url_matching">@names = url_matching ($pattern);</a></strong><br />
</dt>
<dd>
Find all URLs (from <out> and <media> tags) whose name matches the glob-style
pattern <code>$pattern</code>. The names of the URLs, not the URLs themselves, are
returned. If <code>$pattern</code> begins with the prefix <strong>RE:</strong>, it is treated as a
regular expression.
</dd>
<dt>
<strong><a name="item_get_url">$url = get_url ($name);</a></strong><br />
</dt>
<dd>
Get a named URL. Equivalent to an $ (url_reference).
</dd>
<dt>
<strong><a name="item_set_url">set_url ($name, $url);</a></strong><br />
</dt>
<dd>
Set an URL to the value provided.
</dd>
<dt>
<strong><a name="item_del_url">del_url ($name);</a></strong><br />
</dt>
<dd>
Delete an URL.
</dd>
<dt>
<strong><a name="item_make_list">$listtext = make_list ($itemname, @namelist);</a></strong><br />
</dt>
<dd>
Generate a list by iterating through the <code>@namelist</code>, setting the content item
<code>item</code> to the current name, and interpreting the content chunk named
<code>$itemname</code>. This content chunk should refer to <code></code> appropriately.
<p>
Each resulting block of content is appended to a $listtext, which is finally
returned.
</p>
<p>
See the <code>news_site.wmk</code> sample site for an example of this in use.
</p>
</dd>
<dt>
<strong><a name="item_define_tag">define_tag ($tagname, \&handlerfn, @required_attributes);</a></strong><br />
</dt>
<dd>
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.
<p>
Handler functions are called as fcllows:
</p>
<pre>
handler ($tagname, $attrs, $text, $perlcode);</pre><p>
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.
</p>
<p>
$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.
</p>
<p>
This function returns an empty string.
</p>
</dd>
<dt>
<strong><a name="item_define_empty_tag">define_empty_tag ($tagname, \&handlerfn, @required_attributes);</a></strong><br />
</dt>
<dd>
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.
<p>
The handler in this case is called with an empty string for the $text
argument.
</p>
</dd>
<dt>
<strong><a name="item_define_preformat_tag">define_preformat_tag ($tagname, \&handlerfn, @required_attributes);</a></strong><br />
</dt>
<dd>
Identical to <a href="#item_define_tag">define_tag</a>, above, with one difference; these tags will
be interpreted <strong>before</strong> the content undergoes any format conversion.
</dd>
<dt>
<strong><a name="item_define_empty_preformat_tag">define_empty_preformat_tag ($tagname, \&handlerfn, @required_attributes);</a></strong><br />
</dt>
<dd>
Identical to <a href="#item_define_empty_tag">define_empty_tag</a>, above, with one difference; these tags will
be interpreted <strong>before</strong> the content undergoes any format conversion.
</dd>
<dt>
<strong><a name="item_define_wmk_tag">define_wmk_tag ($tagname, \&handlerfn, @required_attributes);</a></strong><br />
</dt>
<dd>
Define a tag for use in the WebMake file.
<p>
Aside from operating on the WebMake file instead of inside content items, this
is otherwise identical to define_tag above,
</p>
</dd>
<dt>
<strong><a name="item_define_empty_wmk_tag">define_empty_wmk_tag ($tagname, \&handlerfn, @required_attributes);</a></strong><br />
</dt>
<dd>
Define an empty, aka. standalone, tag for use in the WebMake file.
<p>
Aside from operating on the WebMake file instead of inside content items, this
is otherwise identical to define_tag above,
</p>
</dd>
<dt>
<strong><a name="item_get_root_content_object">$obj = get_root_content_object();</a></strong><br />
</dt>
<dd>
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.
</dd>
<dt>
<strong><a name="item_get_current_main_content">$name = get_current_main_content();</a></strong><br />
</dt>
<dd>
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
<code>map</code> attribute set to ``true''.
<p>
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.
</p>
<p>
<code>undef</code> is returned if no main content item has been referenced.
</p>
</dd>
<dt>
<strong><a name="item_get_webmake_main_object">$main = get_webmake_main_object();</a></strong><br />
</dt>
<dd>
Get the current WebMake interpreter's instance of <code>HTML::WebMake::Main</code>
object. Virtually all of WebMake's functionality and internals can be accessed
through this.
</dd>
<dt>
<strong><a name="item_get_tmp_filename">$filename = get_tmp_filename($type, $extension);</a></strong><br />
</dt>
<dd>
Get a path to a temporary file in the WebMake ~/.webmake directory.
Useful for plugins. You should provide a string to use in the filename
as a clue to the tag type, e.g. ``freetable'', ``thumbnail'' etc.; and
you should provide the extension to use on the file, e.g. ``html'', ``txt'',
``gif'' etc.
</dd>
<dt>
<strong><a name="item_scrape_xml">$text = scrape_xml ($text, qr/start/, qr/end/ [, $keepstart, $keepend ]);</a></strong><br />
</dt>
<dd>
''Scrape'' a block of HTML or XML text. Given the text in <code>$text</code>, and
regular expressions in <code>qr/start/</code> and <code>qr/end/</code>, this function will remove
all HTML up to and including the start regexp, and all HTML including and
after the end regexp.
<p>
If <code>$keepstart</code> or <code>$keepend</code> is set to 1, then the text matched by that
regexp will be preserved, otherwise it will be stripped. The default values
are 0.
</p>
<p>
If the patterns match halfway through a HTML or XML tag, then the remainder of
that tag (until the trailing > character) will be stripped automatically.
</p>
<p>
If a regexp is specified as <code>undef</code>, then it will be ignored.
</p>
<p>
The resulting, scraped text is returned.
</p>
</dd>
<dt>
<strong><a name="item_scrape_out_xml">$text = scrape_out_xml ($text, qr/start/, qr/end/ [, $keepstart, $keepend ]);</a></strong><br />
</dt>
<dd>
The inverse of <a href="#item_scrape_xml"><code>scrape_xml()</code></a>, above.
<p>
Given the text in <code>$text</code>, and regular expressions in <code>qr/start/</code> and
<code>qr/end/</code>, this function will remove all HTML after, and including, the start
regexp, and all HTML up to and including the end regexp.
</p>
<p>
If <code>$keepstart</code> or <code>$keepend</code> is set to 1, then the text matched by that
regexp will be preserved, otherwise it will be stripped. The default values
are 0.
</p>
<p>
If the patterns match halfway through a HTML or XML tag, then the remainder of
that tag (until the trailing > character) will be stripped automatically.
</p>
<p>
The regexps cannot be specified as <code>undef</code>, as <a href="#item_scrape_xml"><code>scrape_xml()</code></a> should
be used for that case instead.
</p>
<p>
The resulting, scraped text is returned.
</p>
</dd>
</dl>
</td>
</tr>
</table>
</td>
</tr>
</table>
</td>
</tr>
</table>
<table width="100%">
<tr>
<td valign="top">
<strong><a href="http://webmake.taint.org/">WebMake</a>
Documentation</strong> (version 2.3)
</td>
<td valign="top">
<div align="right">
[ <a href="Main.pm.html">Back</a> | <a href="index_09-man.html">Forward</a> | <a href="index.html">Index</a>
| <a href="allinone.html">All In One</a> ]
</div>
</td>
</tr>
</table>
<div align="right">
<a href="http://webmake.taint.org/"> <img src="images/BuiltWithWebMake.png" alt="Built With WebMake" border="0" width="88" height="31" /></a>
</div>
</font>
</body>
</html>
