Create an include page

You do not have to create a special page as every page will work as an include page. But you may insert parameter placeholders which are replaced with content when displayed with Param Include macro. And you can add information for users to your page with Param Include Description Macro.

Parameter placeholders

An include page can but don't have to contain parameters. A parameter name enclosed dollar sign. The sign in between can consist of letters, decimals and the underscore. The name has a minimal length of one sign.

If you don't want to name your parameters, numbered parameters will work, too.

Preformatted Parameters

You can format parameters so that the formatting is applied to values when using the include page. Please pay attention that the formatting has to surround the whole parameter name. Starting or ending the formatting within the parameter will break the parameter detection and your include page won't work.

Describing include pages

Include Description macro let you add information for the users to an include page. The content of this macro is displayed as an info box when viewing the page directly. It is hidden when the page is included by the Param Include macro. Multple description macros are allowed, but only the first is display when listing pages with the Param Include Catalog macro. You can use this to provide general information in the first description and additional explanation in other description macros. Or you can put a description next to every parameter in the page to descripe its purpose.

Parameter inheritance

Param Include macro can be nested i.e. an include page ("inner inclusion") can be used within another one ("outer inclusion"). When nesting, the parameters are inherited: Parameters declared in the outer inclusion are known when processing the inner inclusion. You can use this feature to combine different pages with parameter placeholders into new include pages for easy usage, while preserving the dynamic replacement of parameter placeholders for each outer and inner include page. A parameter don't have to be used in the outer macro. It can be declared as pass through parameter for the inner include page.

Example:
"Company Header" is a page containing three parameter placeholders: $product_name$, $product_version$ and $vendor_name$. It is embedded into a new page without declaring the three parameters. When using this new page with Param Include, all three parameters have to be declared: $product_name$ is both used by the outer inclusion and by th inner inclusion "Company Header". $product_version$ and $vendor_name$ are passed through to the inner inclusion and used by "Company Header" exlusive.

Please note, that you will receive an error message when viewing the outer include page directly. The macro will complain that an parameter declaration for the inner inclusion is missing. You can ignore this as the parameter can be provided when including the outer page using Param Include.

Labeling Pages as Include Pages

As every page can be included, pages intended to be included have to be marked somehow. The Param Include plugin uses the build in label system of Confluence for this purpose. Every page labeled with "include" is regarded as a include page. This label is used by the Param Include Catalog plugin to list all include pages. But a page don't have to be labeled to be included with the Param Include macro.