{deck:id=Advanced Macros|width=907px}
{card:label=Overview}

h4. Advanced Macros

This plugin provides many macros which generates information on Wiki content.

h5. This plugin includes the following macros:

* *listlabels* -- Displays the pages for a label in a pretty matrix.
* *content-by-user* -- List all the content created by a particular user.
* *children* -- List all the children of a page (and possibly their children).
* *search* -- Perform a full-text search, and include the results in the page.
* *index* -- Create an index of all pages within the space.
* *rss* -- Retrieve a remote RSS feed and summarise it in the page.
* *blog-posts* -- View, summarise or list the most recent news items in the space.
* *excerpt* -- Mark a section of a page as an excerpt for page summaries.
* *excerpt-include* -- Include the excerpt from one page within another page.
* *include* -- Include the full content of one page within another page.
* *gallery* -- Create a thumbnail gallery from a page's attachments.
* *doc* -- Link to the documentation using the doc macro.
* *change-history* -- Show the history of version comments.
* *popular-labels* -- List the most popular labels.
* *contentbylabel* -- List the pages labelled by a specified set of labels.
* *favpages* -- List the pages in your favourites list.
* *related-labels* -- List the related labels for a given set of labels, or for the current page.
* *recently-used-labels* -- List the labels that have been used recently.
* *navmap* -- Displays the pages for a label in a pretty matrix.

{card}
{card:label=Documentation}
{deck:id=advancedm}
{card:label=Excerpt / Include
Macros}
{deck:id=excerptincludem}

{card:label=include}
The Include macro displays the contents of one Wiki page in another. If the page is from another space, you will need to include the space name.
h3. The Code :
{code}
{include:HELP:Wiki Markup Editor}
{code}
h3. What you will get :
The page 'Wiki Markup Editor' from the wiki space 'HELP' is not displayed on this page:
{include:HELP:Wiki Markup Editor}
h3. Parameters
{code}
{include:SPACE:Name_of_page}
{code}
{note:title=The 'space' parameter is case sensitive.}
{card}

{card:label=excerpt}
The Excerpt Macro is used to mark a part of a page's content for re-use. By itself, the excerpt macro does not change the display of a page. However, defining an excerpt enables other macros such as *excerpt-include* and *blog-posts* macros to display the specified content elsewhere.
{note:title=A page can only have *ONE* excerpt.}
h3. The Code :
{code}
{excerpt}
Content to be included on another page.
{excerpt}
{code}
h3. What you will get :
Content to be included on another page.
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
|hidden|(x)|false|Controls whether the text between the excerpt tags will appear on that page when users read it.|
{card}

{card:label=excerpt-include}
This macro allows a portion of a page to 'excerpted' in another. To use this macro you must define the 'excerpted' content with the *excerpt* macro.
h3. The Code :
{code}
{excerpt-include:Advanced Macros Plugin}
{code}
h3. What you will get :
This is the plugin libraries navigation bar, which was created using the *excerpt* and *excerpt-include* macros. The panel displays the name of the page where the 'excerpted' content is being pulled from. It can be removed by adjusting the 'nopanel' parameter (see below):

{excerpt-include:Advanced Macros Plugin}

If any changes are made to the content within the body of the *excerpt* macro, it will automatically be changed on any pages it is being 'excerpted'. This makes the *excerpt* and *excerpt-include* macros ideal for creating navigation bars.
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
|nopanel|(x)|false|Controls whether the square panel border around the excerpt should be removed. Also controls whether the name of the page where the 'excerpted' content is being pulled from is displayed.|
{card}
{deck}
{card}

{card:label=Label 
Macros}
{deck:id=labelm}

{card:label=popular-labels}
Displays the most popular labels used throughout a Wiki space.
h3. The Code :
Bulleted list:
{code}
{popular-labels:style=list|spacekey=HELP|count=15}
{code}
Heatmap :
{code}
{popular-labels:style=heatmap|spacekey=HELP|count=15}
{code}
h3. What you will get :
*Bulleted list:*
{popular-labels:style=list|spacekey=HELP|count=15}
*Heatmap :*
{popular-labels:style=heatmap|spacekey=HELP|count=15}

h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
|count|(x)|100|Specifies the total number of labels to display in the heatmap.|
|spacekey|(x)|none|Restricts the list of popular labels to the specified space. |
|style|(x)|list|Displays the list of popular labels in standard bullet-point 'list' form or as a 'heatmap'. The heatmap style uses different font sizes depending on their rank of popularity, ordered by label names. The list style orders labels by popularity (highest first).|
{card}

{card:label=contentbylabel}
Generates a list of content associated with a specific label or labels.
h3. The Code :
{code}
{contentbylabel:Documentation}
{code}
h3. What you will get :
{contentbylabel:Documentation}
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
|spacekey|(x)|all|Filter by space.|
|type|(x)|false|Filter by content type.|
|showLabels|(x)|true|Show or hide labels for results.|
|showSpace|(x)|true|Show or hide spaces for results.|
|excerpt|(x)|false|Show or hide excerpts for results.|
|maxResults|(x)|5|Specify maximum results to display.|
|sort=creation
sort=title
sort=modified
sort=recent|(x)|recent|The 'sort' attribute is an optional attribute that allows you to configure how the children are sorted. Use the 'reverse' attribute to optionally reverse the sorting.|
|operator|(x)|OR|The operator to apply to the supplied lists of labels. By default, a page with any of the labels will be listed. By using operator=AND, only pages with all of the supplied labels will be listed.|
{card}

{card:label=related-labels}
Lists all tagged labels from every page which has one or more labels in common with the current page.
h3. The Code :
{code}
{related-labels}
{code}
h3. What you will get :
{related-labels}
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
|labels|(x)|none|Specify the labels for which you want to view related labels. For example, documentation, help.| 
{card}

{card:label=recently-used-labels}
Generates a list of recently used labels on a specific scale : Global, Space, Personal.
h3. The Code :
Horizontal list:
{code}
{recently-used-labels}
{code}
Table:
{code}
{recently-used-labels:style=table}
{code}
h3. What you will get :
*Horizontal list:*
{recently-used-labels}
*Table:*
{recently-used-labels:style=table}
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
|count|(x)|10|Specifies the total number of labels to display in the list. |
|scope|(x)|global|Specifies the scope of labels to be displayed in the list. Valid values include:
* global — covers all non-personal spaces in the Confluence installation.
* space — the current space.
* personal — your own personal space.|
|style|(x)|list|Displays the list of recently used labels in a horizontal 'list' style or in a 'table' style. The table style includes additional information such as the page to which the label was added user who added it.|
|title|(x)|none|Adds a title to the top of the list in table style. Titles are only visible when the *List* Style (style) parameter has been set to table.| 
{card}

{card:label=listlabels}
Creates a hyperlinked alphabetically listed index of all labels within the current space.
h3. The Code :
{code}
{listlabels}
{code}
h3. What you will get :
{listlabels}
{card}
{card}
{deck}


{card:label=content-by-user}
Creates a list of ALL current content by a specific Wiki user. This includes, pages, comments, and spaces.
h3. The Code :
{code}
{content-by-user:ggaskell}
{code}
h3. What you will get :
!content_by_user.png!
h3. Parameters
{code}
{content-by-user:username}
{code}
{card}

{card:label=children}
Creates a hyperlinked list of a pages' children and its' descendants (childrens' children).
h3. The Code :
{code}
{children:all=true}
{code}
h3. What you will get :
{children:all=true}
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
|all|(x)|false|Display all descendants.|
|page|(x)|current|Specify which page to display children for in a current space or in a different space.
If the page parameter is '/', then the macro will list all the current space's top-level pages i.e. those without parents. If the page parameter is a space key followed by a
colon (e.g {code}{children:page=DOC:}{code}), then the top-level pages of that space will be listed.|
|depth|(x)|none|Specify the depth of descendents to display. {note:title=If your *children* macro includes both 'all=true' and 'depth=X' parameter-value combinations where X is a number, 'all=true' takes precedence. If an 'all=false' and 'depth=X' parameter-value combination is used, 'depth=X' takes precedence.}|
|first|(x)|none|Restrict the number of children displayed at the top level.|
|style|(x)|none|Specify the style in which descendents are displayed.|
|excerpt|(x)|false|Display the child pages' excerpts, if they exist.|
|sort=creation
sort=title
sort=modified|(x)|Manual if manually ordered, otherwise alphabetical|he 'sort' attribute is an optional attribute that allows you to configure how the children are sorted. Specify 'creation' to sort by content creation date, 'title' to sort alphabetically on title and 'modified' to sort of last modification date.|
|reverse|(x)|false|Use this parameter in conjunction with the 'sort' parameter described above. Set 'reverse=true' to change the sort from ascending to descending order.|
{card}

{card:label=search}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}

{card:label=index}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}

{card:label=rss}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}

{card:label=gallery}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}

{card:label=doc}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}

{card:label=change-history}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}

{card:label=favpages}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}

{card:label=navmap}
h3. The Code :
h3. What you will get :
h3. Parameters
||*Name*||*Required?*||*Default*||*Description*||
{card}
{card}
{deck}
{deck}

{roundrect:bgcolor=#828282|width=909px|height=50px|corners=false,false,true,true}
{roundrect}