NAME

WE_Frontend::Plugin::Navigation - utilities for navigation creation

SYNOPSIS

my $t = Template->new({PLUGIN_BASE => "WE_Frontend::Plugin"});

[% USE Navigation %]

DESCRIPTION

WE_Frontend::Plugin::Navigation is a Template-Toolkit plugin to make the creation of navigations based on objects in a WE::DB::Obj database easier. The WE_Frontend::Plugin::Navigation object corresponds somewhat to the WE::DB::Obj database. Most of the methods described below return WE_Frontend::Plugin::Navigation::Object objects, which correspond to WE::Obj objects.

METHODS

new

This method is normally not called directly, but only as part of the USE directive:

[% USE Navigation %]
[% USE n = Navigation %]

You can pass the named parameter objid to set the object id for this context.

[% USE n = Navigation(objid = 10) %]

Or you can use the name parameter:

[% USE n = Navigation(name = "rootcollection") %]

You can pass the named parameter objid to set the object id for this context.

When calling the process() method of Template-Toolkit the value for objdb (a reference to the WE::DB::Obj database) should be set or rootdb (a reference to the WE::DB database) XXX rootdb prefered if content access. Also, if objid is not set in the USE directive, it may be supplied to the process() method.

    my $t = Template->new(
        {PLUGIN_BASE => "WE_Frontend::Plugin"}
    );
    $t->process(
        \$template,
        {
         objdb      => $objdb,
	 rootdb     => $rootdb,
         objid      => $objid,
         config     => $c,
         langstring => \&WE::Util::LangString::langstring
        },
        \$output
    );

The return value of the USE Navigation directive (the n variable in the examples above) is a WE_Frontend::Plugin::Navigation::Object of the current object supplied with the objid key.

ancestors([[objid = id | name = name], fromlevel => level, tolevel => level, restrict = restrictmethod])

Return a list of ancestors of the current object. The oldest (top-most) ancestor is first in the list. If objid is given, then return the ancestors for the object with this object identifier. If fromlevel and/or tolevel are given, then restrict the ancestor list for these levels. The topmost level is numbered with 1. The root itself is numbered with 0, this can be used for a "home" link on top of the list. The list may be restricted by specifying restrict. If tolevel is less than fromlevel, then an empty list is returned.

parent([[objid = id | name = name]])

Return the parent of the current object, or of the object with id objid. Note that it is possible in the WE::DB::Obj database to have more than one parent, nevertheless only one parent is returned.

level([[objid = id | name = name]])

Return the level of the current object, or of the object with id objid. The root of the site has level = 0.

toplevel_children([sort = sortmethod, restrict = restrictmethod])

Return a list of sorted toplevel children. Normally, the sequence order is used but the sorting can be changed by specifying sort. The list may be restricted by specifying restrict.

siblings([[objid = id | name = name], level = level, sort = sortmethod, restrict => restrictmethod])

Get the siblings of the current object, or of the object with id objid. The siblings are sorted by the sortmethod in sort and can be restricted with restrict.

If level is specified, the siblings of the ancestor of the current object in the specified level are returned. The level can also be specified as a negative number; this means how many levels up from the current position should be used.

children([[objid = id | name = name], sort = sortmethod, restrict => restrictmethod])

Get the children of the current object, or of the object with id objid. The children are sorted by the sortmethod in sort and can be restricted with restrict.

siblings_or_children([...]);

Often, siblings are used if the object is a document and children are used if the object is a folder. This convenience method uses the appropriate method. The arguments are the same as in siblings or children.

restrict($params, $listref)

Internal method to restrict the passed array reference according to the <$params-{restrict}>> subroutine.

The value of the restrict parameter should be the name of a method in the WE_Frontend::Plugin::Navigation::Object class. The object is accepted if the returned value is true. Example for an user-defined method (although subclassing would be the cleaner solution):

package WE_Frontend::Plugin::Navigation::Object;
sub my_restrict {
    my $o = shift;
    # restrict to objects with Id less than 5
    $o->o->Id < 5;
}

sort($params, $listref)

Internal method to sort the passed array reference according to the <$params-{sort}>> subroutine.

The value of the sort parameter should be the name of a method in the WE_Frontend::Plugin::Navigation class. This method takes to arguments $a and $b, both WE_Frontend::Plugin::Navigation::Object objects which should be compared. The returned value should be -1, 0, or 1, just as in the sort function. Example for an user-defined method (although subclassing would be the cleaner solution):

package WE_Frontend::Plugin::Navigation;
sub my_sort {
    my($self, $a, $b) = @_;
    # sort by title
    WE::Util::LangString::langstring($a->o->Title) cmp WE::Util::LangString::langstring($b->o->Title);
}

current_object([[objid = id | name = name]])

Return the current active object as a WE::Obj object. See also the self method.

current_id([[objid = id | name = name]])

Return the current active id. The object is identified in this order:

objid in this method call

name in this method call

objid parameter in the Navigation USE directive

objid template variable (as specified in the Template->new call)

self([[objid = id | name = name]])

Return the current active object as a ...::Navigation::Object object.

get_object([[objid = id | name = name]])

This is an alias for self, but uses a more "logical" name if an object is retrieved by id or name.

is_self([$testobj | $testobjid], [[objid = id | name = name]])

Return true if the given $testobj (object) or $testobjid (id) is the current object. You can pass another objid instead of the current object. =cut

equals([$testobj | $testobjid], [objid = id | name = name])

The same as is_self, only that either objid or name are mandatory.

Example:

[% IF n.equals(testobjid, objid = otherobjid) %]

is_ancestor([$testobj | $testobjid], [objid => id])

Return true if the given $testobj (object) or $testobjid (id) is an ancestor of the current object. You can pass another objid instead of the current object. The current object is not considered an ancestor of itself.

object_by_name($name)

Return an object by $name.

Root

Return reference to root database.

ObjDB

Return reference to the object database.

Object

Return the class name for the navigation objects. This can be overridden in inherited classes.

MEMBERS

Remember that there is no visible distinction in the Template-Toolkit between accessing members and methods.

Context

The WEsiteinfo context.

ObjDB

A reference to the object database (WE::DB::Obj).

INTERNAL METHODS

objify_list($listref)

Internal method to create from a list of WE::Obj objects a list of Navigation objects (see the Object method). The passed parameter $listref will be changed.

objectify_params($obj_or_id, $obj_or_id, ...)

Turn the given arguments from an object id or WE::Obj object into an WE_Frontend::Plugin::Navigation::Object object.

idify_params($obj_or_id, ....)

Turn the given arguments from an object id or WE::Obj object into an object id.

INTERNALS

Some methods like ancestors or is_ancestor are implemented using WE::DB::Obj::pathobjects_with_cache. This means that the structure of the site should not change for a Navigation instance. This is normally not a problem. XXX see reset_cache

AUTHOR

Slaven Rezic - slaven@rezic.de

SEE ALSO