Wiki source code of Creating an Extension
Version 1.3 by Vincent Massol on 2016/08/31
Hide last authors
| author | 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: |
| 6 | * 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. | ||
| 7 | * JAR Extensions: they are [[XWiki Components>>extensions:Extension.Component Module]] written in Java and packaged in a JAR. | ||
| 8 | |||
| 9 | = Creating a XAR Extension = | ||
| 10 | |||
| 11 | 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"]]. | ||
| 12 | |||
| 13 | Note that those wiki pages can contain a lot of things: | ||
| 14 | * pure content, | ||
| 15 | * [[scripts>>DevGuide.Scripting]], | ||
| 16 | * 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), | ||
| 17 | * [[wiki macros>>DevGuide.WikiMacroTutorial]], | ||
| 18 | * ... and a lot more | ||
| 19 | |||
| 20 | == Building a XAR with Maven == | ||
| 21 | |||
| 22 | 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/]]. We have developed a plugin called the [[XAR Maven plugin>>dev:Community.XARPlugin]] to help with this. | ||
| 23 | |||
| 24 | Here's how you can save the XAR you got when exporting pages from the wiki into your source tree: | ||
| 25 | * create a ##[ROOT]## directory to be the root of your Maven project | ||
| 26 | * add a ##pom.xml## file (see below for more details) | ||
| 27 | * 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) | ||
| 28 | * run ##mvn xar:format## to pretty format the wiki pages (XML files) | ||
| 29 | * run ##mvn install## to automatically perform validation and generate the XAR | ||
| 30 | |||
| 31 | === Authoring a Maven POM for a XAR === | ||
| 32 | |||
| 33 | Here's an example of how your ##pom.xml## could look like (adapt to your need): | ||
| 34 | |||
| 35 | {{code language="xml"}} | ||
| 36 | <?xml version="1.0" encoding="UTF-8"?> | ||
| 37 | |||
| 38 | <!-- | ||
| 39 | * | ||
| 40 | * See the NOTICE file distributed with this work for additional | ||
| 41 | * information regarding copyright ownership. | ||
| 42 | * | ||
| 43 | * This is free software; you can redistribute it and/or modify it | ||
| 44 | * under the terms of the GNU Lesser General Public License as | ||
| 45 | * published by the Free Software Foundation; either version 2.1 of | ||
| 46 | * the License, or (at your option) any later version. | ||
| 47 | * | ||
| 48 | * This software is distributed in the hope that it will be useful, | ||
| 49 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
| 50 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
| 51 | * Lesser General Public License for more details. | ||
| 52 | * | ||
| 53 | * You should have received a copy of the GNU Lesser General Public | ||
| 54 | * License along with this software; if not, write to the Free | ||
| 55 | * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA | ||
| 56 | * 02110-1301 USA, or see the FSF site: http://www.fsf.org. | ||
| 57 | * | ||
| 58 | --> | ||
| 59 | |||
| 60 | <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"> | ||
| 61 | <modelVersion>4.0.0</modelVersion> | ||
| 62 | <parent> | ||
| 63 | <groupId>org.xwiki.contrib</groupId> | ||
| 64 | <artifactId>parent-platform</artifactId> | ||
| 65 | <version>7.4-6</version> | ||
| 66 | </parent> | ||
| 67 | <groupId>org.xwiki.contrib</groupId> | ||
| 68 | <artifactId>your-extension-id</artifactId> | ||
| 69 | <version>1.0-SNAPSHOT</version> | ||
| 70 | <name>Your extension's name</name> | ||
| 71 | <packaging>xar</packaging> | ||
| 72 | <description>Your extension's description</description> | ||
| 73 | <scm> | ||
| 74 | <connection>scm:git:git://github.com/xwiki-contrib/(your extension id).git</connection> | ||
| 75 | <developerConnection>scm:git:git@github.com:xwiki-contrib/(your extension id).git</developerConnection> | ||
| 76 | <url>https://github.com/xwiki-contrib/(your extension id)</url> | ||
| 77 | </scm> | ||
| 78 | <developers> | ||
| 79 | <developer> | ||
| 80 | <id>scm id of developer 1</id> | ||
| 81 | <name>Full Name of developer 1 as registered on xwiki.org, e.g. Vincent Massol</name> | ||
| 82 | </developer> | ||
| 83 | ... | ||
| 84 | <developer> | ||
| 85 | <id>scm id of developer N</id> | ||
| 86 | <name>Full Name of developer N as registered on xwiki.org, e.g. Vincent Massol</name> | ||
| 87 | </developer> | ||
| 88 | </developers> | ||
| 89 | <properties> | ||
| 90 | <!-- Don't check for API backward-compatibility here since there's no Java code. --> | ||
| 91 | If you're using a xwiki-commons parent POM that is >= 8.1M1 then you need to use: | ||
| 92 | <xwiki.revapi.skip>true</xwiki.revapi.skip> | ||
| 93 | Otherwise you should use: | ||
| 94 | <xwiki.clirr.skip>true</xwiki.clirr.skip> | ||
| 95 | <!-- The Extension name. If not defined, the <name> property is used --> | ||
| 96 | <xwiki.extension.name>Your extension's name</xwiki.extension.name> | ||
| 97 | <!-- The extension's category --> | ||
| 98 | <xwiki.extension.category>application</xwiki.extension.category> | ||
| 99 | </properties> | ||
| 100 | <distributionManagement> | ||
| 101 | <repository> | ||
| 102 | <id>xwiki-staging</id> | ||
| 103 | <name>XWiki Staging Repository</name> | ||
| 104 | <url>http://nexus.xwiki.org/nexus/service/local/staging/deploy/maven2/</url> | ||
| 105 | </repository> | ||
| 106 | </distributionManagement> | ||
| 107 | <issueManagement> | ||
| 108 | <system>jira</system> | ||
| 109 | <url>http://jira.xwiki.org/jira/browse/(your jira project id)</url> | ||
| 110 | </issueManagement> | ||
| 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): | ||
| 115 | * Extension id | ||
| 116 | * Name | ||
| 117 | * Description | ||
| 118 | * Developers | ||
| |
1.3 | 119 | * Category (using ##<xwiki.extension.category>##). Valid values are [[listed here>>extensions:Extension.Repository Application||anchor="HCategories"]]. |
| |
1.1 | 120 | * SCM (Note: this is also required by the Maven Release plugin if you use it to release your extension) |
| 121 | * Issue Management | ||
| 122 | |||
| 123 | 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##: | ||
| 124 | |||
| 125 | {{code language="xml"}} | ||
| 126 | <properties> | ||
| 127 | ... | ||
| 128 | <!-- Old names of this module used for retro compatibility when resolving dependencies of old extensions --> | ||
| 129 | <xwiki.extension.features>tdelafosse:meeting-application</xwiki.extension.features> | ||
| 130 | ... | ||
| 131 | </properties> | ||
| 132 | {{/code}} | ||
| 133 | |||
| 134 | {{info}} | ||
| 135 | 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. | ||
| 136 | |||
| 137 | LTS are always provided for https://github.com/xwiki-contrib/parent, in case the version you want is not listed you can either ask for it to be released in the Mailing List or use ##org.xwiki.commons:xwiki-commons-pom## instead. | ||
| 138 | {{/info}} | ||
| 139 | |||
| 140 | = Creating a JAR Extension = | ||
| 141 | |||
| 142 | 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. | ||
| 143 | |||
| 144 | Here are some examples: | ||
| 145 | * [[Add a new Macro>>rendering:Main.ExtendingMacro]], | ||
| 146 | * [[Write a Listener>>DevGuide.WritingEventListenerTutorial]], | ||
| 147 | * [[Implement a new wiki markup syntax>>rendering:Main.Extending||anchor="HAddinganewSyntax"]], | ||
| 148 | * ... and a lot more | ||
| 149 | |||
| 150 | We recommend following the [[Creating an XWiki Component tutorial>>DevGuide.WritingComponents]] to learn how to both develop a Component and use Maven to build it. | ||
| 151 | |||
| 152 | = Installing an Extension = | ||
| 153 | |||
| 154 | {{todo/}} | ||
| 155 | |||
| 156 | = Deploying Extensions = | ||
| 157 | |||
| 158 | {{todo/}} |
