Help > Documentation > 5. Page creation > Page models >

Managing navigation links: atm-linx tags

The principle of links between Automne pages

The pages of sites managed by Automne create a tree. Like all websites it is possible to create links between the different pages in this tree.

Automne allows you to define rules for automatically creating links between pages according to their position in the tree.

You may, for example, want a given area of a page to include links to all the sub pages of the current page. You may also want to have the path (the Ariadne's thread) between any two given points in the tree, such as between the welcome page and the current page in order to to create a navigation history.

Perhaps you would simply like to have a link to a page: for example the welcome page or any other page, no matter where it is in the tree.

These are merely a few examples of the possiblities offered for creating links between different pages in the tree.

Another essential point is the maintenance of these links over time. Automne dynamically manages the different links found on Automne pages. For example, if a page is deleted, all the links pointing to this page will be automatically deleted on all the pages of the tree. This eliminates the problem of "broken links".

In the same way, if an area displays links to all the sub pages of a given page and if a new page is created in its place, it will automatically be added to the existing list of links.

To do this, you must employ XML markers in your page models or in your content rows specifically describing the type of link you want to make. These markers are the atm-linx tags.

The atm-linx tags create 'internal' links on the site. These links generate navigation links from one page to another. They will follow the tree schema you define for your site.

Format of atm-linx tags:

Notation convention: in the following source codes, the code between brackets [] is optional.

<atm-linx type="linxtype"> <selection>...</selection> [<selection>...</selection>] <display>...</display> [<display>...</display>] [<noselection>...</noselection>] </atm-linx>

Linxtype where the value of the attribute type may be one of the following:

"direct": direct link to one or more pages.
"sublinks": link to sub-pages of a page.
"desclinks": "descendant" links from the root to the current page. Parameters permit fixing the depart and arrival pages.
"recursivelinks" : "recursive" links display a complete page tree.

The content of an atm-linx tag is separated into three distinct zones:

The <selection> tag(s) select the target pages of the links to be created.
The <display> tag(s) specify how to display the targeted pages.
The optional <noselection> tag specifies a display in the case where no pages were found by the <selection> tag(s).

The sub-links and decendant links do not go outside of websites. On the other hand, direct links do not have this restriction.

1. Format of 'selection' tags.

The selection tag defines the target pages of the link. It can contain a declaration of conditions, in the case where target pages must meet certain conditions before being selected.

The format of 'selection' tags:

<selection [noerror="1"] [crosswebsite="1"]> [<condition>...</condition>] <start>'nodespec declaration'[, 'nodespec declaration' ...]</start> [<start>'nodespec declaration'[, 'nodespec declaration' ...]</start>] [<stop>'nodespec declaration'</stop>] </selection>

Selecting target pages has three steps:

The departure point(s), represented by a start tag.
The destination target in the form of a path description ("desclinks" link), represented by a stop tag.
Some conditions (optional) represented by the condition tag.

The optional attributes of the selection tag:

noerror: Eliminates error messages when a non-existant page is created. Values accepted: 0, 1, true, false (default).
crosswebsite: By default, a link cannot target a page belonging to another site managed by Automne. This attribute can go beyond this limitation. Values accepted: 0, 1, true, false (default).

This table describes the number of start and stop tags possible according to the type of atm-linx tag:

LINKTYPE	START	STOP
direct	1+
sublinks	1
desclinks	1	1
recursivelinks	1

2. Format of 'nodespec declaration'.

The nodespec are the specifications of targeted pages. They can refer to a page by its reference or by its position in relation to the current page (the page where the link is found) or the root.

The format:

<nodespec type="NODESPECTYPE" value="NODESPECVALUE" [reloffset="OFFSET"] />

A table summarizing the possible values of attributes:

NODESPECTYPE	NODESPECVALUE	OFFSET
node	Identifer of the target page. Example: 23	N/A
relative	self: indicates the current page	N/A
	brother: indicates the page with same father as the current page	1: right brother -1: left brother
	father: un ancestor of the current page	1: father 2: grandfather
	root: the site root	0: root 1: the son of the root on the branch leading to the current page 2: grandson ...

ATTENTION: By "site root" we mean the root closest to the parent site!

3. Format of 'noselection declaration'

noselection declares an alernate display in the case where the 'selection' tag does not target any page. It is optional.

The format:

<noselection>Valid XHTML code</noselection>

4. Format of 'display declaration'.

The display is the HTML specification which will replace the linx tag for all the targeted pages defined in the declaration selection. A display can have many conditions and there can be many displays in the atm-linx tag. In this case, for each target, one can look at the displays in their order of appearance in the tag; if the target meets all the conditions, this display will be adopted. If no display is sufficient, the target is rejected. If a display has no conditions, the default display is called up. It is useless to put many displays without conditions, as those following the first will be ignored.

The format:

<display> [<condition>...</condition>] <htmltemplate> Valid XHTM code </htmltemplate> [<subleveltemplate> Valid XHTML code </subleveltemplate>] </display>

Tag <htmltemplate>: it has the XHTML code which generates the links for selected pages.

In the <htmltemplate> tag, the following special values can appear:

"{{href}}": will be replaced by the absolute URL of the target.
"{{title}}": will be replaced by the "link title" field of the target.
"{{jstitle}}": same as the preceding tag, but the single and double quotes will be freed in order to include them in the javascript or the attributes of the XHTML tags.
"{{pagetitle}}": Title of the page.
"{{jspagetitle}}": Title of the page, but the single and double quotes will be freed in order to include them in the javascript or the attributes of the XHTML tags.
"{{desc}}": Description of the page.
"{{id}}": Displays the unique identifier of the target page.
{{currentClass}}: Displays the CMS_current if the current target is the same as the current page. This information can be useful for post treatment of CSS or javascript.
id="{{currentID}}": Displays the id="CMS_current" if the current target is the same as the current page. This information can be useful for post treatment of CSS or javascript.
"{{number}}": Uniquely for sublink type links. Displays the number of account links. This information can be useful for post treatment of CSS or javascript.
"{{modulo}}": Uniquely for sublink type links. Displays alternately 0 or 1 for each page. This information can be useful for post treatment of CSS or javascript.
{{isParent}}: Displays the CMS_parent if the current target is a parent of the current page. This information can be useful for post treatment of CSS or javascript.
id="{{isParent}}": Affiche id="CMS_parent" if the current target is a parent of the current page. This information can be useful for post treatment of CSS or javascript.
class="{{isParent}}": Uniquely for sublink type links. Displays class="CMS_parent" if the current target is a parent of the current page. This information can be useful for post treatment of CSS or javascript.

The optional <subleveltemplate> tag defines an optional frame for the content of the htmltemplate tag for every type of link. It contains an XHTML code zone in which the {{sublevel}} value must be defined or the code produced by the <htmltemplate> placed.

Specificity of recursivelinks tags:

The syntax of the display tag for 'recursivelinks' type links has some nuances compared with other tags:

<display [mode="MODE" root="ROOT"]> [<condition>...</condition>] <htmltemplate> Valid XHTML code </htmltemplate> <subleveltemplate> Valid XHTML code </subleveltemplate> [<mode>MODE</mode>] [<root>ROOT</root>] </display>

In addition to the special values of other tags, the <htmltemplate> tag has these supplementary values:

"{{lvlClass}}": Uniquely for recursivelinks type links. Displays CMS_lvln. being the current level of recursivity (number). This information can be useful for post treatment of CSS or javascript..
"{{typeClass}}": Uniquely for recursivelinks type links. Displays CMS_sub if the current target has sublevels, CMS_nosub if the target does not have sublevels, or CMS_open if the current target has sub levels and these levels are displayed (uniquely in close mode). This information can be useful for post treatment of CSS or javascript..
"{{sublevel}}": Uniquely for recursivelinks type links. Position of the recursive zone. It is in this place the supplementary level of recursivity (depth) will be displayed if it exists.

The optional <subleveltemplate> tag defines an optional frame for the level of recursivity. It contains an XHTML code zone in which the {{sublevel}} value must be defined or the following level of recursivity (depth) must be placed. This HTML area can also contain the {{lvlClass}} value which will be replaced, in the same manner as the <htmltemplate> tag, by the current level of recursivity.

The optional <mode> tag defines the display mode of a recursivelinks tag. It is only useful for this kind of tag. <mode> accepts two values: open or close. A tag having the open value displays the entire tree. A closed tag will only display the tree area necessary to locate the current page..

From version 4.0.0rc2: the <mode> can be replaced by a mode attribute on the <display> tag. This attribute also accepts the open or close values.
It is also possible to add a tag or an <root> attribut which displays (or not) the first level of recursivity. This tag (or attribute) accepts the values 0 or 1 to activate or not the display of the first level of recursivity.

4. Format of 'condition declaration'.

The condition defines a rule to verify a target it it wants to meet a condition. It contains a value tag that will determine the value which will serve as a comparison with the other value of a tested target.

The format:

<condition property="PROPERTY" operator="OPERATOR">

    <value type="VALUETYPE" [property="VALUEPROPERTY"]>VALUEDATA</value>

</condition>

Where, in a simplified fashion:

PROPERTY: can contain the following values: rank, title, id, lvl, father
OPERATOR: can contain the following values: ==, !=, >, <, >=, <=, %2==

IMPORTANT: These characters must be coded in HTML to avoid any parsing problems (the character < becomes &It; the character > becomes &gt).

VALUETYPE: can contain the following valuespeut contenir les valeurs suivantes : data, nodeproperty
VALUEPROPERTY: can contain the following values: rank, title, id
VALUEDATA: can contain the following values: valeur scalaire ou tag nodespec

Where, more detailed:

PROPERTY is a property of the target which will serve for the test, or "rank" of the target (order number) in the target table. The properties allowed are restricted: title or id for the title or the reference of the target, "rank" for its rank (position relative to its brothers or sisters), "lvel" for its level of recursivity (depth) uniquely for recursivelinks.
OPERATOR is a simple comparison operator: ("==", ">=", ...) or composed: "%2==". There is no limit to composed operators, except that they must be binary.
VALUETYPE defines the type of value which will serve as the comparison. It can have these values: data or nodeproperty; the first will determine if the value between the starting tag and the end of the tag value is an unchanged scalar value. The second will determine if it is a value worth taking a nodespec.
VALUEPROPERTY is optional, defining the properties that one must extract from nodespec that will follow in order to serve as a value.
VALUEDATA defines the value (in the case where VALUETYPE="data") or the nodespec from which will be extracted the propoerty in order to define one of two values of the comparison.

5. Some examples of links created with atm-linx tags:

Direct link:

<atm-linx type="direct"> <selection> <start><nodespec type="node" value="23" /></start> </selection> <display> <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate> </display> </atm-linx>

This is the most simple tag; it will be replaced by a link to page 23 (if it exists); which will create the following XHTML code:

<a href="url_23">Page title</a>

Sublinks link:

<atm-linx type="sublinks"> <selection> <start><nodespec type="relative" value="self" /></start> </selection> <display> <htmltemplate><li><a href="{{href}}">{{title}}</a></li></htmltemplate> <subleveltemplate><ul>{{sublevel}}</ul></subleveltemplate> </display> </atm-linx>

Again, this tag is very simple, it will be replaced by a list of links to all the subpages (if there are any) of the current page This creates the following XHTML code:

<ul> <li><a href="url_fils1">Title subpage 1</a></li> <li><a href="url_fils2">Title subpage 2</a></li> </ul>

Simple desclinks link:

<atm-linx type="desclinks"> <selection> <start><nodespec type="relative" value="root" /></start> <stop><nodespec type="relative" value="self" /></stop> </selection> <display> <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate> </display> </atm-linx>Here is a simple example of a desclinks link. It creates a list of links going to the welcome page (root); for this the current page will create the following XHTML code:

<a href="url_home">Home page title</a><a href="url_page_bellow_home">Title of the page bellow the home page</a><a href="current_url">Current page title</a>

Complex desclinks link:

<atm-linx type="desclinks"> <selection> <start><nodespec type="relative" value="root" /></start> <stop><nodespec type="relative" value="self" /></stop> </selection> <display> <condition property="id" operator="!="> <value type="nodeproperty" property="id"><nodespec type="relative" value="self" /></value> </condition> <htmltemplate><a href="{{href}}" title="{{jstitle}}">{{title}}</a> ></htmltemplate> </display> <display> <condition property="id" operator="=="> <value type="nodeproperty" property="id"><nodespec type="relative" value="self" /></value> </condition> <htmltemplate>{{title}}</htmltemplate> </display> </atm-linx>

This example is a little more complex because it has certain conditions. It cannot link to the current page, which is useless as this is the page where we already are! It will add chevrons between each link to clearly separate the navigation path. This generates the following XHTML code:

<a href="url_home">Home page Title</a> ><a href="url_page_bellow home">Title of the page bellow the home</a> >Titre page actuelle

"Open" recursivelinks link:

<atm-linx type="recursivelinks"> <selection> <start><nodespec type="relative" value="root" /></start> <condition property="lvl" operator="<="> <value type="data">3</value> </condition> </selection> <display> <mode>open</mode> <htmltemplate><li class="{{lvlClass}} {{typeClass}} {{currentClass}}"><a class="{{lvlClass}}" href="{{href}}">{{title}}</a>{{sublevel}}</li></htmltemplate> <subleveltemplate><ul class="{{lvlClass}}">{{sublevel}}</ul></subleveltemplate> </display> </atm-linx>

This link generates an embedded, bulleted list describing the entire tree under the welcome page (root) until the third level maximum.
This generates the following XHTML code:

<ul class="CMS_lvl1"> <li class="CMS_lvl1 CMS_sub "> <a class="CMS_lvl1" href="url_accueil">Titre page Accueil</a> <ul class="CMS_lvl2"> <li class="CMS_lvl2 CMS_nosub "> <a class="CMS_lvl2" href="url_sous_page1">Titre sous page 1</a> </li> <li class="CMS_lvl2 CMS_sub "> <a class="CMS_lvl2" href="url_sous_page2">Titre sous page 2</a> <ul class="CMS_lvl3"> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-1">Titre sous page 2 - 1</a></li> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-2">Titre sous page 2 - 2</a></li> <li class="CMS_lvl3 CMS_nosub CMS_current"><a class="CMS_lvl3" href="url_page_actuelle">Titre page actuelle</a></li> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-4">Titre sous page 2 - 4</a></li> </ul> </li> <li class="CMS_lvl2 CMS_sub "> <a class="CMS_lvl2" href="url_sous_page3">Titre sous page 3</a> <ul class="CMS_lvl3"> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page3-1">Titre sous page 3 - 1</a></li> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page3-2">Titre sous page 3 - 2</a></li> </ul> </li> </ul> </li> </ul>

You will note the presence of classes which allow you to know what the current page is (CMS_current), twhat the different levels are (CMS_lvln) and if each of the pages has subpages (CMS_sub ou CMS_nosub). All these classes allow you to add style sheets as well as the necessary javascripts.

"Closed" recursivelinks link:

<atm-linx type="recursivelinks"> <selection> <start><nodespec type="relative" value="root" /></start> <condition property="lvl" operator="<="> <value type="data">3</value> </condition> </selection> <display> <mode>close</mode> <htmltemplate><li class="{{lvlClass}} {{typeClass}} {{currentClass}}"><a class="{{lvlClass}}" href="{{href}}">{{title}}</a>{{sublevel}}</li></htmltemplate> <subleveltemplate><ul class="{{lvlClass}}">{{sublevel}}</ul></subleveltemplate> </display> </atm-linx>

The only difference from the preceding example is found in the <mode> tag which in this case specifies that he links tree must be "closed."

This generates the following XHTML code:

<ul class="CMS_lvl1"> <li class="CMS_lvl1 CMS_sub "> <a class="CMS_lvl1" href="url_accueil">Titre page Accueil</a> <ul class="CMS_lvl2"> <li class="CMS_lvl2 CMS_nosub "><a class="CMS_lvl2" href="url_sous_page1">Titre sous page 1</a></li> <li class="CMS_lvl2 CMS_sub "> <a class="CMS_lvl2" href="url_sous_page2">Titre sous page 2</a> <ul class="CMS_lvl3"> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-1">Titre sous page 2 - 1</a></li> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-2">Titre sous page 2 - 2</a></li> <li class="CMS_lvl3 CMS_nosub CMS_current"><a class="CMS_lvl3" href="url_page_actuelle">Titre page actuelle</a></li> <li class="CMS_lvl3 CMS_nosub "><a class="CMS_lvl3" href="url_sous_page2-4">Titre sous page 2 - 4</a></li> </ul> </li> <li class="CMS_lvl2 CMS_sub "><a class="CMS_lvl2" href="url_sous_page3">Titre sous page 3</a></li> </ul> </li> </ul>

The only difference is in the display of subpages of subpage 3 which in this case are not visible because they are not found in a direct branch of the current page.

Multiple and conditional link:

<atm-linx type="direct"> <selection> <start><nodespec type="relative" value="self" /></start> <start><nodespec type="node" value="12" /></start> <start><nodespec type="node" value="15" /></start> </selection> <display> <condition property="title" operator=">="> <value type="data">C</value> </condition> <htmltemplate><a href="{{href}}">{{title}}</a></htmltemplate> </display> </atm-linx>

This code creates links to pages 12, 15 and the current page. Only, however, if they have a title which begins with the letter C or more on the ASCII scale.

There will be many other possible examples to add in order to describe the many possibilities offered by the atm-linx tag. Do not hesitate to consult those already existing in the demo suplied with Automne or to pose your questions in the forum.

Top