Navigation portlet

From VYRE

Jump to: navigation, search
Navigation portlet
module: Publishing module
supplier: VYRE Ltd.


The purpose of the Navigation Portlet is to display the site page tree (a sitemap).

Navigation Portlet Configuration

Contents

Configuration Settings

  • Label Type setting allows the user to select the static text (Use custom label option) or the localization bundle resource (Use localized label option) to be used for portlet's label. For localized label, key must be provided; check Configuration / Localizations for available keys. If the localized key provided will be invalid, "??????" will be shown as a label.
  • Id for Anchor setting, if set, results a link with relevant anchor being printed in HTML.
    Anchor ID printed in HTML
  • XSL to be used for tree transformation setting allows to select an item from Files / XSL / Navigation Portlet. The default option is backwards-compatible with the old (pre 4.3.1) portlet behaviour in terms of produced HTML. Detailed XSL structure is explained below. This option uses shortcut functionality.
  • One of the Tree Root Page selection options allows to specify the tree root which will be processed later to show available site pages. In other words, no predcessors of the tree root page will be shown. Let's discuss each option in detail:
    • Current page is useful if tree should start from the current page. E.g. if the page is based on a template and template contains Navigator portlet instance, navigation tree would include pages starting from the current page, regardless which page is it. Term "current page" effectively means the page which is being shown in the browser at the moment.
    • Ancestor and its level is useful when tree must be shown starting from a certain (statically defined) level. Let's see an example below. If the current page is t111, ancestor on level 0 would be t1, same if current page would be t11 (ancestor always counts from the site root; first page being level 0). It does still work if ancestor level is the same as page level - for example, if current page is t11 and ancestor level = 1, resulting tree would include both t11 and t111. But, current page being t11 and ancestor level set to 2 would result an empty tree and relevant warning in the vyre.log. Generally: If the current page is lower than the Ancestor on level then no navigation tree will be displayed.
      Image:ancestor.png
    • The Choose option allows user to specifically select a tree node. Additionally, it allows site selection (by clicking on site) which is not possible using other (current page or ancestor) selections. Site selection is the only possibility to include all root level (or level 0) pages in the tree. All other options would include a page on level 0, but would not include its siblings.
    • The Enter Path (introduced in 4.6.3) works in a similar to the choose option. It allows you to a root page to be picked by the path that you enter. The path that is entered must reference a page that exists on the site that the portlet is on. There is no validation for this in the edit mode of the portlet. If the path is left empty, the current site will be used instead (in the same way as the current site is used when using the choose option and not picking a site/page).


  • ** Hide current page being checked would exclude current page from showing in the resulting tree. Otherwise, the page would be shown if other conditions (as per configuration) would allow showing it. NOTE: this setting overrides Start tree at level and End tree at level settings. If the checkbox is not ticked, decision (whether to print a node or not) is made by the start/end tree level options.
    • Show current pages children' setting forces showing children of a current page (pages that are deeper by only one level than current page. On the above example, t1s child would be only t11, but not t111). If the current page is not shown, this setting has no effect. NOTE: this setting overrides End tree at level settings if End tree at level setting is not 0. If the checkbox is not ticked, decision (whether to print a node or not) is made by the start/end tree level options.
  • The tree root selection (using the options above) results a sub-tree which can be evaluated further, and possibly be limited to it.s depth, if necessary. Let's see an example below. Let's assume our current page is unf-1186_home and it's our tree root (say, we selected tree root being current page). This effectively means that subsequent tree boundary settings would be related and only apply to the brown-bounded area.
Image:example_tree.png


  • ** Start tree at level setting allows to start visualising tree nodes from selected level. E.g. If the value would be 0, the tree would be printed having unf-1186_home node as a root. Similarly, if the start tree at level would be 2, our root would be page2. But start tree at level having value 1, would print the tree which contain page1 and page1_1 nodes as both them are at level 1. This setting is somewhat similar to tree root selector (as in setting above) in the sense it determines the start boundary of the tree, but is also different in the behaviour (as just noted - it does include siblings of a certain level). Default value for this setting is zero, which effectively prints the tree from the tree root (selected by the option above). NOTE: this setting is overriden by Hide current page only if Start page is the same as the current page.
    • End tree at level setting puts a limit on the tree depth (right boundary). E.g. if the current page is unf-1186_home, Start tree at level=0 and End tree at level is 1, it would only show nodes unf-1186_home, page1 and page1_1 as levels 0 and 1 are to be shown. Increasing this value would result deeper and deeper tree to be printed. Setting a zero (=infinitive) would result the entire tree (down to page6 and further) to be printed, regardless of its depth. NOTE: this setting is overriden by Hide current page and Show current pages children.
    • Tracer depth is a special parameter which allows printing of nodes when the current page is located deep down in a hierarchy and end tree at level isn't going that deep. Let's look at the table below for examples:
Tree root Current page
Tree start level Tree end level Tracer depth Result Comment
unf-1186_home page6 0 (=unf-1186_home) 2 (=page2) 1

Image:tracer1.png

We are showing tree with levels 0 and 1, and tracer has no effect (because tracer is less than tree end level)
unf-1186_home page6 0 (=unf-1186_home)
2 (=page2)
3

Image:tracer2.png

No changes here except that tracer is deeper and overrides tree end level. This results deeper tree being printed.
unf-1186_home
page6 1 (=page1) 2 (=page2) 0

Image:tracer3.png

In this example, tracer being zero resulted deep tree to be printed. However, it did not print children of page6 (tracer only advances to ancestors but not predecessors of current page). Notice that we increased start tree level, which resulted unf-1186_home to be skipped.

  • Show hidden pages setting includes hidden pages being printed in the result tree; otherwise they're skipped.

More Examples

Current page

Tree root

Tree start level

Tree end level

Tracer depth

Hide current page

Show current pages children

Result

Comment

page6

Unf-1186_home

0 (=same as root)

2

0 (=infinitive)

No

Yes

NavPortlet1

In this example, tracer being zero resulted deep tree to be printed. Please note that the tracer only advances to ancestors and not predecessors.However it did also print child of page6 (which in this case is page7) as ‘Show current pages children' option was selected.

page6

Unf-1186_home

0 (=same as root)

2

0 (=infinitive)

Yes

Yes

NavPortlet2

Same example as above apart from this time ‘Hide current page option was selected. This option will automatically override ‘Show current pages children option, which has no effect in this case.

Show Hidden Pages

The checkbox allows you to include hidden pages in the navigation. By default they remain hidden.

XML structure

Since version 4.3.1, the portlet has been modified to generate XML which is being fed to default XSLT template that generates the HTML. It is possible to write and supply custom XSLT so that desirable HTML would be generated. Let's look at the XML below:

Image:xml.png

This XML is an actual output of the portlet which is later fed to the XSLT. This, and other XMLs are generated using the following rules:

  • opening and closing tag is portlet_output and tree (latter being a sub-tag of portlet_output);
  • tree can contain many nested page tags; page can contain other nested page tags as well.
  • page can contain:
    • name (comes from page properties screen);
    • current_page_ancestor (tag with no value). Will be generated if this page is an ancestor of the current page;
    • current_page (tag with no value). Will be generated if this page is the current page;
    • href, contains relative link to the page;
    • hreftitle, names the title to be printed over the link as a tip;
    • another page if there are any nested children.

XML schema is available if necessary.

What does the default XSL do? It wraps each list of pages into unordered lists (ul in HTML), presenting each item as list item (li in HTML). It also encloses each page with hrefs (that are presented in XML) and titles for href. If a page is nested, relevant nested unordered list (ul) is created. It also adds relevant CSS classes if a page is current page's ancestor, current page, also the level the page's at.

See also

Personal tools