|
Cookbook /
HgSummary: Produce Hierarchical groups like effects on your site
Version: 2007-03-07
Prerequisites: None
Status: Stable
Maintainer:
More Info: See Hierarchical Groups Questions answered by this recipeQ. 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');
DescriptionThis 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:
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 WorksLet'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/AttributesGroup 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 filesConfiguration 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("to the Kingdom-Animal-Canine.php file. CSS style sheetsCSS 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. SideBarsThere 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:
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")'; DefaultsHg 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:
Configuration variablesThese can all be reset as desired in your local/config.php. Hg works fine without any configuration settings required.
BreadCrumbsHg 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 Group TitlesHg 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 ShortcutsSeveral powerful link shortcuts are provided in Hg, when making [[links]]: * absolute
^ relative ancestor
- relative descendant
Page VariablesCleanUrlsHg 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 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 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 PrefixingHg 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- 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 InfoPlease report bugs, problems, or suggested improvements in the comments section below. Release Notes
Contributors
See Also
CommentsThis is a really nice innovation. I had just a couple of problems. 1. I found that links did not resolve properly for new groups, i.e. if you link to [[Main-Kingdom]] and there are no pages matching Main-Kingdom.*, then the link ends up going to Main.Main-Kingdom. The solution is to link to explicitly create Main-NewGroup.HomePage, Hg links work as expected once that page exists. 2. I didn't understand how to put a breadcrumb link in a skin. I understood from the guide that I would need to create a page variable, but that's not the case (at least for the simple breadcrumb that I wanted). All you need to do is edit the skin.tmpl page and insert <!--markup:(:breadcrumb:)--> at the appropriate place. Phil 5/4/2007 1. In order for hg.php to work, I had to eliminate the line: Thanks so much! LFS 13-14.06.2007 I'm unable to get this working at a basic level, and I can't figure out what I'm doing wrong. Hope you can help. I placed the hg.php file in my cookbooks directory. I added the include_once statement to my config.php. (I also tried using double quotes and Any help greatly appreciated. Am facing the same problem as SarahD. The markup (:breadcrumb:) does not work at all. I tried all the above recommendations. I am having the same problem as SarahD and FarhadK. I even set-up a virgin copy of PMWiki with no modifications at all except for installing Hg and including Hg.php in the config.php file. On a new, empty page, when I insert (:breadcrumb:) nothing gets interpreted. I then installed Cluster and it's breadcrumb function seems to work correctly. My server is a Windows 2000 box running IIS 5. Help! Hi, please change line: |