pedigree: added documentation (doc/plugins/pedigree.mdwn)
Signed-off-by: intrigeri <intrigeri@boum.org>master
intrigeri
parent
b391b5a80b
commit
cff4201eed
|
|
@ -0,0 +1,145 @@
|
|||
[[!template id=plugin name=pedigree author="intrigeri"]]
|
||||
[[!tag type/useful]]
|
||||
|
||||
This plugin provides a bunch of loops that one can use in his/her
|
||||
`HTML::Template`'s to iterate over all or a subset of a page's
|
||||
parents. One can think of pedigree as "`PARENTLINKS` on steroids".
|
||||
|
||||
[[!toc ]]
|
||||
|
||||
Content
|
||||
=======
|
||||
|
||||
Loop variables
|
||||
--------------
|
||||
|
||||
Inside any loop provided by the pedigree plugin, every path element
|
||||
has not only the `URL` and `PAGE` variables, as with `PARENTLINKS`,
|
||||
but also the following ones:
|
||||
|
||||
* `ABSDEPTH` (positive integer): depth of the path leading to the
|
||||
current path element, counting from the wiki's root, which has
|
||||
`ABSDEPTH=0`
|
||||
* `DISTANCE` (positive integer): distance, expressed in path elements,
|
||||
from the current page to the current path element; e.g. this is
|
||||
1 for the current page's mother, 2 for its grand-mother, etc.
|
||||
* `IS_ROOT` (boolean): true if, and only if, this path element is the
|
||||
wiki's root
|
||||
* `IS_SECOND_ANCESTOR` (boolean): true if, and only if, this path
|
||||
element is the first one after the wiki's root, on the path leading
|
||||
to the current page
|
||||
* `IS_GRAND_MOTHER` (boolean): true if, and only if, this path element
|
||||
is the current page's grand-mother
|
||||
* `IS_MOTHER` (boolean): true if, and only if, this path element
|
||||
is the current page's mother
|
||||
|
||||
Loops
|
||||
-----
|
||||
|
||||
### `PEDIGREE`
|
||||
|
||||
Returns the same parents list as `PARENTLINKS` would, along with
|
||||
additional loop variables as explained above.
|
||||
|
||||
### `PEDIGREE_BUT_ROOT`
|
||||
|
||||
Returns the same parents list as `PEDIGREE` would, **but** the wiki
|
||||
root (i.e. homepage).
|
||||
|
||||
In addition to pedigree's common loop variables, `PEDIGREE_BUT_ROOT`
|
||||
provides `RELDEPTH` (positive integer), whose value, for a given
|
||||
parent, is its relative depth, i.e. the depth of the path leading to
|
||||
it, counting from the first element returned by this loop.
|
||||
|
||||
### `PEDIGREE_BUT_TWO_OLDEST`
|
||||
|
||||
Returns the same parents list as `PEDIGREE` would, **but** the wiki
|
||||
root (i.e. homepage) and the next path component.
|
||||
|
||||
In addition to pedigree's common loop variables,
|
||||
`PEDIGREE_BUT_TWO_OLDEST` provides `RELDEPTH`: depth of the path
|
||||
leading to the current parent, relative to the first element returned
|
||||
by this loop.
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
Styling parents depending on their depth
|
||||
----------------------------------------
|
||||
|
||||
Say you want the parent links to be styled depending on their depth in
|
||||
the path leading to the current page; just add the following lines in
|
||||
`page.tmpl`:
|
||||
|
||||
<TMPL_LOOP NAME="PEDIGREE">
|
||||
<a href="<TMPL_VAR NAME="URL">" class="parentdepth<TMPL_VAR NAME="ABSDEPTH">">
|
||||
<TMPL_VAR NAME="PAGE">
|
||||
</a> /
|
||||
</TMPL_LOOP>
|
||||
|
||||
Then write the appropriate CSS bits for `a.parentdepth1`, etc.
|
||||
|
||||
Skip some parents, style the others depending on their distance
|
||||
---------------------------------------------------------------
|
||||
|
||||
Say you want to display the parents links, skipping the wiki homepage,
|
||||
styled depending on their distance from the current page; just add the
|
||||
following lines in `page.tmpl`:
|
||||
|
||||
<TMPL_LOOP NAME="PEDIGREE_BUT_ROOT">
|
||||
<a href="<TMPL_VAR NAME="URL">" class="parentdistance<TMPL_VAR NAME="DISTANCE">">
|
||||
<TMPL_VAR NAME="PAGE">
|
||||
</a> /
|
||||
</TMPL_LOOP>
|
||||
|
||||
Then write the appropriate CSS bits for `a.parentdistance1`, etc.
|
||||
|
||||
Full-blown example
|
||||
------------------
|
||||
|
||||
Let's have a look at a more complicated example; combining the boolean
|
||||
loop variables provided by this plugin (`IS_ROOT` and friends) and
|
||||
`HTML::Template` flow control structures, you can have custom HTML
|
||||
and/or CSS generated for some special path components; e.g.:
|
||||
|
||||
<!-- all parents, skipping mother and grand'ma, inside a common div+ul -->
|
||||
<div id="oldestparents">
|
||||
<ul>
|
||||
<TMPL_LOOP NAME="PEDIGREE">
|
||||
<TMPL_IF NAME="IS_GRAND_MOTHER">
|
||||
<TMPL_ELSE>
|
||||
<TMPL_IF NAME="IS_MOTHER">
|
||||
<TMPL_ELSE>
|
||||
<li><a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a></li>
|
||||
</TMPL_IF>
|
||||
</TMPL_IF>
|
||||
</TMPL_LOOP>
|
||||
</ul>
|
||||
</div>
|
||||
|
||||
<!-- dedicated div's for mother and grand'ma -->
|
||||
<TMPL_LOOP NAME="PEDIGREE">
|
||||
<TMPL_IF NAME="IS_GRAND_MOTHER">
|
||||
<div id="grandma">
|
||||
<a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
|
||||
</div>
|
||||
<TMPL_ELSE>
|
||||
<TMPL_IF NAME="IS_MOTHER">
|
||||
<div id="mother">
|
||||
<a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a>
|
||||
</div>
|
||||
</TMPL_IF>
|
||||
</TMPL_IF>
|
||||
</TMPL_LOOP>
|
||||
|
||||
<!-- eventually, the current page title -->
|
||||
<TMPL_VAR NAME="TITLE">
|
||||
</div>
|
||||
|
||||
Known bugs
|
||||
==========
|
||||
|
||||
If `PEDIGREE_BUT_ROOT` and `PEDIGREE_BUT_TWO_OLDEST` are used in the
|
||||
same `HTML::Template`, `RELDEPTH` has wrong values inside the
|
||||
`PEDIGREE_BUT_ROOT` loop. This can be fixed if anyone needs this to
|
||||
be working.
|
||||
Loading…
Reference in New Issue