Introduction

The Include Content plugin contains a number of macros to insert content from other pages or sources into the current page.

As a general rule, if a macro tries to include a content by name, but the current user does not have permissions to view the content an error to that effect will be shown. If the macro is pulling in pages by a rule, such as all pages with a particular label, then pages the user does not have permissions to see will be silently ignored.

Features at a Glance

Feature	Description
FAQ Macro	A macro to build a faq from child pages or by pages with a given label.
FAQ Page Blueprint	A blueprint to setup a FAQ for a space.
Help Text Macros	A set of macros to create a clickable element that pops up some help text.
Include Code Macro	A macro to pull source code from a url and insert it into the standard code macro.
Include Children Macro	A macro to serialized the child pages onto the current page.
Include Page With Replacement Macro	A macro to include a page with the ability to perform text substitutions.
Include Shared Block Macro	A macro to include the content from a shared block onto the current page.
Include Shared Block With Replacement Macro	A macro to include the content of a shared block with the ability to perform text substitutions.
Shared Block Macro	A block of content that can be included elsewhere. This acts like the excerpt macro, but you can have multiple shared blocks on a page.

Features in Detail

FAQ Macro

Description

The FAQ Macro creates a FAQ like visualization of content and titles from various pages. As a starting place to understand what tha macro does, the default settings will for the macro create a list of links where the displayed text is the title of a child page and when clicked will expand to reveal the content of that child page. From that starting place, the macro offers three directions to make choices. First is how to identify the pages that will be used to create the list. The second is how to visualize the list. The last is what additional information to include in the view.

Selecting Content

There are four parameters used to identify the content to pull in: Labels, Restrict to Spaces, Restrict to Descendants of Page, Include Descendants and And Labels. Below is a table summarizing how these parameters work together.

Label	Space Keys	Page	Expected Outcome
			The children of the current page will be selected. All descendants will be selected if Include Decendants is checked.
X			Every page, regardless of space, with any of the labels will be included. If And Labels is checked, the only pages with all of the labels will be included.
	X		The home page and every descendant page for every identified space will be selected. Use this with caution as it can pull in a lot of content.
	n/a	X	Child or descendant pages of the selected page will be included. The Space Keys field will be ignored in this case as the page defines the bounding space.
X	X		All pages with any or all of the labels that are also in the identified spaces will be included.
X	n/a	X	All pages with any or all of the labels that are also a descendant of the identified pages will be included.

Viewing the List of Pages (Render Style)

There are three ways the list of pages can be displayed. The first, Expand is as a list of links, where every link matches the title of the include pages that when clicked will expand to show the content. The second and third render a table where every row show information about a child pages. If the Link render style is selected, the pages title will be shown as a link to that page. If the Popup style is selected, the link will bring up a popup dialog box.

What portion of the pages to show.

The Expand or Popup render style can bring up the full Page content, the First Excerpt or the First Shared Block on the page. In addition to selection what portion of the page to show, there are options to include various pieces of meta-information such as the space where the page lives, the last modification date, the last modification author, the page labels and the number of likes. The information will be included in the table for the Link and Popup render styles. It will be inserted into the content display for the Expand render style.

Usage

Insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Labels	Zero or more labels. See the Summary of Content Selection table above to see how the parameter is used.
Restrict To Spaces	Zero or more comma separated space keys. See the Summary of Content Selection table above to see how the parameter is used.
Restrict To Descendants of Page	A page title. See the Summary of Content Selection table above to see how the paramter is used.
Render Style	One of Expand (default), Popup, or Link.
Render Content	One of Page (default), First Excerpt or First Shared Block.
Title on Popup Dialog	Text to display in the title section of the popup dialog. Defaults to the page title. Use the string $title to represent the current page title.
And Labels	If set, the list of labels in the Labels field will be joined with and rather than or.
Include Descendants	When pulling children pages, all descendants will be included. Otherwise, only children pages willbe.
Include Space	Show the space name in the results
Include Last Modified Date	Show the last modified date in the results
Include Last Modification Author	Show the author who made the last modification in the results
Include Page Labels	Show the page labels in the results.
Include Like Count	Show the number of likes in the results.

Purpose

