Wiki source code of Creating an Extension

Version 6.1 by Vincent Massol on 2017/03/31

Hide last authors
Vincent Massol 1.2 1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
Vincent Massol 1.1 5 There are 2 types of Extensions:
Thomas Mortagne 4.1 6
Vincent Massol 1.1 7 * XAR Extensions: they are wiki pages packaged in a [[format that is called XAR>>extensions:Extension.XAR Module Specifications]] (which stands for XWiki Archive). It's a ZIP file with a specific directory structure and an XML syntax to represent the wik pages, along with a package metadata file.
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
12 The simplest strategy is to create the wiki pages in a running XWiki instance and then to [[export them as a XAR>>Features.Exports||anchor="HXARExport"]].
13
14 Note that those wiki pages can contain a lot of things:
Thomas Mortagne 4.1 15
Vincent Massol 1.1 16 * pure content,
17 * [[scripts>>DevGuide.Scripting]],
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),
19 * [[wiki macros>>DevGuide.WikiMacroTutorial]],
20 * ... and a lot more
21
22 == Building a XAR with Maven ==
23
Vincent Massol 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.
Vincent Massol 1.1 25
26 Here's how you can save the XAR you got when exporting pages from the wiki into your source tree:
Thomas Mortagne 4.1 27
Vincent Massol 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
Vincent Massol 6.1 36 Here's an example of how your ##pom.xml## could look like (adapt to your need).
Vincent Massol 1.1 37
Vincent Massol 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
Vincent Massol 1.1 40 {{code language="xml"}}
41 <?xml version="1.0" encoding="UTF-8"?>
42
43 <!--
44 *
45 * See the NOTICE file distributed with this work for additional
46 * information regarding copyright ownership.
47 *
48 * This is free software; you can redistribute it and/or modify it
49 * under the terms of the GNU Lesser General Public License as
50 * published by the Free Software Foundation; either version 2.1 of
51 * the License, or (at your option) any later version.
52 *
53 * This software is distributed in the hope that it will be useful,
54 * but WITHOUT ANY WARRANTY; without even the implied warranty of
55 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
56 * Lesser General Public License for more details.
57 *
58 * You should have received a copy of the GNU Lesser General Public
59 * License along with this software; if not, write to the Free
60 * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
61 * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
62 *
63 -->
64
65 <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">
66 <modelVersion>4.0.0</modelVersion>
67 <parent>
68 <groupId>org.xwiki.contrib</groupId>
69 <artifactId>parent-platform</artifactId>
Thomas Mortagne 5.1 70 <version>8.4-6</version>
Vincent Massol 1.1 71 </parent>
72 <groupId>org.xwiki.contrib</groupId>
73 <artifactId>your-extension-id</artifactId>
74 <version>1.0-SNAPSHOT</version>
75 <name>Your extension's name</name>
76 <packaging>xar</packaging>
77 <description>Your extension's description</description>
78 <scm>
79 <connection>scm:git:git://github.com/xwiki-contrib/(your extension id).git</connection>
80 <developerConnection>scm:git:[email protected]:xwiki-contrib/(your extension id).git</developerConnection>
81 <url>https://github.com/xwiki-contrib/(your extension id)</url>
82 </scm>
83 <developers>
84 <developer>
85 <id>scm id of developer 1</id>
86 <name>Full Name of developer 1 as registered on xwiki.org, e.g. Vincent Massol</name>
87 </developer>
88 ...
89 <developer>
90 <id>scm id of developer N</id>
91 <name>Full Name of developer N as registered on xwiki.org, e.g. Vincent Massol</name>
92 </developer>
93 </developers>
94 <properties>
95 <!-- Don't check for API backward-compatibility here since there's no Java code. -->
96 If you're using a xwiki-commons parent POM that is >= 8.1M1 then you need to use:
97 <xwiki.revapi.skip>true</xwiki.revapi.skip>
98 Otherwise you should use:
99 <xwiki.clirr.skip>true</xwiki.clirr.skip>
Thomas Mortagne 4.1 100
Vincent Massol 1.1 101 <!-- The Extension name. If not defined, the <name> property is used -->
102 <xwiki.extension.name>Your extension's name</xwiki.extension.name>
Thomas Mortagne 4.1 103
Vincent Massol 1.1 104 <!-- The extension's category -->
105 <xwiki.extension.category>application</xwiki.extension.category>
Thomas Mortagne 4.1 106
107 <!-- Issue management -->
108 <xwiki.release.jira.skip>false</xwiki.release.jira.skip>
Thomas Mortagne 5.1 109 <xwiki.issueManagement.jira.id>(your jira project id)</xwiki.issueManagement.jira.id>
Vincent Massol 1.1 110 </properties>
111 </project>
112 {{/code}}
113
114 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):
Thomas Mortagne 4.1 115
Vincent Massol 1.1 116 * Extension id
117 * Name
118 * Description
119 * Developers
Vincent Massol 1.3 120 * Category (using ##<xwiki.extension.category>##). Valid values are [[listed here>>extensions:Extension.Repository Application||anchor="HCategories"]].
Vincent Massol 1.1 121 * SCM (Note: this is also required by the Maven Release plugin if you use it to release your extension)
122 * Issue Management
123
124 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##:
125
126 {{code language="xml"}}
127 <properties>
128 ...
129 <!-- Old names of this module used for retro compatibility when resolving dependencies of old extensions -->
130 <xwiki.extension.features>tdelafosse:meeting-application</xwiki.extension.features>
131 ...
132 </properties>
133 {{/code}}
134
135 {{info}}
136 In addition you need to pay attention to the version of the dependencies you're going to use (for example the version of your parent POM). 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. This is because your extension will only be able to be installed in XWiki versions satisfying those dependencies you expressed.
137
Thomas Mortagne 5.1 138 LTS are always provided for https://github.com/xwiki-contrib/parent, in case the version you want is not listed you can:
139 * use the closest LTS as parent but use a different version for the dependencies
140 * ask for it to be released in the Mailing List
141 * use ##org.xwiki.commons:xwiki-commons-pom## instead
Vincent Massol 1.1 142 {{/info}}
143
144 = Creating a JAR Extension =
145
146 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.
147
148 Here are some examples:
Thomas Mortagne 4.1 149
Vincent Massol 1.1 150 * [[Add a new Macro>>rendering:Main.ExtendingMacro]],
151 * [[Write a Listener>>DevGuide.WritingEventListenerTutorial]],
152 * [[Implement a new wiki markup syntax>>rendering:Main.Extending||anchor="HAddinganewSyntax"]],
153 * ... and a lot more
154
Vincent Massol 3.2 155 Follow the [[Creating an XWiki Component tutorial>>DevGuide.WritingComponents]] to learn how to both develop a Component and use Maven to build it.
Vincent Massol 1.1 156
157 = Installing an Extension =
158
Vincent Massol 2.1 159 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.
Vincent Massol 1.1 160
Vincent Massol 2.1 161 == Using the Extension Manager ==
162
163 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.
164
165 * 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:(((
166 {{code language="none"}}
167 extension.repositories=local:maven:file://${sys:user.home}/.m2/repository
168 extension.repositories=maven-xwiki:maven:http://nexus.xwiki.org/nexus/content/groups/public
169 extension.repositories=extensions.xwiki.org:xwiki:http://extensions.xwiki.org/xwiki/rest/
170 {{/code}}
171 )))
172 * Build your component and deploy it in your local Maven repository with ##mvn install##
173 * 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.
174
175 {{warning}}
176 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]].
177 {{/warning}}
178
179 == Manually ==
180
181 === For a XAR ===
182
183 * To build the component, issue ##mvn install##. This generates a XAR in the ##target## directory of your project.
184 * Inside your XWiki instance, go the Admin and [[Import the XAR>>Features.Imports]].
185
186 === For a JAR ===
187
188 * To build the component, issue ##mvn install##. This generates a JAR in the ##target## directory of your project.
189 * To install it into a XWiki Enterprise instance, just copy that JAR file in ##XE_WAR_HOME/WEB-INF/lib## where ##XE_WAR_HOME## is where the XWiki Enterprise WAR is deployed.
190
Vincent Massol 1.1 191 = Deploying Extensions =
192
Vincent Massol 3.1 193 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]]. Go there and enter a name for your extension in the Contribute box and submit. Then document nicely your extension with instructions on how to use. The more screenshots the better! Here are some [[documentation guidelines>>contrib:Main.WebHome||anchor="HDocumenting"]].
194
195 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!
196
197 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.

Get Connected