NAME

Apache::Wyrd::Site::TagPull.pm - Display a list of Pages by subject

SYNOPSIS

  <BASENAME::TagPull search="newsletter AND current">
    <BASENAME::Template name="list"><table>$:items</table></BASENAME::Template>
    <BASENAME::Template name="item">
      <tr><td><a href="$:name">$:title</a>?:published{, posted: $:published}
      ?:description{<BR>&#151$:description}</td></tr>
    </BASENAME::Template>
    <BASENAME::Template name="selected">
      <tr><td><b>$:title?:published{, posted: $:published}</b>
      ?:description{<BR>&#151;$:description}</td></tr>
    </BASENAME::Template>
  </BASENAME::TagPull>

DESCRIPTION

TagPulls operate on the Page attribute "tags" which is a map attribute of the Index object. Given a search string of these tags, the Index is queried for documents which have those tags as items in their "tags" attribute. The list is returned following the format defined by the TagPull's templates: list, item, and selected.

Note, however, that like Apache::Wyrd::Site::Pull's "eventdate" attribute, the "tags" attribute is optional and must be defined as a map of the index itself. (See Apache::Wyrd::Site::Index for more details of these optional attributes.)

Each of these templates represents a component of the HTML that is expressed. All of them follow the Apache::Wyrd::Interfaces::Setter-style conventions for placemarkers and conditional expressions:

list

"list" is the HTML which bounds the list itself: in one of the list tags, it represents the list tags themselves (e.g. <UL>...</UL>). Where the items of the list are to appear, the placemarker $:items should appear.

item

"item" is the HTML which represents an individual page. Whatever attributes of the Page you want to display in the list need to be given in placemarkers of this template.

selected

Identical to "item", but used only if the document in the TagPull list is the document on which it appears. This template is kept separate from the item template to allow the document to be treated differently on the page on which it appears, for example, not at all, or unlinked, so that it is clear it can't be navigated to. (Not normally used, see "metoo" flag, below.)

Another feature of a TagPull is that if it encloses any HTML with Setter-style placemarkers, it will assume that it should treat that text as a template for the HTML enclosing the list, and replace the $:list placemarker with the complete list itself.

One more feature of TagPulls is that they will change the private attribute "_pull_results" of the enclosing Wyrd to an integer representing how many of the results were found. What the parent Wyrd does with this data is not determined by the TagPull.

HTML ATTRIBUTES

search

The search string in conventional logical format. Other than quotes, which provide no meaning in tokenized search expressions, either the +/- or the formal AND, OR, NOT, DIFF modifiers may be used to express the set of tagged pages which are to be displayed. Parentheses may also be used.

sort

Sort the list by the attributes indicated in this token list. Sorting is done in precedence given by these tokens from left to right, for example "title, published, isbn" is by title first, then by date, then by ISBN. These items must, of course, be attributes of the Page Wyrds that are indexed.

Sorting is done in alphabetical order when comparing non-numerical strings, ascending order when comparing numbers, and in reverse chronology when searching by one of the attributes designated in the site's implementation of Apache::Wyrd::Site::Pull::_date_fields().

before

Item publication date must be before the date (given in YYYYMMDD format)

after

Item publication date must be before the date (given in YYYYMMDD format)

eventdate

See Apache::Wyrd::Site::Pull.

limit

Limit of how many documents to present. Can be a single digit for how many from the top to present, two digits separated by a comma for a range from the top, or a comma to the left or right of a digit to represent a range from the top up to an item or from the item to the end of the series, respectively. This limit is appled after all other filters.

attribute

attribute description

FLAGS

autohide

Instruct the TagPull not to display at all if the TagPull has no results. Otherwise, an empty list is presented.

metoo

Cause the page the TagPull occurs on to appear in the pull, which is not the default behavior.

PERL METHODS

(format: (returns) name (arguments after self))

(void) _set_defaults (void)

This method provides the default templates for the list, item, selected, and header templates.

BUGS/CAVEATS

Reserves the _format_output method.

AUTHOR

Barry King <wyrd@nospam.wyrdwright.com>

SEE ALSO

Apache::Wyrd

General-purpose HTML-embeddable perl object

Apache::Wyrd::Site::Pull

Abstract document-list Wyrd

LICENSE

Copyright 2002-2007 Wyrdwright, Inc. and licensed under the GNU GPL.

See LICENSE under the documentation for Apache::Wyrd.