move complex examples to a tip
authorJoey Hess <joey@kodama.kitenet.net>
Wed, 16 Jul 2008 21:43:57 +0000 (17:43 -0400)
committerJoey Hess <joey@kodama.kitenet.net>
Wed, 16 Jul 2008 21:43:57 +0000 (17:43 -0400)
doc/plugins/parentlinks.mdwn
doc/tips/parentlinks_style.mdwn [new file with mode: 0644]

index ff413939019745c128f4c72238e4e1c297cc5f8e..ef262a30c1230b1f04feeb77a4ee04ca14da50c5 100644 (file)
@@ -1,124 +1,5 @@
 [[!template id=plugin name=parentlinks core=1 author="[[intrigeri]]"]]
 [[!tag type/link]]
 
 [[!template id=plugin name=parentlinks core=1 author="[[intrigeri]]"]]
 [[!tag type/link]]
 
-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 ]]
-
-Content
-=======
-
-This 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_LOOP>
-
-Then write the appropriate CSS bits for `a.height1`, 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="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>
+This plugin generates the links to a page's parents that typically appear
+at the top of a wiki page.
diff --git a/doc/tips/parentlinks_style.mdwn b/doc/tips/parentlinks_style.mdwn
new file mode 100644 (file)
index 0000000..5294e54
--- /dev/null
@@ -0,0 +1,124 @@
+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 ]]
+
+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_LOOP>
+
+Then write the appropriate CSS bits for `a.height1`, etc.
+
+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>