This macro was developed to create a FAQ that was easier to maintain than a list of expand macros. Over time the macro has been used in a number of different contexts, for example to create a list of tutorials.

FAQ Page Blueprint

Description

The FAQ blueprint is a convenient feature to setup a FAQ for a space using the FAQ macro.

Usage

Select the FAQ page from the "..." menu next to the create button.

Purpose

It provides an easy way to setup a FAQ for a space.

Help Text Macros

Description

The Help Text Macros are a trio of related macros to create text or a question mark icon that when clicked brings up some help text.

Macro List

Macro Name	Description
Help Text	A block macro where the body of the macro is brought up in a popup dialog when clicked.
Help Text From Page	An inline macro that will bring up the contents of the identified page when clicked.
Help Text From Shared Block	An inline macro that will bring up the contents ### Usage

Usage

Help Text

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Text	The text to show on the page. Defaults to a question mark in a circle. The text (?) will be substituted for the question mark in a circle icon.
Title	Text to display on the heading of the dialog box (Only effective if the Dialog Box type of popup is selected).
Tip	Text to display on the footer of the dialog box (Only effective if the Dialog Box type of popup is selected).
Type	The popup rending style. Popup will place a small popup just above the text. Dialog Box will bring up a centered modal dialog box.

Help Text From Page

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Page	The page with the content to include.
Text	The text to show on the page. Defaults to a question mark in a circle. The text (?) will be substituted for the question mark in a circle icon.
Title	Text to display on the heading of the dialog box (Only effective if the Dialog Box type of popup is selected).
Tip	Text to display on the footer of the dialog box (Only effective if the Dialog Box type of popup is selected).
Type	The popup rending style. Popup will place a small popup just above the text. Dialog Box will bring up a centered modal dialog box.

Help Text From Shared Block

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Page	The page with the content to include.
Shared Block Key	The key of the shared block to include. Defaults to the first shared block on the pages.
Text	The text to show on the page. Defaults to a question mark in a circle. The text (?) will be substituted for the question mark in a circle icon.
Title	Text to display on the heading of the dialog box (Only effective if the Dialog Box type of popup is selected).
Tip	Text to display on the footer of the dialog box (Only effective if the Dialog Box type of popup is selected).
Type	The popup rending style. Popup will place a small popup just above the text. Dialog Box will bring up a centered modal dialog box.

Purpose

This macro was created so that we could provide a rich description of some text without having to have it all written out and taking up lots of screen space.

Include Code Macro

Description

The code include macro is a wrapper around the Confluence Code macro that can pull the source code from a url and place it onto the page

Usage

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
URL	The url from which to get the source code.
Syntax Highlighting	The syntax highlighting pen to use.
Username	If the url requires authentication, this is the username. Confluence Administrators can configure credentials by server using the plugin configuration page.
Password	If the url requires authentication, this is the password. Confluence Administrators can configure credentials by server using the plugin configuration page.
Title	The title of the code block.
Start Line Regex	This is a regular expression used to identify a line that represents the starting point of the code to include.
Include First Matched Line	If checked, the matched line will be included. Otherwise, it will be excluded.
End Line Regex	This is a regular expression used to identify a line that represents the ending point of the code to include.
Include Last Matched Line	If checked, the matched line will be included. Otherwise, it will be excluded.
Multiple Regions	If checked, the plugin will extract multiple sections each bounded by the start and end regular expressions.
Initial Line	An arbitrary line of text to include at the start. For example, "...". Use "\n" to insert a line break.
Join Line	An arbitrary line of text to include between the multiple regions. For example, "...". Use "\n" to insert a line break.
Final Line	An arbitrary line of text to include at the end. For example, "...". Use "\n" to insert a line break.
Collapsable	Should the code block be collapsible.
Show Line Numbers	Should line numbers be included.
Theme	The style theme to use.

Purpose

This macro was written so we could pull in examples and source code directly fromm the SCM system so that the inforamtion in Confluence was always up to date and did not need to be manually updated.

Include Children Macro

Description

This macro serializes the children and descendants of a page onto the current page.

Usage

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Page	The parent page
Exclude Page Titles	If checked, the pages titles will not be included. If unchecked, the pages titles will be inserted as an heading matching their depth below the parent page.
Levels to Included	A number representing how many levels of descendants to include.

Purpose

As our company has been migrating to Confluence, many users are importing Word documents and breaking them up into trees of pages. Some users still wanted the single document they could print and markup. This macro provided the ability to create a single page with all of the content for those users, while still being able to manage the content as a tree of pages.

Include Page With Replacement Macro

Description

This macro is a variant of the Confluence Include Page macro. It does the same task, except the user can provide substitutions rules into the body of the macro which get applied when the macro renders. Every line in the body of the macro represents a substitution rule and should conform to the pattern <delimiter>initial-string<delimiter>final-string<delimiter>. The default delimiter is the forward slash, "/", but it can be changed as one of the macro properties. The initial string is interpreted as a Java regular expression. Care should be taken in defining the regular expression as the substitution can render the underlying representation invalid and the content will not render at all.

Here is an example that changes Monday to Tuesday and January to February.

/Monday/Tuesday/
/Januray/February/

Usage

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Page	The page to include
Delimiter	The delimiter to bound and separate the text to be replaced and the replacement text.
Suppress Permission Errors	If checked and the user does not have permissions to view the included page, the macro will silently fail to render the page.

Purpose

This macro was created to assist in creating code tutorials. Much of the content was boilerplate, but the name of the example would change. This macro allows one to include the boilerplate content - but insert the name of the current example project.

Include Shared Block Macro

Description

This macro is almost identical to the Confluence Include Page macro with the difference that only the Shared Block on the page is inserted rather than the full contents of the page.

Usage

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Page	The page containing the Shared Block to include
Shared Block Key	The key of the shared block on the parent to include. If left blank, the first shared block on the page will be included.
Suppress Permission Errors	If checked and the user does not have permissions to view the included page, the macro will silently fail to render the page.

Purpose

This was a way of inserting content into multiple pages but not cluttering up the page tree in the sidebar.

Include Shared Block With Replacement Macro

Description

This macro is almost identical to the Include Page with Replacement macro with the difference that only the Shared Block on the page is inserted rather than the full contents of the page. As with the Include Page with Replacement, substitutions rules may be inserted into the body of the macro which get applied when the macro renders. Every line in the body of the macro represents a substitution rule and should conform to the pattern <delimiter>initial-string<delimiter>final-string<delimiter>. The default delimiter is the forward slash, "/", but it can be changed as one of the macro properties. The initial string is interpreted as a Java regular expression. Care should be taken in defining the regular expression as the substitution can render the underlying representation invalid and the content will not render at all.

Here is an example that changes Monday to Tuesday and January to February.

/Monday/Tuesday/
/Januray/February/

Usage

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Page	The page containing the Shared Block to include
Shared Block Key	The key of the shared block on the parent to include. If left blank, the first shared block on the page will be included.
Delimiter	The delimiter to bound and separate the text to be replaced and the replacement text.
Suppress Permission Errors	If checked and the user does not have permissions to view the included page, the macro will silently fail to render the page.

Purpose

As with the Include Page With Replacement, this macro was created to assist in creating code tutorials so that boiler plate content could be created and inserted but the context, such as the name of the example project, could be inserted. One advantage of the Shared Blocks is that they do not clutter up the page tree in the sidebar.

Shared Block Macro

Description

This macro is almost identical to the Confluence Excerpt macro with the difference that you can create multiple shared blocks on a page.

Usage

To use the macro, insert the macro using the normal Confluence methods, then adjust the parameters as needed.

Parameters	Description
Shared Block Key	A string to uniquely identify the shared block on the page.
Allow Anonymous Access	If checked, this content can be included and seen on pages when the viewer does not have permissions to the page with the shared block. This is useful to create a page with multiple shared blocks included elsewhere, but the host page can be hidden so as to not clutter up the page tree in the sidebar.
Hidden	If checked, the shared block will not be rendered except when included via the Include Shared Block, Include Shared Block With Replacement or Help Text from Shared Block. The primary purpose is to place some help text at the bottom of the page which the Help Text from Shared Block can use.

Purpose

This macro provides a way of identifying content that can be inserted elsewhere.

Home