| Div | ||
|---|---|---|
| ||
On this page
|
...
|
...
|
...
|
...
|
...
|
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.
...
|
Parameters
| 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
- text - value is displayed in a text box. (default)
- textarea - value is displayed in a multi-line text area.
- radio - values are displayed as radio buttons.
- checkbox - values are displayed as checkboxes.
- select - values are displayed as a select list.
- select-multi - values are displayed as a multiple select list.
- integer - value is displayed in a short text box. Integer values are long integers.
- integer-select - value is displayed in a select list with automatically generated values based on lower and upper bounds. Difference must be less than 10000.
- float - value is displayed in a short text box. Float values are double floats.
- date - value is displayed in a short text box.
- output - value is displayed as output text.
- hidden - value is hidden - the field does not show up in the parameter table.
- group - pseudo field used for grouping of other fields so they display as a single row. A group field indicates the start of fields included in the group. Groups are automatically ended by the next group field or append -end to the type field for the last field in the group.
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.
...
- input size - Default is inputSize parameter. This allows for individual text fields to have a different value.
...
- number of rows - Default is 5 rows to display.
- number of columns - Default is to be as large as the containing area allows.
...
. |
...
- 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.
...
- 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.
...
- 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
Export
The htmlHTML, 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 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 URL after pressing the run button or after an autorun. This url URL can be used as a link. Usually, the url 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 URL can be used: .../pages/viewpage.action?pageId=......... The view url can be constructed by looking at the url 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:
- run - constant
- id - id associated with this run instance - see the id parameter
- parameter key - the first component of the key:value:description triple
...
The group pseudo field type does not result in a requestParameter. The request parameter representation can be controlled using the requestPrefix and requestAction parameters.
Fields that allow multiple selections
Checkbox and multi-select fields allow multiple selections and are more complex. Special considerations are:
- If the initial value needs to be specified with more than one selection, the value must be a single quoted, comma-separated list of choice values.
- The replacement value for such a field is a single quoted, comma-separated list of single-quoted selected values.
- Checkbox and multi-select entries appear multiple times as a request parameter with a value matching values that have been selected.
- Embedded single quotes are doubled.
Translation
Text visible to form users (field titles, parameter descriptions, and choice text) can be provided so that it is translatable by using @ followed by a key to the translatable resource. This means that the form will show text specific to the user language setting.
- Any valid i18n key defined in Confluence can be used (example: @dashboard.name)
- Custom keys (beta - subject to change based on user feedback)
- Can be defined and accessed via @custom.example.key.
- This requires customization that requires your system administrator. Custom keys must be added to a property file named org.swift.confluence.run.custom.properties. Appropriate language translations property files named after the language abbreviation (example: org.swift.confluence.run.custom_fr.properties) and inserted into the plugin add-on jar under i18n directory.
Export
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:
| No Format |
|---|
{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.
Usage
Usage
The following examples are given in wiki markup format so it is easy to copy and paste. Use Insert ->Markup in your Confluence editor to paste in the examples.
Run example
Run a script
| No Format |
|---|
{run:replace=greeting:Hello,who:Bob}
{beanshell}
System. out.println("$greeting $who");
{beanshell}
{run}
|
Run a SQL query
| No Format |
|---|
{run:replace=first:Bob:First name|exportFile=^bobs.html|titleExport=Archive result}
{sql:datasource=NameDS}
select * from NAMES where first='$first'
{sql}
{run}
|
...