| Table of Contents | ||||||||
|---|---|---|---|---|---|---|---|---|
|
Description
Allows Provides a user form with input of parameters fields before rendering the body of the macro. Parameters Form fields will be used to replace variables in the body prior to rendering. Parameters Field values can be provided by user interaction, Prepre-defined variables, or request parameters. Any text in the macro body that begins with $ immediately followed by a key found in the replace parameter list of comma separated key:value:description triplets will (see Field types for details) will be replaced by the value. Normally, values will be provided by a user submitting a form from the page based on the replace parameter. The default value is specified in the key:value:description tripletDefault values can be specified.
This macro may have restricted use for security reasons. See CMSP and consult with your administrator for details.
| Section | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Parameters
...
- key is the parameter name. It must not be blank or contain blanks. Avoid special characters.
- value is the initial replacement value. If not provided, blank will be used.
- description is descriptive text used to provide prompt text for the parameter. If not provided, the key will be used. Line breaks with leading space ( <br>) and required spaces ( ) are supported.
...
- ^attachment - The rendered html is exported as an attachment to the current page.
- page^attachment - The rendered html is exported as an attachment to the page name provided.
- space:page^attachment - The rendered html exported as an attachment to the page name provided in the space indicated.
- filename - The rendered html is exported as a file located in confluence home directory/script/filename. Subdirectories can be specified.
Replacement keys are allowed in this field and will be replaced with values.
...
- new - (default) Creates new version of the attachment. For file based exports 'new' has the same effect as 'keep'.
- replace - Replace (overwrites) existing rendered html and, for attachments, removes all previous versions! To replace an existing attachment, the user must be authorized to remove attachments for the page specified.
- keep - Only creates an new export if an existing export of the same name does not exist. An existing attachment will not be changed and an existing file will not be updated.
...
| Include Page | ||||
|---|---|---|---|---|
|
Field Types
See Field types.
Advanced capabilities
| Tip | ||
|---|---|---|
| ||
Release notes 2.0 shows some examples of advanced capabilities. |
Entry fields
By default, parameter entry fields are text fields. By providing additional information, other entry fields are possible. The entry field type and other options for a replacement parameter are specified on the replace parameter as additional portions of the replacement parameter entry - key:value:description:type:number:... . The first 3 parts are described above. The additional parts are described next:
type
...
. |
...
Append -required to the field type to ensure a non-blank value is selected or specified.
Append -disabled to the field type to disable input on the field.
Append -end to the field type to end a group previously started with the group type.
Append -more to the field type to initially hide the parameter until the user requests to view more parameters. This allows for basic and advanced parameters to be on the same form with display under user control.
Unrecognized types are ignored.
The remaining colon (:) separated entries are interpreted in a type specific manner.
- text type
- input size - Default is inputSize parameter. This allows for individual text fields to have a different value.
- textarea type
- number of rows - Default is 5 rows to display.
- number of columns - Default is to be as large as the containing area allows.
- radio, checkbox, select, and select-multi types
- number of rows - used to control the display for some field types that can span multiple rows. The default is 1 except for a default of 5 for select-multi type. A negative value will be interpreted as the number of entries per line for radio and checkbox field types.
- value:text - Subsequent pairs represent entry values and entry text for options needed for radio, checkbox, and select field types. The value becomes the replacement value for the option. The text is what appears to the user. If the text is blank, the value will be used. Note when specifying the initial value for this parameter, use the choice value and not the text. For select fields, select groups can be specified using special value:text pairs indicated by @group:text and @end:text where text is the group name. If text is blank, the group will not be named and a line will be drawn instead.
- integer and float types
- lowerBound:upperBound - if a bound is not specified, no check will be done. Bounds must be valid integer or float values. Bounds are inclusive (less than or equal). Both bounds must be specified for integer-select.
- date type
- lowerBound:upperBound:dateFormat - if a bound is not specified, no check will be done. Bounds must be valid date values. Bounds are inclusive (less than or equal). Date format defaults to the dateFormat parameter. See Date Format for how to specify this value.
- group type
- width - Width of the group area in percent(%) or pixels. Default is to use as much space as needed by group elements.
Examples:
- Horizontal radio button - gender:M:Gender:radio::M:Male:F:Female
- Single select with 12 lines - month:12:Month:select:12:1:Jan:2:Feb:3:Mar:4:Apr:5:May:6:Jun:7:July:8:Aug:9:Sept:10:Oct:11:Nov:12:Dec
- Checkbox (value same as text) - day::Day of$nbsp;week:checkbox-required:7:Sunday::Monday::Tuesday::Wednesday::Thursday::Friday::Saturday
...
The html, representing the rendered body of the macro, can be exported to a page attachment or to the file system. This enables the dynamic content to be captured at a point in time for later viewing. An attachment or file created by this type of export, can be used on a page by including it in the body of an html macro. For example: {html:script=^bobs.html} {html}. If exportVersion=keep is used, the referenced attachment is already there, and the HTML macro is authorized for use on the page, then the macro body will not be rendered and the attachment will be included instead. This enables caching and automation capabilities.
Recursive use
Three When using wiki markup, identical macros run, run1, and run2 are provided to enable recursive use of the macro. Request parameters
Parameters are passed as request parameters on the URL, enabling automatic running of content based on the incoming parameters.
Request parameters
Request parameters are case sensitive. Look at the url after pressing the run button or after an autorun. This url can be used as a link. Usually the url contains the page title. If the page title contains special characters or you wish to have a more persistent link (that survives page renames or moves), then Confluence's alternate page view url can be used: .../pages/viewpage.action?pageId=......... The view url can be constructed by looking at the url after going to Tools->Info. Tiny links cannot be used (CONF-11594 ). Each parameter is represented by a request parameter composed of _ separated elements:
...