Wiki source code of Creating an Extension

Last modified by Eleni Cojocariu on 2026/02/24 09:53

Manage
- Copy
Actions
- Export
- Print Preview
Viewers
- Source
- Children
- Content
- Attachments
- History
- Information
- Likes

version	line-number	content
1.2	1	{{box cssClass="floatinginfobox" title="Contents"}}
	2	{{toc/}}
	3	{{/box}}
	4
1.1	5	There are 2 types of Extensions:
4.1	6
25.3	7	* XAR Extensions: they are wiki pages packaged in a [[format that is called XAR>>documentation.xs.admin.exports.export-xar-format.format-specifications.WebHome]] (which stands for XWiki Archive). It's a ZIP file with a specific directory structure and an XML syntax to represent the wiki pages, along with a package metadata file.
1.1	8	* JAR Extensions: they are [[XWiki Components>>extensions:Extension.Component Module]] written in Java and packaged in a JAR.
	9
	10	= Creating a XAR Extension =
	11
25.3	12	The simplest strategy is to create the wiki pages in a running XWiki instance and then to [[export them as a XAR>>documentation.xs.admin.exports.export-xar-format.WebHome]].
1.1	13
	14	Note that those wiki pages can contain a lot of things:
4.1	15
1.1	16	* pure content,
22.2	17	* [[scripts>>Documentation.DevGuide.Scripting.WebHome]],
1.1	18	* applications (you can even use the [[Applications Within Minutes application>>extensions:Extension.App Within Minutes Application]] to help create some simple application to match your needs),
22.2	19	* [[wiki macros>>Documentation.DevGuide.Tutorials.WritingMacros.WikiMacroTutorial.WebHome]],
1.1	20	* ... and a lot more
	21
	22	== Building a XAR with Maven ==
	23
