diff options
Diffstat (limited to 'doc/tips/parentlinks_style.mdwn')
| -rw-r--r-- | doc/tips/parentlinks_style.mdwn | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/doc/tips/parentlinks_style.mdwn b/doc/tips/parentlinks_style.mdwn new file mode 100644 index 000000000..f9dfa8f55 --- /dev/null +++ b/doc/tips/parentlinks_style.mdwn @@ -0,0 +1,143 @@ +Here are some tips for ways to style the links +provided by the [[plugins/parentlinks]] plugin. + +This plugin offers a `HTML::Template` loop that iterates over all or +a subset of a page's parents. It also provides a few bonus +possibilities, such as styling the parent links depending on their +place in the path. + +[[!toc levels=2]] + +Content +======= + +The plugin provides one template loop, called `PARENTLINKS`, that +returns the list of parent pages for the current page. Every returned +path element has the following variables set: + +* `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 + `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. +* `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. + +Basic usage +----------- + +As in the default `page.tmpl`, one can simply display the list of +parent pages: + + <TMPL_LOOP NAME="PARENTLINKS"> + <a href="<TMPL_VAR NAME=URL>"><TMPL_VAR NAME=PAGE></a>/ + </TMPL_LOOP> + <TMPL_VAR TITLE> + + +Styling parents depending on their depth +---------------------------------------- + +Say you want the parent links to be styled depending on their depth in +the path going from the wiki root to the current page; just add the +following lines in `page.tmpl`: + + <TMPL_LOOP NAME="PARENTLINKS"> + <a href="<TMPL_VAR NAME="URL">" class="depth<TMPL_VAR NAME="DEPTH">"> + <TMPL_VAR NAME="PAGE"> + </a> / + </TMPL_LOOP> + +Then write the appropriate CSS bits for `a.depth1`, etc. + +Skip some parents, style the others depending on their distance to the current page +----------------------------------------------------------------------------------- + +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`: + + <TMPL_LOOP NAME="PARENTLINKS"> + <TMPL_IF NAME="DEPTH_0"> + <TMPL_ELSE> + <a href="<TMPL_VAR NAME="URL">" class="height<TMPL_VAR NAME="HEIGHT">"> + <TMPL_VAR NAME="PAGE"> + </a> / + </TMPL_IF> + </TMPL_LOOP> + +Then write the appropriate CSS bits for `a.height1`, etc. + +Avoid showing title of toplevel index page +------------------------------------------ + +If you don't like having "index" appear on the top page of the wiki, +but you do want to see the name of the page otherwise, you can use a +special `HAS_PARENTLINKS` template variable that the plugin provides. +It is true for every page *except* the toplevel index. + +Here is an example of using it to hide the title of the toplevel index +page: + + <TMPL_LOOP NAME="PARENTLINKS"> + <a href="<TMPL_VAR NAME=URL>"><TMPL_VAR NAME=PAGE></a>/ + </TMPL_LOOP> + <TMPL_IF HAS_PARENTLINKS> + <TMPL_VAR TITLE> + </TMPL_IF> + +Full-blown example +------------------ + +Let's have a look at a more complicated example; combining the boolean +loop variables provided by the 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="PARENTLINKS"> + <TMPL_IF NAME="HEIGHT_2"> + <TMPL_ELSE> + <TMPL_IF NAME="HEIGHT_1"> + <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="PARENTLINKS"> + <TMPL_IF NAME="HEIGHT_2"> + <div id="grandma"> + <a href="<TMPL_VAR NAME="URL">"><TMPL_VAR NAME="PAGE"></a> + </div> + <TMPL_ELSE> + <TMPL_IF NAME="HEIGHT_1"> + <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> |