Wiki
Clone wikiKeysight Plugins For Atlassian Products / Confluence Plugins / Include Content Plugin
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.
Updated