Run Plugin

Name Run Plugin Vendor Bob Swift and other contributors Authors Bob Swift Homepage http://confluence.atlassian.com/display/CONFEXT/Run+Plugin Issue Management http://developer.atlassian.com/jira/browse/RUN Categories Content Macros Version 1.0.0 Availability Confluence v2.5.2 to v2.10-m1 State Stable Support License Freeware / Open Source (BSD) Price Free Release Docs http://confluence.atlassian.com/display/CONFEXT/Run+Plugin Java API Docs n/a Download Source http://svn.atlassian.com/svn/public/contrib/confluence/run-plugin/trunk Download JAR run-plugin-1.0.0.jar

Additional Information JVM requirements Java 1.4 and above Installation requirements Confluence Repository Client or upload from Confluence's administration console. Cannot be installed in /WEB-INF/lib Description Dynamic content based on substitution of parameters provided by page user. Macro displays a dialog for substitution parameters and then renders the body contents after substitution.

Downloads Date 2008-Mar 2008-Apr 2008-May 2008-Jun 2008-Jul 2008-Aug 2008-Sep Hits 49 103 82 89 84 65 13 Compatibility Plugin 2.2 2.3 2.4 2.5 2.6 2.7 2.8 Tested release 1.0.0 2.5.2, 2.7.1, 2.8 0.7.0 2.2.9, 2.5.2, 2.7.1

Documentation

• Also see the Notation guide on your installation.

Allows user control over the rendering of the body of the macro. Parameters can be provided and they will be used to replace parameters in the body prior to rendering. Parameters can be provided as request parameters on the URL, enabling automatic running of content based on the incoming parameters. Any text in the macro body that begins with $ immediately followed by a key value found in the replace parameter list of comma separated key:value:description triples will be replaced by the value. Until the documentation can be improved, look at the url after pressing the run button or after an autorun.
Some pre-defined variables are available for use:

• $current_user_id will be replaced with the current logged in user's id or blank if not logged in
• $current_user_name will be replaced with the current user's full name or blank if not logged in
• $current_user_email will be replaced with the current user's email address or blank if not logged in
• $page_title will be replaced with the page title of the page containing the macro
• $space_name will be replaced with the space name of the page containing the macro
• $space_key will be replaced with the space key of the page containing the macro
• $current_time will be replaced with the current date and time in the format specified by the dateFormat parameter

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}

Advanced capabilities: 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 identical macros run, run1, and run2 are provided to enable recursive use of the macro.

Parameters

• id - Optional way to identify this instance of the run macro. By default, a numeric id is automatically assigned based on the order of the macro on the page. The id is visible in the url after a button press.
• replace - A comma separated list of key:value:description triples. Any string containing a comma (,) or colon (:) must be enclosed in single quotes (').
  • key is the parameter name. This must be non blank.
  • value is the initial replacement value. If not provided, blank will be used.
  • description is text used to provide prompt text for the parameter. If not provided, the key will be used.
• inputSize - Size of the value entry fields. Default is 20.
• autoRun - Default is false. Set to true to render the macro body with the default parameter values.
• heading - Heading that appears before the buttons. Default is blank.
• prompt - Prompt text that appears above the parameters. Default is blank.
• titleRun - Title for the run button. Default is Run
• titleExport - Title for the export button. Default is Export. Exportfile parameter is required before the export button will show.
• titleExportFile - Title for the export file input field. Default is blank. This will only be shown if exportfile parameter value starts with a question mark (?).
• titleAttachmentComment - Title for the attachment comment input field. Default is blank. This will only be shown if attachmentComment parameter value starts with a question mark (?).
• hideParameters - Hide the parameters. Default is false.
• hideRun - Hide the Run button. Default is false.
• hideExport - Hide the Export button. Default is true unless exportFile is non-blank.
• exportFile - Location of the export partial html file representing the rendered macro body. For export to an attachment, the user must be authorized to add attachments to the page specified.
  • ^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.
• exportVersion - Defines the the versioning mechanism for exported html.
  • new - (default) Creates new version of the attachment. For file based exports 'new' has the same effect as 'keep'.
  • replace - Replaces (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.
• attachmentComment - Comment used for an exported attachment. If it begins with a question mark (?) then an entry field with this value will appear next to the export button. Replacement keys are allowed in this field and will be replaced with values.
• autoExport - Default is false. Set to true to have the rendered macro body automatically exported.
• showKey - Show the key. The key is shown after the value entry field. Default is false.
• dateFormat - Date format to use for replacement of $current_time. Default is server date format. The notation guides has informaiton on the format of this parameter.
• keepRequestParameters - Default is false. Set to true to keep existing request parameters on the url after button is pressed. All requests parameters will be retained if keepRequestIds is not specified. Otherwise, non-run macro request parameters and those references by the keepRequestIds parameter will be retained.
• keepRequestIds - List of run macro ids whose request parameters should be retained on the url after a button is pressed. button is pressed. This will be required for recursive use of this macro. Use of this parameter or keepRequestParameters parameter is required for recursive use of this macro.

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 Plugin. 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.

Usage

Run example

Run a script

{run:replace=greeting:Hello,who:Bob}
{beanshell}
System.out.println("$greeting $who");
{beanshell}
{run}

Run a SQL query

{run:replace=first:Bob:First name|exportFile=^bobs.html|titleExport=Archive result}
{sql:datasource=NameDS}
select * from NAMES where first='$first'
{sql}
{run} 

Release History

Version	Date	State	License	Price
1.0.0 (#4)	16 Apr 2008	Stable	Freeware / Open Source (BSD)	Free
Release Notes Atlassian Developer Network JIRA (4 issues) Key Pr Summary Updated Reporter Status RUN-14 Recursive use of run macro Apr 16, 2008 Bob Swift Closed RUN-13 Add ability to keep existing request parameters on button push Apr 16, 2008 Bob Swift Closed RUN-9 run macro to have some pre-defined (automatic) substitution values Apr 16, 2008 Ed Wittmann Closed RUN-8 Ability to use the run macro by submitting form Apr 16, 2008 Scott Farquhar (Devsuite) Closed Contributors Bob Swift — Developer
0.7 (#3)	26 Jan 2007	Stable	Freeware / Open Source (BSD)	Free
Release Notes Atlassian Developer Network JIRA (0 issues) Key Pr Summary Updated Reporter Status Contributors Bob Swift — Developer
0.6 (#2)	05 Oct 2006	Beta	Freeware / Open Source (BSD)	Free
Contributors Bob Swift — Developer
0.5 (#1)	16 Sep 2006	Beta	Freeware / Open Source (BSD)	Free
Contributors Bob Swift — Developer

Older history

Open Issues

Atlassian Developer Network JIRA (6 issues)
T	Key	Summary	Reporter	Assignee	Pr	Status
	RUN-1	More input choices? Drop down choice, checkboxes, radio button.	Patrice Saint-Louis	Bob Swift		Open
	RUN-5	Harmonize with the replace-and-render macro	James Mortimer	Bob Swift		Open
	RUN-11	result of run plugin to be exported to a PAGE as WIKI (a.k.a. an attachment as html)	James Mortimer	Bob Swift		Open
	RUN-15	Control over URL parameter prefix	David Dembo	Bob Swift		Open
	RUN-16	Pluging does not work if page title contains umlauts	Christian Vollrath	Bob Swift		Open
	RUN-17	new variable: $page_id (more useful than $page_title for SQL queries)	Vincent Kopa	Bob Swift		Open

Screenshots

Screenshots
Release 1.0.0	0.7 look