Hg

Summary: Produce Hierarchical groups like effects on your site
Version: 2007-03-07
Prerequisites: None
Status: Stable
Maintainer: (unsupported since 2008)
Categories: Markup | Links | Hierarchy | PageNaming

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.

NameDescriptionDefault
$hgseparatorDefine the character used to separate the different parts of a group name       '-'
$hgmaxlevelsDefine the maximum number of levels to split group names by7
$hglinkprefixCauses all links to be prefixed by specified subgroupnone
$hgprefixcodeString used to ignore prefixingHg
$hgbreadcrumbseparator       String used to separate terms in the breadcrumb.' > '
$EnableBreadCrumbNameTurn display of names on and off in breadcrumb.true
$EnableHgCleanUrlsTransforms links into cleanurls for viewerfalse

 

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
ExamplesCurrent 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.]]
ExamplesCurrent page is Kingdom-Animal.
  +-Feline (child-group):[[-Feline.]]
    +-Cat (grandchild):[[-Feline.Cat]]

 

Page Variables

$g0The number of levels in the given group
$g1The first part of the group name
$g7The 7th part of the group name (if it exists)
$n0The number of levels in the given page name ($PageName, not $FullName)
$n1The first part of the page name
$n7The 7th part of the page name (if it exists)
$sidebarThe 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, 2007Initial release.
Feb 01, 2007Added subname vars, fixed problem resolving pagename
Feb 02, 2007Version, Subvars fix for pagelists. Thanks Kathryn!
Feb 04, 2007CleanUrls version released for testing and comments...
Feb 06, 2007Hg now has link prefixing!
Mar 07, 2007Fixed several minor bugs, added "-" linking
Mar 18, 2007Generalized hierarchical page variables & customizable breadcrumbs
Apr 25, 2007Fixed a bug in the markup pattern for link shortcuts

 

See Also

  • Hierarchical Groups -- For a comparison of Cluster and Hg, and other related options.
  • Cluster -- An alternative to Hg with a few slightly different features.

 

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.