Documentation for the Textpattern plugin smd_parent by Stef Dawson follows this short message from our sponsor ;-)

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 name attribute always overrides any catnum or global category (even if it’s a typo!)
Using catnum forces type to “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

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 frolic in the raw code halls, you’ll need to step into the view source page.

Legacy software

If, for some inexplicable reason, you need an ancient 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.

Who's your daddy?