[All Adaptavist Apps]
Wiki Markup |
---|
h1. Automated Menu Creation *{excerpt}This tutorial shows you how to use the [AtlassianConfluence:Macros] to automatically generate self-updating menus...{excerpt}* There are three scenarios where you might want to automate the structure of your menus: * You have a big menu structure that matches the structure of content in your [space|AtlassianConfluence:Spaces] * You want to allow other people to add content and have the menus automatically updated * You're lazy (a bit like me) and don't want to type loads of [AtlassianConfluence:Wiki Markup Editor] to create your menus If any of those describe you, read on :) But first, there are some scenarios where you might want to _avoid_ automating menus: * Automated menus can't have icons in them (yet... we're working on that feature) * Automated menus have limited ordering options (alphabetically, date, etc) - if you want a very specific order to items, you'll have to manually add them. * You can't define custom on-screen text or tool tips when using macros (unless they specifically support such a feature) So, assuming that you still want to automate your menus, let's begin... h2. Macros to the Rescue You can use *any* macro that outputs an unordered bullet list of items within a menu. :D Let's take a look at two of them... h3. \{children} macro This is by far the most common macro to make it's way in to the menu settings: {noformat} {menu}[Builder] {children} {menu} {noformat} The [AtlassianConfluence:children macro] basically creates a bulleted list of child pages from a given starting point. The example shown above would look something like this if you put it on a page: {menu}[Builder] {compound-menuitem:home|caption=builder|flat=true} {children} {menu} And produces the following menu: {menubar} {menu}[Builder] {children} {menu} {menubar} As you can see, there's no other items showing - that's because *_this_* page doesn't have any children. However, if we were on a page with children then the list would be generated. To ensure that children are listed from a specific starting point, use the ??page?? parameter as follows: {noformat} {menu}[Builder] {children:page=Builder} {menu} {noformat} Which would give: {menu}[Builder] {children:page=Builder} {menu} Which results in the menu: {menubar} {menu}[Builder] {children:page=Builder} {menu} {menubar} Voila! That's exactly{footnote}Well, not quite. We use the ??depth=2?? parameter of the [children macro] to automatically create sub-menus for any pages that themselves have children.{footnote} how the ??Builder?? menu and most other menus are created at the top of pages in this user guide. {display-footnotes} h3. \{incoming-links} macro The [AtlassianConfluence:incoming-links macro] lists pages that link to the current page. As such, if you're on a page that nothing links to, it won't output anything{footnote}The [incoming-links macro] actually allows you to specify what to output if there are no incoming links: {noformat} {incoming-links:style=disc}* No incoming links{incoming-links} {noformat}{footnote}. However, as something does link to this page, we will get some output: {noformat} {menu}[Automated Menu Creation] {incoming-links:style=disc}{incoming-links} {menu} {noformat} As you can see, this macro needs to be told to output as a bulleted list (by default it outputs with icons, but not the sort that are usable in the menu) and because the macro can have a body we've had to include the closing tag as well. On screen, for this specific page, the macro would display: {menu}[Automated Menu Creation] {incoming-links:style=disc}{incoming-links} {menu} Which produces the menu: {menubar} {menu}[Automated Menu Creation] {incoming-links:style=disc}{incoming-links} {menu} {menubar} {display-footnotes} h3. Our Navigate Menu While writing this tutorial, we got a bit carried away playing around with other macros and came up with the idea of a navigate menu: {noformat} {menu}Navigate {submenu}Incoming Links {incoming-links:style=disc}* No incoming links{incoming-links} {submenu} {menuseparator} {submenu}Page Headings {wikimenu}{toc:maxLevel=5}{wikimenu} {submenu} {submenu}Child Pages {children} {submenu} {menu} {noformat} {menubar} {menu}Navigate {submenu}Incoming Links {wikimenu}{incoming-links:style=disc}* No incoming links{incoming-links}{wikimenu} {submenu} {submenu}Page Headings {wikimenu}{toc:maxLevel=5}{wikimenu} {submenu} {submenu}Child Pages {children} {submenu} {menu} {menubar} Be warned, if you add this menu, it can get very big! We've included it here as an example of the different types of macros that can be used. Have fun! |