The Metadata Plugin Metadata Management for Manila

Site last updated 2/24/2006; 12:33:21 PM

Home Why Features FAQ Updates Documentation Download Developers Bugs Feedback Discuss Planned Features				navigator() macro Author:   John VanDyk   Posted: 10/4/2002; 4:14:45 PM Topic: navigator() macro Msg #: 1706 (top msg in thread) Prev/Next: 1705/1707 Reads: 8203 Syntax: navigator (metaname, metavalue:"--related--", sortby:"", direction:"both", msgNum:nil, sep:" | ",beforeItem:"", afterItem:"",prevText:"",nextText:"") The navigator macro allows you to navigate web pages in the order defined by a meta type. For example, suppose you are creating a website about Trees. You have divided your site into sections, including a particularly intriguing section about Oaks. You've created a meta type called Section and on each page about oaks, you've set the value of the Section meta type, not surprisingly, to Oak. Now you've added five pages about oaks: MsgNum Title 45 Planting Oaks 46 Using Oaks for Furniture 48 Story of an Acorn 49 Oaken Kegs for Ale 50 The Old Oaken Bucket Because you are working on a team, you were not able to add the pages with sequential message numbers -- just after you submitted the story about Using Oaks for Furniture, team member Frieda Hackleberry submitted a story about Birch Bark Paper. You don't really care, though, because she added her story to the Birch section of the website, not the Oak section. In other words, when she submitted her story she set the Section meta type to Birch. The message numbers don't have to be sequential, because we're not going to use them for figuring out which order your pages are in. If you want the navigator macro to give you previous and next links based on the order you submitted the stories, simply say {metadatamacros.navigator("Section")} and you're done. On the first page of the section, there will be a link to the next page. On the second page, there will be a link to the first page and the third page. And so on. Maybe you don't want them in the order submitted. Well, what do you want to order them by? You could create another meta type called Position, and number them that way: MsgNum Title Position 45 Planting Oaks 500 46 Using Oaks for Furniture 400 48 Story of an Acorn 300 49 Oaken Kegs for Ale 200 50 The Old Oaken Bucket 100 Now I say {metadatamacros.navigator("Section", sortBy:"Position")} and presto, the order will start with The Old Oaken Bucket as the first page and Oaken Kegs for Ale as the second page, etc. Why did I use big numbers like 300? So later I can insert a page in the middle by setting Position to 350 for the new page. You can customize the macro in many ways. Here's a description of the parameters: metaname and metavalue: the navigator macro actually does a query before it orders the pages. So in the above example I have Section for the meta type because I don't want to include all the pages on my site, just the ones in the Oak section. I could set metavalue to Oak explicitly ( {metadatamacros.navigator("Section", metavalue:"Oak")} ) but that's unnecessary because the default value for the metavalue parameter is "--related--", which is a special string that means "find out what the value for the Section meta type is on this page we're currently rendering and use that". That means that with the same macro parameters, the Oak section will have navigation links within it, while the navigation for the Birch section will remain in the Birch section. Which means you can put a single instance of the macro in your template and have it work everywhere. If no next or previous pages are found, it returns the empty string. sortby: this tells the macro how to order the results of the query. By default, it orders the pages in the order they were created. direction: values are "both", "prev", or "next" depending on which link you want to generate. Default is "both". msgNum: if for some reason you want to explicitly set the message number context, you can do so using this parameter. sep: this is the separator between the previous and next links. By default it's the vertical bar. If you want to suppress it set it to the empty string: {metadatamacros.navigator("Section",sep:"")} beforeItem and afterItem: used to format the resulting title(s) as in the query macro prevText and nextText: if you don't want the title of the page as the link to the previous or next page, put what you want to use instead into these parameters. If you want to use arrows, you could put an img tag here. Just make sure to use single quotes for the attributes instead of double quotes. You can see an example of that here. Note the green arrows at the bottom of the page.