Page History

h1. Automated Menu Creation
{scrollbar:no-css=true}

*{excerpt}This tutorial shows you how to use the [children macroMacros] to automatically generate self-updating menus...{excerpt}*

There are three scenarions where you might want to automate the structure of your menus:

* You have a big menu structure that matches the structure of contnet in your [space|Spaces]
* You want to allow other people to add content and have the menus automatically udpated
* You're lazy (a bit like me) and don't want to type loads of [Wiki Notation] 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 tooltips 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 un-ordered 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}
* [Builder] {children}
{noformat}

The [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:

* [Builder] {children}

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}
* [Builder] {children:page=Builder}
{noformat}

Which would give:

* [Builder] {children:page=Builder}

Voila! That's exactly{footnote}Well, not quite. We use the ??depth=2?? parameter of the [children macro] to automaticall create sub-menus for any pages that themeselves 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 [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}* [Automated Menu Creation] {incoming-links:style=disc}{incoming-links}
{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:

* [Automated Menu Creation] {incoming-links:style=disc}{incoming-links}

{display-footnotes}

h3. Our Navigate Menu

While writing this tutorial, I got a bit carried away playing around with other macros and thus the ??Navigate?? menu (at the top of all pages in this user guide) was born.

Here's how it was made:

{noformat}
* Navigate
** Incoming Links {incoming-links:style=disc}* No incoming links{incoming-links}
** Child Pages {children}
** ----
** Related Labels {related-labels}
** ----
** Page Headings {toc:style=disc|maxLevel=5}
{noformat}

Have fun!