Wiki source code of Contributing an XWiki XAR Extension
Version 9.12 by Mohamed Boussaa on 2015/02/13
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
1.1 | 1 | |
 |
9.9 | 2 | **How to contribute an extension on http://extensions.xwiki.org ?** |
| |
1.1 | 3 | |
| |
9.12 | 4 | The current document will help you to create XAR extensions that will be installable via the extension manager. The extension manager is an application accessible from the [[XWiki Administration>>url:http://extensions.xwiki.org/xwiki/bin/view/Extension/Administration+Application]] that provides an UI to manage the extensions within a wiki. Extensions are mainly XARs (e.g. [[XWiki applications>>url:http://platform.xwiki.org/xwiki/bin/view/Features/Applications]], [[wiki macros>>http://extensions.xwiki.org/xwiki/bin/view/Extension/Wiki+Macro+Bridge+Application]]). A XAR is a set of XWiki pages that represents an XWiki application, a macro or simply a page containing a code snippet. This document will explain how to publish a XAR automatically through the extensions Manager (EM). Notice that XARs can be imported from maven but this method requires special permissions. |
| |
9.9 | 5 | |
| |
1.1 | 6 | == **step 1**== |
| 7 | |||
| 8 | Go to http://extensions.xwiki.org and login (You can create an account on http://www.xwiki.org/xwiki/bin/view/XWiki/RealRegistration). | ||
| 9 | |||
| 10 | Then type the name of the extension to create (TotemApplication) into the "contribute extension" box and click "add". | ||
| 11 | |||
| 12 | [[image:new-extension.png||style="border:1px solid #cccccc;width:90%"]] | ||
| 13 | |||
| 14 | == **step 2**== | ||
| 15 | After clicking the Add button you will be redirected to the edit form of your new extension. | ||
| 16 | in the "**Source**" field, you can put the URL of github repo containing your application code. | ||
| 17 | **Description/license/summary** are whatever you want, we're creating an extension which can be installed with the ExtensionManager so "**custom installation"** and "**custom installation instructions**" should remain blank/unchecked. | ||
| 18 | |||
| 19 | [[image:extension-info.png||style="border:1px solid #cccccc;width:90%"]] | ||
| 20 | |||
| 21 | Once you've done that, just save the TotemApplication page (save & view). | ||
| 22 | |||
| 23 | == **step 3**== | ||
| 24 | Add the .xar file as an attachment to your extension document. | ||
| 25 | |||
| 26 | == **step 4**== | ||
| 27 | So after you've finished uploading the .xar file, click "edit" on the page and then scroll down almost to the bottom... | ||
| 28 | and click: "Add Download information for the new attachment by filing in a new Extension Version". | ||
| 29 | |||
| 30 | [[image:add-down-info.png||style="border:1px solid #cccccc;width:90%"]] | ||
| 31 | |||
| 32 | Now you should be back at the edit page with a "Current Downloads" section added. | ||
| 33 | |||
| 34 | [[image:current-down.png||style="border:1px solid #cccccc;width:90%"]] | ||
| 35 | |||
| 36 | With "Release notes", "download URL" "id" and "version" download url should be attach:<the name of your attachment> | ||
| 37 | for example: "attach:totem-1.0.xar" | ||
| 38 | |||
| 39 | id is just a generic name like "totem" | ||
| 40 | version is whatever the version number is, for example 1.0 | ||
| 41 | |||
| 42 | Make sure to use only <major>.<minor> in the version number, a version number such as 1.0.0 or 1.0-feb13 will cause problems. | ||
| 43 | |||
| 44 | Save the extension page (save & view). | ||
| 45 | |||
| 46 | == **step 5**== | ||
| 47 | So when you go back to the page, you should see a field saying "Installable with extension manager". | ||
| 48 | |||
| 49 | Notice on this extension, there is that field: http://extensions.xwiki.org/xwiki/bin/view/Extension/Wiki+Flavor+Application. | ||
| 50 | |||
| 51 | If there is no "Installable with extension manager" then there is a problem. you have to go back to the edit page and check the extension information as mentionned above in this document. | ||
| 52 | |||
| 53 | == **step 6**== | ||
| 54 | {{info}} | ||
| 55 | Skip this step if your extension do not depend on other extensions. | ||
| 56 | {{/info}} | ||
| 57 | |||
| 58 | In our example the extension depends on the following extension : http://extensions.xwiki.org/xwiki/bin/view/Extension/Multiselect+custom+display | ||
| 59 | We need the ID of the dependency extension (In our example : **org.xwiki.contrib:displayer-multiselect-suggest**). | ||
| 60 | |||
| 61 | To get the ID of the dependency extension, you can edit the extension in edit object mode. | ||
| 62 | Click Edit on extension page and append **?editor=object** to the URL in order to be switched into Object Edit mode. | ||
| 63 | In our example the URL is the following : | ||
| 64 | http://extensions.xwiki.org/xwiki/bin/edit/Extension/Multiselect+custom+display?editor=object | ||
| 65 | |||
| 66 | Now expand the first entry in "**Objects of type ExtensionCode.ExtensionClass (1)**" | ||
| 67 | Select "id" which is the first entry in that (the value is "**org.xwiki.contrib:displayer-multiselect-suggest**") | ||
| |
9.11 | 68 | Click cancel or close the tab ("DON'T CLICK SAVE"). |
| |
1.1 | 69 | |
| |
9.2 | 70 | [[image:extension-id.png||style="border:1px solid #cccccc;width:90%"]] |
| 71 | |||
| |
1.1 | 72 | So when you got the ID, go back to your extension edit page to declare the dependency. |
| 73 | Scroll down almost to the bottom ... and click: "You can also associate dependencies to each version by filing in the following information in a new Dependency". | ||
| 74 | |||
| 75 | [[image:add-new-dep.png||style="border:1px solid #cccccc;width:90%"]] | ||
| 76 | |||
| 77 | Now you should be back at the edit page with a "Current Dependencies" section added. | ||
| 78 | |||
| 79 | **Extension version** is the version on which this dependency is assigned | ||
| 80 | **Dependency id** is the identifier of the dependency extension on the repository where it is localed | ||
| 81 | **Dependency version** constraint is the version related information of the dependency. Can be a version (e.g. 1.0) or one or several ranges of versions based on Maven standard syntax, for example: [1.0,) which would mean "at least 1.0". | ||
| 82 | |||
| 83 | Save the extension page (save & view). | ||
| 84 | |||
| 85 | [[image:current-dep.png||style="border:1px solid #cccccc;width:90%"]] | ||
| 86 | |||
| 87 | To check if dependency was added successfully, go back to the main page and check that the "Installable with the Extension Manager" tag still exists. | ||
| 88 | extensions.xwiki.org will automatically remove it if something is broken with the extension after adding a dependency. | ||
| 89 | |||
| 90 | == **step 7**== | ||
| 91 | |||
| 92 | The last step is to start up a fresh wiki on your machine, go to "Administer Wiki", click "Install Extensions" on the left and type the name of your extension, in our example "totem". | ||
| 93 | |||
| 94 | Once you verify that the extension has successfully installed (and works) on your local wiki, then the process of creating the extension is complete. | ||
| 95 | |||
| 96 | [[image:install-extension.png||style="border:1px solid #cccccc;width:90%"]] |
