Hg

Summary: Produce Hierarchical groups like effects on your site

Version: 2007-03-07

Prerequisites: None

Status: Stable

Maintainer: (unsupported since 2008)

More Info: See Hierarchical Groups

Discussion: Hg-Talk

Questions answered by this recipe

Q. How can I get hierarchical groups like effects on my site?

A. Download hg.php Δ, and enable it in your config file.

include_once('cookbook/hg.php');

While the recipe is no longer supported by its author, and was not published with a license allowing modification and redistribution, another user has provided diffs for an update for PHP 7.2. See mailing list discussion.

Description

This recipe makes groups hierarchical in the sense properties in group Kingdom will be used for groups Kingdom-Animal and Kingdom-Animal-Canine, unless overwritten at a lower level. This effect works for the following six areas:

group headers
group footers
group sidebars
group attributes
config files
styles sheets

Hg also allows for easy, customizable bread crumbs, group titles, link shortcuts, subgroup/subname page variables link prefixing (for virtual wikis), and built in optional cleanurls.

How Hg Works

Let's use the common Kingdom-Animal-Canine example. Suppose you have a group called Kingdom, another group called Kingdom-Animal, another called Kingdom-Animal-Canine, and another called Kingdom-Plant.

Headers/Footers/Attributes

Group headers, group footers and group attributes pages will be searched for from the specific to the general. The first page found will be the one that is used.

For example, if Kingdom-Animal-Canine.GroupHeader and Kingdom.GroupHeader exist, then if one is in the Kingdom-Animal-Canine group, then Kingdom-Animal-Canine.GroupHeader will be used, but if one is in the Kingdom-Plant group then Kingdom.GroupHeader will be used. Likewise for GroupFooter and GroupAttributes.

Local Config files

Configuration files are also searched for from the specific to the general, and, again, the first one found will be the one used.

Suppose local/Kingdom.php and local/Kingdom-Animal-Canine.php exist. When on the Kingdom-Animal.HomePage page, the Kingdom.php config will be used. When on the Kingdom-Animal-Canine.Dog page, the Kingdom-Animal-Canine.php config file will be used -- and the Kingdom.php config file will NOT be used. If you want to "inherit" the settings from Kingdom.php, then you would add

     include_once("$LocalDir/Kingdom.php");

to the Kingdom-Animal-Canine.php file.

CSS style sheets

CSS style sheets follow the same pattern, but all stylesheets are included, since Cascading Style Sheets have inheritance built-in.

Suppose pub/css/local.css, pub/css/Kingdom.css and pub/css/Kingdom-Animal-Canine.css exist. On the Kingdom-Animal.HomePage page, the CSS sheets will be local.css and Kingdom.css. On the Kingdom-Animal-Canine.HomePage page, the CSS sheets will be local.css, Kingdom.css and Kingdom-Animal-Canine.css.

SideBars

There are two ways to use Hg in producing hierarchical SideBars. First, you can make the entire SideBar hierarchical by changing the skin template as follows:

From:	`<!--wiki:{$Group}.SideBar {$SiteGroup}.SideBar-->` (or similar)
To:	`<!--wiki:{$SideBar}-->`

The $SideBar page variable will then be set to the appropriate sidebar page for the current group, doing the search in the same kind of way that GroupHeader or GroupFooter etc are searched for. IE, Kingdom-Animal-Canine.SideBar, then Kingdom-Animal.SideBar, then Kingdom.SideBar and finally Site.SideBar.

Hg also makes a $SideMenu page variable available which looks for sidemenu pages instead of sidebar pages. This can be used for sites that want a consistent sidebar throughout the site, but only want the menu portion of the sidebar to change. To use it, just add (:include {$SideMenu}:) to the appropriate place of your sidebar.

Hg now supports unlimited hierarchical variables like this. To create a hierarchical breadcrump page for example to put in a skin, just add the following line to your config.php file:

$FmtPV['$BreadCrumb'] = 'HierarchicalPagenames($group, "BreadCrumb")';

Defaults

Hg is designed to work as close as possible to how PmWiki normally works, only with the addition of Hierarchical Groups. That is, the following default values are still used as normal:

Attributes: $DefaultPasswords (from config files)
Config: config.php & Group.Name.php
GroupHeader: Site.GroupHeader
GroupFooter: Site.GroupFooter
SideBar: Site.SideBar
CSS: local.css

Configuration variables

These can all be reset as desired in your local/config.php. Hg works fine without any configuration settings required.

Name	Description	Default
$hgseparator	Define the character used to separate the different parts of a group name	'-'
$hgmaxlevels	Define the maximum number of levels to split group names by	7
$hglinkprefix	Causes all links to be prefixed by specified subgroup	none
$hgprefixcode	String used to ignore prefixing	Hg
$hgbreadcrumbseparator	String used to separate terms in the breadcrumb.	' > '
$EnableBreadCrumbName	Turn display of names on and off in breadcrumb.	true
$EnableHgCleanUrls	Transforms links into cleanurls for viewer	false

BreadCrumbs

Hg is designed to give you easy BreadCrumbs, while still allowing great flexibility. To set up a basic BreadCrumb effect, simply put the (:breadcrumb:) markup on your page. It will create a pretty, clickable trail like Group > SubGroup > SubSubGroup > Name. That's all you need to do! You can Enable/Disable the display of the page name using the $EnableBreadCrumbName variable in a config file. However, you can do much more...

If you create a page called Site.HgBreadCrumbs, you can use text variables to do full aliasing of how each element in the breadcrumb looks. For example, suppose you are on page Main-Hide-Start.HomePage, then on Site.HgGroupTitles, you could put

 Main:  [[Main.HomePage|Welcome]] > 
 Hide:  
 Start:  [[Somewhere.Else|Getting Started]] >

In this case, the breadcrumb would output Welcome > Getting Started > HomePage (with appropriate underlying links. The Hg breadcrumb also uses $Title rather than $NameSpaced (cluster), so you can change HomePage to something different as well.

In situations where you need extra flexibility, you may wish to consider a hierarchical page variable (see above), and insert it into your skin where desired. Then at the default $SiteGroup.BreadCrumb location (different from page BreadCrumbs), add the (:breadcrumb:) markup. Hg will then enable you to overwrite it in any child groups you wish, just as it does with sidebars and sidemenus--allowing you to create fully customized breadcrumbs wherever needed.

Group Titles

Hg is designed to also make it easy to assign custom titles to specific groups, and make them hierarchical as well. At the easiest level, just add {$grouptitle} to your page, and the last subgroup will be returned as the group title. Again, however, you can do more...

If you create a page called Site.HgBreadCrumbs, you can list any group you like as a text variables, and supply it a group title. So you could, for example put

 Kindgom: Apple
 Kingdom-Animal: Orange
 Kingdom-Animal-Canine: Banana
 Kingdom-Plant:

Then pages in the appropriate groups will return the appropriate values for {$grouptitle}. You can even include most markup! However, since these group titles are hierarchical, a page in group Kingdom-Test will also return Apple. If a value is cleared for a specific group (like Kingdom-Plant), you will get the default value (Plant), for that group, and all descendent groups. IE, in Kingdom-Plant-Grass you would get Grass.

Link Shortcuts

Several powerful link shortcuts are provided in Hg, when making [[links]]:

     * absolute
     ^ relative ancestor
     - relative descendant

Examples	Current page is Kingdom-Animal-Canine.
`Kingdom` (grandparent):	`[[^^.]]` or `[[*.]]`
`+-Plant` (uncle):	`[[^^-Plant.]]` or `[[*-Plant.]]`
`\| +-Grass` (cousin):	`[[^^-Plant.Grass]]` or `[[*-Plant.Grass]]`
`+-Animal` (parent):	`[[^.]]` or `[[**.]]`
`+-Canine` (self):	`[[${FullPage}]]` or `[[***.]]`
`\| +-Terrier` (child-page):	`[[Terrier]]`
`+-Feline` (sibling):	`[[^-Feline.]]` or `[[**-Feline.]]`
`+-Cat` (nephew):	`[[^-Feline.Cat]]` or `[[**-Feline.Cat.]]`
Examples	Current page is Kingdom-Animal.
`+-Feline` (child-group):	`[[-Feline.]]`
`+-Cat` (grandchild):	`[[-Feline.Cat]]`

Page Variables

$g0	The number of levels in the given group
$g1	The first part of the group name
$g7	The 7th part of the group name (if it exists)
$n0	The number of levels in the given page name ($PageName, not $FullName)
$n1	The first part of the page name
$n7	The 7th part of the page name (if it exists)
$sidebar	The name of the sidebar page that should be associated with this page. See above.
$sidemenu	The name of the sidemenu page that should be associated with this page. See above.

CleanUrls

Hg allows you to get a cleanurl effect by manipulating how links are formed and interpreted by PmWiki. This means that when you mouseover or click a link like the following, it will change what shows up in the status bar and address bar of your browser to the second link, rather than the first:

http://www.example.com/pmwiki.php?n=Kingdom-Animal-Canine.Dog
http://www.example.com/pmwiki.php?n=Kingdom/Animal/Canine/Dog

Note the actual wiki markup is not changed, only how the viewer experiences the links. The cleanurls can also be sent in emails, etc., and they will work as expected.

Cleanurls are disabled by default. To enable them, simply set $EnableHgCleanUrls=1; in your config.php file. Note that even when cleanurls are disabled, Hg can still read either format. It only disables the link transformations.

Those wishing to eliminate "pmwiki.php?n=" from the link (in the address bar) can use url rewriting as described in the CleanUrls recipe.

Link Prefixing

Hg also adds an optional $hglinkprefix capability you can use to keep links in some subgroup by automatically prefixing them with a specified value. This essentially allows you essentially to create full-fledged virtual wiki's in remote subgroups! Imagine for example, giving each user their own wiki space as subgroups of Profiles-$AuthId. To do this, simply set $hglinkprefix equal to some value in your config file, and all links will automatically be prefixed with that value.

EX. Suppose you are on a page in Kingdom-Animal-Canine, and your config file for that page has set the $hglinkprefix to Kingdom-Animal-Canine. In this situation, links to pages like [[Dog.Poodle]], [[Coyote.]] or [[Wolf]] will automatically be changed to Kingdom-Animal-Canine-Dog.Poodle, Kingdom-Animal-Canine-Coyote.(HomePage), and Kingdom-Animal-Canine.Wolf.

To create links that ignore the prefix (useful for things like sidebars, pagelists, or included pages) simply put a ":" at the beginning of the link. Hg is smart enough to ignore colons at the beginning of a link when used elsewhere in the wiki. Note however, that neither relative or absolute link shortcuts can be used when there is a leading colon.

More Info

Please report bugs, problems, or suggested improvements in the comments section below.

Release Notes

Jan 31, 2007	Initial release.
Feb 01, 2007	Added subname vars, fixed problem resolving pagename
Feb 02, 2007	Version, Subvars fix for pagelists. Thanks Kathryn!
Feb 04, 2007	CleanUrls version released for testing and comments...
Feb 06, 2007	Hg now has link prefixing!
Mar 07, 2007	Fixed several minor bugs, added "-" linking
Mar 18, 2007	Generalized hierarchical page variables & customizable breadcrumbs
Apr 25, 2007	Fixed a bug in the markup pattern for link shortcuts

Contributors

Caveman Click here to learn more about the story behind this recipe...
Kathryn Andersen -- Thanks for help at various points, and your excellent documentation.
Hans -- Thanks for your excellent idea for generalizing hierarchical page variables.
Many others who have suggested countless ideas along the way.

Comments

See discussion at Hg-Talk

User notes ? : If you use, used or reviewed this recipe, you can add your name. These statistics appear in the Cookbook listings and will help newcomers browsing through the wiki.

Hg