3.2	24	If you wish to save your XAR sources under [[version control>>https://en.wikipedia.org/wiki/Version_control]] and be able to build it, we recommend using [[Maven>>https://maven.apache.org/]]. There's a plugin called the [[XAR Maven plugin>>dev:Community.XARPlugin]] to help with this.
1.1	25
	26	Here's how you can save the XAR you got when exporting pages from the wiki into your source tree:
4.1	27
1.1	28	* create a ##[ROOT]## directory to be the root of your Maven project
	29	* add a ##pom.xml## file (see below for more details)
	30	* unzip the XAR into the ##[ROOT]/src/main/resources## directory and remove the ##package.xml## file (you don't need to save it since the Maven XAR plugin will regenerate it)
	31	* run ##mvn xar:format## to pretty format the wiki pages (XML files)
	32	* run ##mvn install## to automatically perform validation and generate the XAR
	33
	34	=== Authoring a Maven POM for a XAR ===
	35
6.1	36	Here's an example of how your ##pom.xml## could look like (adapt to your need).
1.1	37
6.1	38	Notice the usage of a Contrib Parent POM which automatically provides configuration for lots of things. To know more about how to use the Contrib Parent POM check the [[documentation for it on GitHub>>https://github.com/xwiki-contrib/parent]].
	39
1.1	40	{{code language="xml"}}
	41	<!--
	42	* See the NOTICE file distributed with this work for additional
	43	* information regarding copyright ownership.
	44	*
	45	* This is free software; you can redistribute it and/or modify it
	46	* under the terms of the GNU Lesser General Public License as
	47	* published by the Free Software Foundation; either version 2.1 of
	48	* the License, or (at your option) any later version.
	49	*
	50	* This software is distributed in the hope that it will be useful,
	51	* but WITHOUT ANY WARRANTY; without even the implied warranty of
	52	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
	53	* Lesser General Public License for more details.
	54	*
	55	* You should have received a copy of the GNU Lesser General Public
	56	* License along with this software; if not, write to the Free
	57	* Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
	58	* 02110-1301 USA, or see the FSF site: http://www.fsf.org.
	59	-->
	60
	61	<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
	62	<modelVersion>4.0.0</modelVersion>
	63	<parent>
	64	<groupId>org.xwiki.contrib</groupId>
	65	<artifactId>parent-platform</artifactId>
25.1	66	<version>14.10</version>
1.1	67	</parent>
	68	<groupId>org.xwiki.contrib</groupId>
	69	<artifactId>your-extension-id</artifactId>
	70	<version>1.0-SNAPSHOT</version>
	71	<name>Your extension's name</name>
	72	<packaging>xar</packaging>
	73	<description>Your extension's description</description>
	74	<scm>
	75	<connection>scm:git:git://github.com/xwiki-contrib/(your extension id).git</connection>
	76	<developerConnection>scm:git:[email protected]:xwiki-contrib/(your extension id).git</developerConnection>
	77	<url>https://github.com/xwiki-contrib/(your extension id)</url>
	78	</scm>
	79	<developers>
	80	<developer>
	81	<id>scm id of developer 1</id>
	82	<name>Full Name of developer 1 as registered on xwiki.org, e.g. Vincent Massol</name>
	83	</developer>
	84	...
	85	<developer>
	86	<id>scm id of developer N</id>
	87	<name>Full Name of developer N as registered on xwiki.org, e.g. Vincent Massol</name>
	88	</developer>
	89	</developers>
	90	<properties>
	91	<!-- Don't check for API backward-compatibility here since there's no Java code. -->
	92	<xwiki.revapi.skip>true</xwiki.revapi.skip>
4.1	93
1.1	94	<!-- The Extension name. If not defined, the <name> property is used -->
	95	<xwiki.extension.name>Your extension's name</xwiki.extension.name>
4.1	96
1.1	97	<!-- The extension's category -->
	98	<xwiki.extension.category>application</xwiki.extension.category>
4.1	99
	100	<!-- Issue management -->
	101	<xwiki.release.jira.skip>false</xwiki.release.jira.skip>
5.1	102	<xwiki.issueManagement.jira.id>(your jira project id)</xwiki.issueManagement.jira.id>
1.1	103	</properties>
	104	</project>
	105	{{/code}}
	106
8.4	107	See the section about Metadata below to understand what information you need to provide in your POM.
	108
25.1	109	== Choosing the Parent POM version ==
	110
	111	You need to pay attention to the version of the dependencies you're going to use, and more specifically the version of your parent POM.
	112
	113	Recommendations:
25.2	114
25.1	115	* If you wish your extension to be used by the maximum number of XWiki users you need to use the oldest dependencies version for which you extension still works.
	116	* Try not to use a version higher than the current LTS version, since most users of XWiki in production will be use the LTS version.
	117	** When using a LTS version, use the first version in the LTS branch. For example if the last LTS version of XWiki is 14.10.12, use a parent POM of 14.10.
	118
	119	Also, there are sometimes bug fix releases of the parent POM (in the form of ##X.Y-Z## for the version), so make sure to always pick the latest one. For example don't pick ##14.0## but ##14.0-1## if the [[latest released tag>>https://github.com/xwiki-contrib/parent/tags]] for the 14.0 branch is ##14.0-1##.
	120
	121	Note that LTS parent POMs are [[always provided>>https://github.com/xwiki-contrib/parent]]. In case the version you want is not listed you can:
25.2	122
25.1	123	* Use the closest LTS as parent but use a different version for the dependencies
	124	* Ask for it to be released in the Mailing List
	125
8.4	126	= Creating a JAR Extension =
	127
	128	XWiki has a notion of [[Components>>extensions:Extension.Component Module]], and this is how it provides extensibility at the level of Java. XWiki itself is written as a set of Components. This allows extension writers to author Components that can replace (i.e. override) existing Components or add new Components to the system.
	129
	130	Here are some examples:
	131
	132	* [[Add a new Macro>>rendering:Main.ExtendingMacro]],
22.2	133	* [[Write a Listener>>Documentation.DevGuide.Tutorials.WritingEventListenerTutorial.WebHome]],
8.4	134	* [[Implement a new wiki markup syntax>>rendering:Main.Extending\|\|anchor="HAddinganewSyntax"]],
	135	* ... and a lot more
	136
22.2	137	Follow the [[Creating an XWiki Component tutorial>>Documentation.DevGuide.Tutorials.WritingComponents.WebHome]] to learn how to both develop a Component and use Maven to build it.
8.4	138
8.5	139	= Extension Metadata =
8.4	140
1.1	141	It's important that you set the following information as they'll be used by XWiki's Extension Manager when the extension is installed in XWiki (see below):
4.1	142
13.1	143	* Extension id (##<groupId>## and ##<artifactId>##), e.g. ##org.xwiki.contrib.blog## and ##application-blog-ui##.
	144	* Name. This is the user-friendly name of your extension and it's displayed on http://extensions.xwiki.org. Specify it using the ##<xwiki.extension.name>## maven property. E.g. ##Blog Application##.
	145	* Description. Keep it to one sentence. It's displayed on http://extensions.xwiki.org.
1.1	146	* Developers
1.3	147	* Category (using ##<xwiki.extension.category>##). Valid values are [[listed here>>extensions:Extension.Repository Application\|\|anchor="HCategories"]].
1.1	148	* SCM (Note: this is also required by the Maven Release plugin if you use it to release your extension)
7.1	149	* Issue Management (most of the time only the jira id as a Maven property like in the example)
25.2	150	* Exposed components that should be discoverable in the XWiki UI (e.g. Macros). This is done [[using an ##<xwiki.extension.components~>## entry>>extensions:Extension.Extension Module.Repositories.Maven.WebHome\|\|anchor="HCustomproperties"]]. For example:(((
21.1	151	{{code language="xml"}}
	152	<xwiki.extension.components>
	153	org.xwiki.rendering.macro.Macro/figure
	154	</xwiki.extension.components>
	155	{{/code}}
23.1	156
25.2	157	{{info}}
	158	The best practice is currently to list Macro components as a miniumum and optionally any public component (internal components must not be listed).
	159	{{/info}}
21.1	160	)))
1.1	161
	162	If you've modified the ##groupId## or ##artifactId## of the extension you need to tell it to the Extension Manager so that it can handle upgrades and understand it's the same extension being upgraded. For example if the extension previously had an extension id of ##tdelafosse:meeting-application## and you're now using another id, you need to add the following property to your ##pom.xml##:
	163
	164	{{code language="xml"}}
	165	<properties>
	166	...
	167	<!-- Old names of this module used for retro compatibility when resolving dependencies of old extensions -->
	168	<xwiki.extension.features>tdelafosse:meeting-application</xwiki.extension.features>
	169	...
	170	</properties>
	171	{{/code}}
	172
	173	= Installing an Extension =
	174
2.1	175	There are 2 ways but the recommended one is to use the [[Extension Manager>>extensions:Extension.Extension Manager Application]] which you can find in the XWiki instance where you wish to install the extension in.
1.1	176
2.1	177	== Using the Extension Manager ==
	178
	179	The advantage over the Manual way is that you don't need to regularly start/stop your XWiki instance and thus you don't occur the start wait times.
	180
	181	* Have a running XWiki instance configured with a local Extension Repository pointing to your Maven local Repository. Edit ##xwiki.properties## and make sure you have the following set:(((
	182	{{code language="none"}}
	183	extension.repositories=local:maven:file://${sys:user.home}/.m2/repository
	184	extension.repositories=maven-xwiki:maven:http://nexus.xwiki.org/nexus/content/groups/public
	185	extension.repositories=extensions.xwiki.org:xwiki:http://extensions.xwiki.org/xwiki/rest/
	186	{{/code}}
	187	)))
	188	* Build your component and deploy it in your local Maven repository with ##mvn install##
17.1	189	* Inside your running XWiki instance, go to the Extension Manager in the Admin UI (e.g. ##{{{http://localhost:8080/xwiki/bin/admin/XWiki/XWikiPreferences?editor=globaladmin&section=XWiki.AddExtensions}}}##) and click on Advanced Search and enter your extension's id and version and follow the instructions. (##<groupId>:<artifactId>## , e.g: ##org.xwiki.contrib:your-extension-id##)
2.1	190
19.1	191	Note: If you are on Windows and the extension manager is not able to look up your extension, you might want to use an explicit path to your local maven repository. (for example, ##extension.repositories = maven-local:maven:file:C:/Users/jdoe/.m2/repository##)
18.1	192
2.1	193	{{warning}}
	194	If you want to redeploy an extension and it's already installed with the same version, the Extension Manager won't let you do so. Thus you'll need to uninstall it first using the Extension Manager. You'll also need to remove metadata in memory using the [[Extension Tweak>>extensions:Extension.Extension Tweak]].
	195	{{/warning}}
	196
	197	== Manually ==
	198
22.1	199	Don't use this method if your extension has non-core dependencies as otherwise it's more complex as you also need to copy all dependencies. In addition this won't test that your extension can be installed properly by users. This is listed for information purposes only but you should really use the Extension Manager instead.
	200
2.1	201	=== For a XAR ===
	202
	203	* To build the component, issue ##mvn install##. This generates a XAR in the ##target## directory of your project.
25.2	204	* Inside your XWiki instance, go the Admin and [[Import the XAR>>documentation.xs.admin.imports.import-xwiki-pages.WebHome]].
2.1	205
	206	=== For a JAR ===
	207
	208	* To build the component, issue ##mvn install##. This generates a JAR in the ##target## directory of your project.
8.1	209	* To install it into a XWiki instance, just copy that JAR file in ##XE_WAR_HOME/WEB-INF/lib## where ##XE_WAR_HOME## is where the XWiki WAR is deployed.
2.1	210
1.1	211	= Deploying Extensions =
	212
25.5	213	If you wish to make your extension available to others to use, the best is to contribute it on [[extensions.xwiki.org>>extensions:Main.WebHome]]. [[Publish the extension on extensions.xwiki.org>>contrib:Main.WebHome\|\|anchor="HPublishingonextensions.xwiki.org"]] and follow the instructions for [[documenting it>>contrib:Main.WebHome\|\|anchor="HDocumentation"]] correctly.
3.1	214
	215	Once your extensions is there, it means that any user of XWiki in the world will be able to find it and install it directly from his/her wiki!
	216
	217	You may also want to join a family and contribute your extension on [[XWiki Contrib>>contrib:Main.WebHome]] so that it is developed and maintained collaboratively.

Wiki source code of Creating an Extension

Quick Links

Navigation

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected