Page History

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

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

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

* You have a big menu structure that matches the structure of contnetcontent in your [space|AtlassianConfluence:Spaces]
* You want to allow other people to add content and have the menus automatically udpatedupdated
* You're lazy (a bit like me) and don't want to type loads of [AtlassianConfluence:Wiki Markup NotationEditor] 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 tooltipstips 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-orderedunordered 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:

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

Which would give:

* [Builder] {children:page=Builder{noformat}

Voila! That's exactly{footnote}Well, not quite. We use the ??depth=2?? parameter of the [children macro] to automaticallautomatically create sub-menus for any pages that themeselvesthemselves 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, Iwe got a bit carried away playing around with other macros and thuscame the ??Navigate?? menu (atup with the topidea of alla pages in this user guide) was born.

Here's how it was madenavigate menu:

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

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!