Wiki source code of Contributing an XWiki XAR Extension
Version 13.1 by Thomas Mortagne on 2015/02/16
Hide last authors
| author | version | line-number | content |
|---|---|---|---|
 |
11.1 | 1 | = How to contribute an extension on http://extensions.xwiki.org = |
 |
1.1 | 2 | |
| |
11.1 | 3 | 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>>extensions:Extension.Administration Application]] that provides an UI to manage the extensions within a wiki. Extensions are mainly XARs (e.g. [[XWiki applications>>platform:Features.Applications]], [[wiki macros>>extensions: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). |
| |
1.1 | 4 | |
| |
11.1 | 5 | Notice that XARs (or JAR extensions) can also be imported from a maven repository (if they were previously released) and this process is [[documented on the contrib page>>contrib:Main.WebHome||anchor="HPublishingonextensions.xwiki.org"]]. |
 |
9.9 | 6 | |
| |
11.1 | 7 | == Step 1 == |
 |
12.1 | 8 | |
| |
1.1 | 9 | |
| |
11.1 | 10 | Go to [[http://extensions.xwiki.org>>extensions:Main.WebHome]] and login (you can [[create an account for the xwik.org community>>xwiki:XWiki.RealRegistration]] if you do not already have one). |
| |
1.1 | 11 | |
| |
11.1 | 12 | Then type the name of the extension to create (e.g. ##TotemApplication##) into the **Contribute Extension** box and click **Add**. |
| |
1.1 | 13 | |
| |
12.1 | 14 | {{image reference="new-extension.png" width="800"/}} |
| |
1.1 | 15 | |
| |
11.1 | 16 | == Step 2 == |
| |
1.1 | 17 | |
| |
11.1 | 18 | After clicking the **Add** button you will be redirected to the edit form of your new extension. |
| |
1.1 | 19 | |
| |
11.1 | 20 | In the **Source** field, you can put the URL of the GitHub repository containing your application's code. |
| 21 | **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. | ||
| |
1.1 | 22 | |
| |
12.1 | 23 | {{image reference="extension-info.png" width="800"/}} |
| |
11.1 | 24 | |
| 25 | Once you've done that, just save the TotemApplication page (Save & View). | ||
| 26 | |||
| 27 | == Step 3 == | ||
| 28 | |||
| |
1.1 | 29 | Add the .xar file as an attachment to your extension document. |
| 30 | |||
| |
11.1 | 31 | == Step 4 == |
| |
1.1 | 32 | |
| |
11.1 | 33 | So after you've finished uploading the .xar file, click **Edit** on the page and then scroll down almost to the bottom where you'll find the **Add Downloads** section. There, you need to read the instructions on the second bullet (the one starting with "Add Download information") and click on **Extension Version**. |
| |
1.1 | 34 | |
| |
12.1 | 35 | {{image reference="add-down-info.png" width="800"/}} |
| |
1.1 | 36 | |
| |
11.1 | 37 | Now you should be back at the edit page with a **Current Downloads** section added. |
| |
1.1 | 38 | |
| |
12.1 | 39 | {{image reference="current-down.png" width="800"/}} |
| |
1.1 | 40 | |
| |
11.1 | 41 | With **Release notes**, **Download URL**, **id** and **Version**. |
| |
1.1 | 42 | |
| |
11.1 | 43 | ; Download URL |
| 44 | : should be {{{attach:<the name of your attachment>}}}, for example {{{attach:totem-1.0.xar}}}. | ||
| 45 | ; id | ||
| |
13.1 | 46 | : this field is optional and mostly used by the importer so you can leave it blank. If you really want to put something put the same ID as the one used by your application, ex: ##mouhb:totemapplication##. If you do not know how to get the ID of an application, have a quick look at step 6 for the details. |
| |
11.1 | 47 | ; Version |
| 48 | : is whatever the version number is, for example ##1.0##. | ||
| |
1.1 | 49 | |
| |
11.1 | 50 | 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. |
| |
1.1 | 51 | |
| |
11.1 | 52 | Save the extension page (Save & View). |
| |
1.1 | 53 | |
| |
11.1 | 54 | == Step 5 == |
| |
1.1 | 55 | |
| |
11.1 | 56 | When you go back to the extension page, you should now see a label saying "Installable with Extension Manager". |
| |
1.1 | 57 | |
| |
12.1 | 58 | {{image reference="installable-with-extension-manager.png" width="800"/}} |
| |
11.1 | 59 | |
| 60 | If there is no "Installable with Extension Manager" mentioned, then there is a problem. You have to go back to the edit page and check the extension information as mentioned above in this document. | ||
| 61 | |||
| 62 | == Step 6 == | ||
| 63 | |||
| |
1.1 | 64 | {{info}} |
| |
11.1 | 65 | Skip this step if your extension does not depend on other extensions. |
| |
1.1 | 66 | {{/info}} |
| 67 | |||
| |
11.1 | 68 | In our example, the extension depends on the [[Multiselect custom display>>extensions:Extension.Multiselect custom display]] extension. |
| |
1.1 | 69 | We need the ID of the dependency extension (In our example : **org.xwiki.contrib:displayer-multiselect-suggest**). |
| 70 | |||
| |
11.1 | 71 | To get the ID of the dependency extension, you need to edit the extension in edit object mode. |
| |
1.1 | 72 | Click Edit on extension page and append **?editor=object** to the URL in order to be switched into Object Edit mode. |
| |
11.1 | 73 | In our example the URL is the following: http://extensions.xwiki.org/xwiki/bin/edit/Extension/Multiselect+custom+display?editor=object |
| |
1.1 | 74 | |
| |
11.1 | 75 | Note: alternatively, you can reach the object editor by setting your user profile preferences **User Type** value to ##Advanced##. Once you do that, the **Edit** button on the page can be expanded and the **Objects** option can be selected. |
| |
1.1 | 76 | |
| |
11.1 | 77 | Now expand the first entry in **Objects of type ExtensionCode.ExtensionClass (1)** and select **Id** which is the first property in that object (the value is ##org.xwiki.contrib:displayer-multiselect-suggest##). Copy that value to the clipbloard (CTRL+C) since we need it further along. |
| 78 | Click cancel or close the tab ({{warning}}DON'T CLICK SAVE{{/warning}}). | ||
| |
9.2 | 79 | |
| |
12.1 | 80 | {{image reference="extension-id.png" width="800"/}} |
| |
1.1 | 81 | |
| |
11.1 | 82 | When you got the ID, go back to your extension edit page to declare the dependency. |
| 83 | Scroll down down almost to the bottom where you'll find the **Add Dependencies** section. There, you need to read the instructions and click on **Dependency**. | ||
| |
1.1 | 84 | |
| |
12.1 | 85 | {{image reference="add-new-dep.png" width="800"/}} |
| |
1.1 | 86 | |
| |
11.1 | 87 | Now you should be back at the edit page with a "Current Dependencies" section added which you can edit. See the picture above for details on what each field means. |
| |
1.1 | 88 | |
| |
11.1 | 89 | When done editing the dependency, save the extension page (Save & View). |
| |
1.1 | 90 | |
| |
12.1 | 91 | {{image reference="current-dep.png" width="800"/}} |
| |
1.1 | 92 | |
| |
11.1 | 93 | To check if the dependency was added successfully, go back to the main page and check that the "Installable with the Extension Manager" tag still exists. |
| 94 | Extensions.xwiki.org will automatically remove it if something is broken with the extension after adding a dependency. | ||
| |
1.1 | 95 | |
| |
11.1 | 96 | == Step 7 == |
| |
1.1 | 97 | |
| |
11.1 | 98 | 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##. |
| |
1.1 | 99 | |
| |
11.1 | 100 | Once you verify that the extension was successfully installed (and works) on your local wiki, then the process of creating the extension is complete. |
| |
1.1 | 101 | |
| |
12.1 | 102 | {{image reference="install-extension.png" width="800"/}} |
