Scriptix

Contents

Dedication

This plugin is dedicated to my new daughter: Keira Isabelle Hardiker. She was born a healthy 9lbs 3.5oz on Friday afternoon. The bulk of this plugin was written while waiting to go into theatre to deliver her, and so she allowed me the time to get it as far as I have.

Description/Features

Requires Mustang This plugin currently requires Java SE 6 as it uses the javax.script JSR 223 libraries.

Scriptix Wiki We've recently started setting up a Scriptix Wiki and will be building a repository of useful scripts on there. We'd love to see some community contributions so if you have a script that others might find useful (even for learning purposes) please contribute!

This plugin taps into the standardised scripting API that comes with Java 6 and provides a nice platform for writing what might be considered to be advanced user macros. This plugin is highly useful when writing a Java plugin seems overkill, and when all you need to do is a bit (or a lot!) of scripting. The following can all be achieved with this macro:

• Parsing of users, and adding them to groups based on their email address (e.g. joe@abba.com would end up in the comp-abba group).
• Composition and rendering of wiki markup
• Complex structures which are awkward to achieve in Velocity

With a bit more work the following are possible:

• Multiple searches, with the results cross referenced – the common results returned and ordered by a metadata key.
• Listing of all the user's who haven't logged in for x days (pulling that data from Crowd), and emailing them with a warning that their account has been inactive and may be deleted.
• Listing of child pages, hiding those with certain keys, sorting by a metadata field.
• A complete redesign of the blog-posts macro to make the output ultimately flexible (the markup can be completely rewritten).

Due to the limits on my time I've not been able to give this plugin any justice, and as we have an immediate need it will be advanced over the coming months.

Installation

Mustang Required This plugin can run on Java 6 out of the box. For Java 5, I've come across claims that you can install the javax.script libraries from the JSR 223 Reference Implementation, but I keep coming up against "UnsupportedClassVersionError" issues. If you find a way, please let me know!

1. Install any of the CODEGEIST:scripting language libraries you want into confluence/WEB-INF/lib – JavaScript is included in the Reference Implementation.
2. Install the plugin from the Plugin Repository

Available Scripting Languages

The libraries for the languages you want to support all need placing in confluence/WEB-INF/lib.

The libraries above can be found in the "lib" folder of the source. Feel free to add others!

Jython Notes

Confluence (2.5.x and 2.6 at least) already have jython-2.1-forked.jar in confluence/WEB-INF/lib. This must be deleted in order to avoid it being loaded by the classloader instead of any other version you install.

Jython 2.2b2 also has additional resources not kept in the jar, to access these the Java property python.home must be set correctly before starting Confluence. This can be done in bin/startup.sh as follows.

export JAVA_OPTS="-Xmx768m -XX:MaxPermSize=128m -Dpython.home=/usr/local/jython/jython2.2b2"

Compiling from Source

Mustang Required You must execute Maven 2 through a Java 6 JDK to compile, as it needs the javax.script classes to do so.

1. Download the source
2. Run mvn package along side pom.xml
3. Upload resulting jar in the target directory

You can also run mvn idea:idea to get IDEA project files to start from for editing.

Usage

The macro essentially evaluates the script and then outputs what ever is in the "output" variable at the end of execution. You can use the components available along the way.

Getting started is quick and easy - the default security settings allows only access to read only and public safe components, specifically just the subRenderer and macro data.

Example 1: Hello World

{scriptix}{scriptix}

Well it doesn't get any more basic than that! It evaluates the following default script:

output = 'You will need to put some JavaScript in here!'

Output

You will need to put some JavaScript in here!

Example 2: Rendered Output

{scriptix}
var table = "|| heading 1 || heading 2 ||\n| value 1 | value 2 |\n| value 3 | value 4 |";
output = new String( scriptix.subRenderer.render(table, macro.renderContext) );
{scriptix}

I'm not sure why the new String() is needed, but I've been limited with time to toy.

Output

heading 1	heading 2
value 1	value 2
value 3	value 4

Example 3: Macro Access

{scriptix:your-name=Joe Burns}
output = "Your name is: "+ macro.params.get('your-name');
{scriptix}

This shows how to access the parameters from the macro calling the script, you can also access the body and renderContext. If the script is in the configuration and is not overridable, then the body can contain what you want – XML for parsing if you like!

Output

Your name is: Joe Burns

Example 4: Group Listing

For this we will need to change the security settings.

1. Go to the Administration console
2. Select Scriptix from the left
3. Edit the DEFAULT configuration (if you create one, you will need to specify the id in the macro parameters)
4. Ensure that "groupManager" is selected, or that the component restrictions are untick

{scriptix}
// Init
var output = "";
// Iterate through each group
var groupIter = scriptix.groupManager.getGroups().iterator();
while (groupIter.hasNext()) {
  output += "* "+ groupIter.next().name +"\n";
}
// Render the output
output = new String( scriptix.subRenderer.render(output, macro.renderContext) );
{scriptix}

Output (on a fresh install)

• confluence-users
• confluence-administrators

Security

You can choose which scripting engines are available, and force it to a certain default engine. You can set a default script, and select it to be optionally overridden. You can choose the components available. You can set the spaces which it can run under.

All of this is on a per-configuration basis, referenced by id – with a default to fall back on in case the id doesn't match.

Expandability

This is only the tip of the iceberg, if I had more time then this would be much further along. Over the coming months you'll see this flesh right out as I add more and more components, with more and more helpers, and more and more examples.

So where to next?

I want to increase the available components, get it searching, get it mailing and get it accessing other plugin's managers.

I would also like to try and find a way of getting the javax.script libraries running on Java 5 ... everywhere says it's possible, but no where says how.