Documentation for the Textpattern plugin smd_parent by Stef Dawson follows this short message from our sponsor ;-)
If you like my code and find it useful, feel free to show your appreciation with something from my UK Amazon wish list (or US) or donate to the Stef Dawson community coding pot, either via paypal.me/stefdawson or by following the Donate button below to PayPal. Thanks!
smd_parent
An extension of <txp:category /> that allows any parent element to be retrieved. Works with all article, link, image and file category types, takes exactly the same arguments as the conventional category tag plus the following attributes.
level
The parent level to return. Defaults to “1” (i.e. the “topmost level”). Any integer returns that particular parent level; a negative number specifies an offset “back up the tree” from the current category
catnum
By default the plugin always chooses the global category (?c) unless you override it with the name attribute. If you use a 1 or a 2 for the catnum option you tell the plugin to use the category1 or category2 value instead
Notes
- Using the
nameattribute always overrides any catnum or global category (even if it’s a typo!) - Using
catnumforcestypeto “article” for obvious reasons and also forces the tag to be used in an article context. You will get a tag warning if this condition is not met, exactly as with<txp:category1 />or<txp:category2 /> - If at any time the parent level “falls off” the tree you will get nothing back
- If you tell the plugin to return the current category you will also get nothing back (use
<txp:category />for that!)
All other attributes class, link, title, wraptag, name, section, this_section, and type are honoured exactly as they are in <txp:category />.
Author
Stef Dawson. Written for TXP user Kjeld Duits and given to the community.
Installation / Uninstallation
Download the plugin from either textpattern.org, or the software page, paste the code into the TXP Admin -> Plugins pane, install and enable the plugin.
Examples
All examples use the following category structure (level numbers are in parentheses):
- (1) animal
- (2) mammal
- (3) tiger
- (3) lion
- (3) human
- (4) male
- (4) female
- (3) zebra
- (2) reptile
- (3) crocodile
- (3) alligator
- (2) mammal
Example 1
The following table shows the result of various tag attributes when you are in the global category “zebra”:
| Tag | Returns | Explanation |
|---|---|---|
<txp:smd_parent /> |
animal | Default is top level (1) |
<txp:smd_parent level="2" /> |
mammal | Retrieves level 2 category in this branch |
<txp:smd_parent level="-1" /> |
mammal | Traverses one level “up” from where we are |
<txp:smd_parent level="42" /> |
The name of a 1980s pop group, not a valid category level :-) |
Example 2
When you are in an article with a category1 of “zebra” and a global category of “female”, the following table shows the result of various tag attributes:
| Tag | Returns | Explanation |
|---|---|---|
<txp:smd_parent level="-1" catnum="1" /> |
mammal | One level up the tree |
<txp:smd_parent level="-3" /> |
animal | Three levels up the tree; omitting catnum uses the global category instead |
<txp:smd_parent name="crocodile" level="2" catnum="1" /> |
reptile | Returns level 2; the name attribute overrides all categories |
Changelog
- 15 Jan 08 | v0.1 | Initial release
Source code
If you’d rather wander aimlessly through thousands of lines of PHP source code, you’ll need to step into the view source page.
Legacy software
If, for some inexplicable reason, you need the un-current version of a plugin, it can probably be found on the plugin archive page.
Experimental software
If you’re feeling brave, or fancy skateboarding into volcanos, you can test out some of my beta code. It can be found on the plugin beta page.
