This page last changed on Mar 05, 2007 by jnolen.
 | XWork plugin modules are available in Confluence 1.4 and later. |
XWork plugin modules enable you to deploy XWork / WebWork actions and views as a part of your plugins.
The XWork Plugin Module
Each XWork module is deployed as a plugin module of type xwork and contains one of more XWork package elements.
Here is an example atlassian-plugin.xml file containing a single XWork module:
<atlassian-plugin name='List Search Macros' key='confluence.extra.livesearch'>
...
<xwork name="livesearchaction" key="livesearchaction">
<package name="livesearch" extends="default" namespace="/plugins/livesearch">
<default-interceptor-ref name="defaultStack" />
<action name="livesearch"
class="com.atlassian.confluence.extra.livesearch.LiveSearchAction">
<result name="success" type="velocity">
/templates/extra/livesearch/livesearchaction.vm
</result>
</action>
</package>
</xwork>
</atlassian-plugin>
- the xwork element has no class attribute.
- beneath this element, multiple package elements can be specified. These are standard XWork package elements, just as you would specify in xwork.xml.
Writing an Action
For information on how to write a WebWork action, please consult the WebWork documentation.
WebWork actions must implement com.opensymphony.xwork.Action. However, we recommend you make your action extend ConfluenceActionSupport, which provides a number of helper methods and components that are useful when writing an Action that works within Confluence.
Other action base-classes can be found within Confluence, but we recommend you don't use them - the hierarchy of action classes in Confluence is over-complicated, and likely to be simplified in the future in a way that will break your plugins.
Accessing Your Actions
Actions are added to the XWork core configuration within Confluence, which means they are accessed like any other action!
For example, given the above atlassian-plugin.xml, the livesearch action would be accessed at http://yourserver/confluence/plugins/livesearch/livesearch.action.
Notes
Some issues to be aware of when developing or configuring an XWork plugin:
- Your packages should almost always extend the default Confluence package. It is useful to be aware of what this provides to you in the way of interceptors and result types.
- You can give your packages any namespace you like, but we recommend using /plugins/unique/value - that is prefixing plugin packages with /plugins and then adding a string globally unique to your plugin. The only name you can't use is servlet as the /plugins/servlet URL pattern is reserved for Servlet plugins.
- Views must be bundled in the JAR file in order to be used by your actions. This almost always means using Velocity views.
- It is useful to be aware of the actions and features already bundled with Confluence, for example your actions will all be auto-wired by Spring (see Accessing Confluence Components From Plugin Modules) and your actions can use useful interfaces like PageAware and SpaceAware to reduce the amount of work they need to do.
Example
The LiveSearch example is a neat example of an Ajax-style Confluence plugin which uses a bundled XWork module to do it's work:
Find this example in the /plugins/macros/livesearch directory within your Confluence distribution.
Is there a way to modify the livesearch macro so that it only searches in a certain space?
thanks in advance

Posted by avinash at Nov 02, 2005 22:16
|
At this point, not without making modifications to the livesearch macro itself. If you would like to see this feature, please raise a feature request via http://jira.atlassian.com
Regards,
-Daniel

Posted by daniel@atlassian.com at Nov 03, 2005 16:21
|
There's actually a bug for that here....
http://jira.atlassian.com/browse/CONF-4546
but it doesn't seem to be working in 2.1.4 as indicated there.

Posted by andriven at Mar 17, 2006 11:40
|
Since Confluence 2.1 you can specify a spaceKey parameter. For example:
{livesearch:spaceKey=ds}
will list only pages from the Demonstration Space
Cheers,
Jens

Posted by jens@atlassian.com at Apr 12, 2006 00:30
|
I'm creating a plugin. the XWork part is not working properly. The following is part of plugin.xml file.
<package name="news" extends="default" namespace="/plugins/news">
<default-interceptor-ref name="defaultStack" />
<action name="/plugins/news/preview" class="com.icsynergy.confluence.news.NewsAction" method="preview">
<result name="preview" type="velocity">
/plugins/news/templates/preview.vm
</result>
</action>
</package>
The problem happens when to forward to the preview result. I got the following exception:
 |
org.apache.velocity.exception.ResourceNotFoundException: Unable to find resource '/ /plugins/news /plugins/news/templates/preview.vm ' |
Can anyone give me some idea? Thanks

Posted by vincent.chen at May 02, 2006 13:31
|
Few comments:
Namespacing
You have specified the /plugins/news namespace, and still prepended the namespace to the action name ... this would mean the action is at http://confluence.atlassian.com/plugins/news/plugins/news/preview.action ... I assume you want http://confluence.atlassian.com/plugins/news/preview.action, so just remove plugins/news/ from the begining of the action element's name attribute.
Whitespace
I would remove the whitespace around the result contents and have <result...>/plugin/news/templates/preview.vm</result> instead.
VM Location
Finally, check that the preview.vm file is in the "plugins/news/templates" folder in your jar (simply open the jar in any zip viewer). If it isnt there then adjust the deployment path or your location in the result body.

Posted by dhardiker@adaptavist.com at May 02, 2006 13:44
|
Thanks, Dan. After removed white space and changed the action name, it works.
My action config now is:
<package name="news" extends="default" namespace="/plugins/news">
<default-interceptor-ref name="defaultStack" />
<action name="newsEdit" class="com.icsynergy.confluence.news.NewsAction">
<result name="success" type="httpheader">
<param name="status">204</param>
</result>
<result name="preview" type="velocity">templates/preview.vm</result>
</package>
While, in the sample plugin dynamictasklist, the action config is:
<xwork name="tasklistaction" key="tasklistaction">
<package name="dynamictasklist" extends="default" namespace="/plugins/dynamictasklist">
<default-interceptor-ref name="defaultStack" />
......
<action name="addTask" class="com.atlassian.confluence.extra.dynamictasklist.TaskListAction" method="addTask">
<result name="success" type="velocity">/templates/extra/dynamictasklist/status.vm</result>
</action>
In my case, the actual action URL is built by ActionNameSpace+ResultURL, while in dynamictasklist plugin it is ResultURL. Why is it diffrent?

Posted by vincent.chen at May 02, 2006 16:23
|
In dynamictasklist the .vm file path starts with '/'. That is a signal for the XWork engine to start from the top of the webapp's (in this case Confluence's) context path. If you want the same result, just add '/' to the start of your result URL.

Posted by david@randombits.org at May 02, 2006 19:09
|
The problem might be the white space? It seems that the result entry should not have any whitespace if the result type is velocity. If the first character is not "/", then XWork will prefix the namespace string to the result URL.

Posted by vincent.chen at May 03, 2006 10:37
|
The livesearch plugin doesn't seem to work for me anymore after upgrading from 2.1.5 to 2.2.9. Very sad, because me and my colleagues love it 
I'm not a java expert but this does pop up in the logs:
If anyone can advise me on how to fix this, please let me know!

Posted by menso at Oct 23, 2006 15:03
|
Hi Menso,
Where did you download your livesearch plugin from?
I checked the latest source for the livesearch plugin within Confluence source code and it is not using DWR for its AJAX requests.
Can you provide us with the livesearch plugin jar you are using?
Please put your reply in a support request at http://support.atlassian.com and we'll handle it there.
Cheers,
Dave

Posted by dave@atlassian.com at Oct 26, 2006 23:29
|
Those messages are generated by the Advanced Search plugin - and can be ignored as the assumptions it makes are correct. In a later release a <signatures> section may be added to the dwr xml.
This would not stop the livesearch plugin from working.

Posted by dhardiker@adaptavist.com at Oct 27, 2006 04:47
|
The LiveSearchAction plugin is kind of useless as an example, since most of the implementation is actually done in SiteSearchAction (the source code for which is not availalbe in the examples directory). Is there something else I can look at as an example of how to implement an Action?

Posted by mattz at Nov 03, 2006 15:14
|
If you mean "how to implement an Action class", that's really easy. A Confluence action has three characteristics:
- It extends com.atlassian.confluence.core.ConfluenceActionSupport.
- It has an execute() method that returns a result String. The method gets called when the action URL gets a request, and the result String is matched against the results in atlassian-plugin.xml to forward to a Velocity template. Predefined results are constants in ActionSupport - SUCCESS, ERROR, INPUT, etc.
- It has setFoo() methods called by Spring to inject dependencies and by Webwork to set query parameters, and getBar() methods called by Velocity when you write "$action.bar".
An extremely short example looks like this:
public class TestAction extends ConfluenceActionSupport
{
private PageManager pageManager;
private long pageId;
public String execute() {
return SUCCESS;
}
public String getPageCreator() {
return pageManager.getPage(pageId).getCreatorName();
}
public void setPageManager(PageManager pageManager) {
this.pageManager = pageManager;
}
public void setPageId(long pageId) {
this.pageId = pageId;
}
}
Accessing this action via test.action?pageId=12345 will run the execute() method, forward to the Velocity template mapped to the 'success' result, and allow you to write $action.pageCreator in Velocity to retrieve the page creator for the page with the given pageId.
There are hundreds of actions in the Confluence source code, if you want to see more complicated examples. The mapping from Actions to Velocity in Confluence is done via the xwork.xml file.

Posted by mryall at Nov 22, 2006 22:47
|
|