Skip to Content

WritingComponents

Version 23.1 by Oana Florea on 2010/01/26
Warning: For security reasons, the document is displayed in restricted mode as it is not the current version. There may be differences and errors due to this.

Writing XWiki components

Invalid macro parameters used for the [toc] macro. Cause: [Failed to validate bean: [must be greater than or equal to 1]]. Click on this message for details.

This tutorial guides you through the creation of an XWiki component, which replaces the Plugin architecture and which is now the recommended way of writing XWiki modules. They should be able to execute any Java code and communicate with XWiki by using the existing XWiki (core) components, as well as being exposed to the XWiki documents scripting environment (velocity and groovy).

You should start by reading the Reference document on XWiki Components.

Warning

The tutorial below is slightly outdated since some changes have been brought to the Component Module since it was written. See the Reference document on XWiki Components for fresh information. This tutorial needs to be rewritten and duplicate with the Reference document removed.

Let's get started!

Enough talking, let's see some code!

In the followings we will guide you through writing a simple component, helping you to quickly get oriented in XWiki components world and explaining how it works.

Creating a XWiki component using maven

To simplify the three steps process of component creation in XWiki, and since the XWiki code lifecycle is based on maven, we have created a maven archetype to help create a simple component module with a single command, with respect to the XWiki architecture and components specific requirements.

  • download the archetype from here: xwiki-archetype-component-1.0-SNAPSHOT.jar (it will soon be uploaded on our maven repository).
  • use maven to install this file on your local repository by executing (make sure you replace path-to-jar-file with your own path):
mvn install:install-file -Dfile=<path-to-jar-file> -DartifactId=xwiki-archetype-component -DgroupId=com.xpn.xwiki.platform.tools -Dversion=1.0-SNAPSHOT -Dpackaging=jar
  • now you're ready to use maven to generate the xwiki component based on this archetype. Navigate to the directory where you want your component to be located and type:
mvn archetype:generate -DarchetypeGroupId=com.xpn.xwiki.platform.tools -DarchetypeArtifactId=xwiki-archetype-component -DarchetypeVersion=1.0-SNAPSHOT -DgroupId=<component-group-id> -DartifactId=<component-artifact-id>  -Dpackage=<component-package> -Dversion=<component-version> -Dpackaging=jar

where you replace component-group-id, component-artifact-id, component-package, component-version with the corresponding values for your component. To create a server XWiki Watch component, for example, we used -DgroupId=com.xpn.xwiki.products -DartifactId=xwiki-watch-component -Dpackage=org.xwiki.watch.component -Dversion=1.1-SNAPSHOT. Don't forget to follow the xwiki package names guidelines.

Now this will create a new maven module in a folder named component-artifact-id in your folder, with a default xwiki component inside. InformationNote that if your parent (current, from where you are executing maven) folder is the folder of a maven module (contains a pom.xml file), then the command above will fail unless the module is packaged as pom. If the project is packaged as pom, then the newly created module will be added in its modules list, and the parent of the newly created component module will be set to this project's pom.

The component explained

Assume, for the following explanations, that the package you used is org.xwiki.component

Navigating in the component project folder, you will see standard maven project structure like this:

pom.xml
src/main/java/org/xwiki/component/HelloWorld.java
src/main/java/org/xwiki/component/internal/DefaultHelloWorld.java
src/main/resources/META-INF/components.txt
src/test/java/org/xwiki/component/HelloWorldTest.java

which corresponds to the default files created: the HelloWorld interface (service), its implementation DefaultHelloWorld, a test class for this component HelloWorldTest, the component declaration file components.txt and the maven project pom file.

If we have a look in the pom, we see something like this:

<groupId>your-group-id</groupId>
 <artifactId>your-artifact-id</artifactId>
 <version>your-version</version>

which are the group, artifact and version you used when you created your component

<properties>
   <!-- TODO: remove this if you inherit a project that has the core version set -->
   <platform.core.version>1.8-SNAPSHOT</platform.core.version>
 </properties>

Failed to execute the [velocity] macro. Cause: [The execution of the [velocity] script macro is not allowed in [xwiki:Documentation.DevGuide.Tutorials.WritingComponents.WebHome]. Check the rights of its last author or the parameters if it's rendered from another script.]. Click on this message for details.

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected