From 55000fd779816fa059e51e9fd01c7e6772b8efc7 Mon Sep 17 00:00:00 2001 From: intrigeri Date: Tue, 15 Jul 2008 12:35:12 +0200 Subject: pedigree: rewrote with different design (and updated testsuite + docs accordingly) Signed-off-by: intrigeri --- doc/plugins/pedigree.mdwn | 112 +++++++++++++++++----------------------------- 1 file changed, 40 insertions(+), 72 deletions(-) (limited to 'doc/plugins') diff --git a/doc/plugins/pedigree.mdwn b/doc/plugins/pedigree.mdwn index 41f70745c..15c032838 100644 --- a/doc/plugins/pedigree.mdwn +++ b/doc/plugins/pedigree.mdwn @@ -1,98 +1,74 @@ [[!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". +This plugin offers a `HTML::Template` loop that iterates over all or +a subset of a page's parents, providing a few bonus possibilities, +such as styling the parent links depending on their place in the path. +One can think of pedigree as "`PARENTLINKS` on steroids". [[!toc ]] Content ======= -Loop variables --------------- +This plugin provides one template loop, called `PEDIGREE`, that +returns the same parents list as `PARENTLINKS` would; as a bonus, +every path element returned by the `PEDIGREE` loop has the following +variables set: -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 +* `URL` (string): url to the current path element +* `PAGE` (string): title of the current path element +* `DEPTH` (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, + `DEPTH=0` +* `HEIGHT` (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. +* `DEPTH_n` (boolean): true if, and only if, `DEPTH==n` +* `HEIGHT_n` (boolean): true if, and only if, `HEIGHT==n` Usage ===== +The `DEPTH_n` and `HEIGHT_n` variables allow the template writer to +skip arbitrary elements in the parents list: they are arbitrary +page-range selectors. + +The `DEPTH` and `HEIGHT` variables allow the template writer to apply +general treatment, depending on one of these variables, to *every* +parent: they are counters. + 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`: +the path going from the wiki root to the current page; just add the +following lines in `page.tmpl`: - " class="parentdepth"> + " class="depth"> / -Then write the appropriate CSS bits for `a.parentdepth1`, etc. +Then write the appropriate CSS bits for `a.depth1`, etc. -Skip some parents, style the others depending on their distance ---------------------------------------------------------------- +Skip some parents, style the others depending on their distance to the current page +----------------------------------------------------------------------------------- -Say you want to display the parents links, skipping the wiki homepage, -styled depending on their distance from the current page; just add the +Say you want to display all the parents links but the wiki homepage, +styled depending on their distance to the current page; just add the following lines in `page.tmpl`: - - " class="parentdistance"> + + + + " class="height"> / -Then write the appropriate CSS bits for `a.parentdistance1`, etc. +Then write the appropriate CSS bits for `a.height1`, etc. Full-blown example ------------------ @@ -106,9 +82,9 @@ and/or CSS generated for some special path components; e.g.:
    - + - +
  • ">
    •  @@ -119,12 +95,12 @@ and/or CSS generated for some special path components; e.g.: - +
    ">
    - +
    ">
    @@ -135,11 +111,3 @@ and/or CSS generated for some special path components; e.g.:
- -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. -- cgit v1.2.3