Wiki source code of Contributing an XWiki XAR Extension
Version 11.1 by Eduard Moraru on 2015/02/14
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 == |
| |
1.1 | 8 | |
| |
11.1 | 9 | 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 | 10 | |
| |
11.1 | 11 | Then type the name of the extension to create (e.g. ##TotemApplication##) into the **Contribute Extension** box and click **Add**. |
| |
1.1 | 12 | |
| |
11.1 | 13 | {{image reference="new-extension.png" width="800" /}} |
| |
1.1 | 14 | |
| |
11.1 | 15 | == Step 2 == |
| |
1.1 | 16 | |
| |
11.1 | 17 | After clicking the **Add** button you will be redirected to the edit form of your new extension. |
| |
1.1 | 18 | |
| |
11.1 | 19 | In the **Source** field, you can put the URL of the GitHub repository containing your application's code. |
| 20 | **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 | 21 | |
| |
11.1 | 22 | {{image reference="extension-info.png" width="800" /}} |
| 23 | |||
| 24 | Once you've done that, just save the TotemApplication page (Save & View). | ||
| 25 | |||
| 26 | == Step 3 == | ||
| 27 | |||
| |
1.1 | 28 | Add the .xar file as an attachment to your extension document. |
| 29 | |||
| |
11.1 | 30 | == Step 4 == |
| |
1.1 | 31 | |
| |
11.1 | 32 | 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 | 33 | |
| |
11.1 | 34 | {{image reference="add-down-info.png" width="800" /}} |
| |
1.1 | 35 | |
| |
11.1 | 36 | Now you should be back at the edit page with a **Current Downloads** section added. |
| |
1.1 | 37 | |
| |
11.1 | 38 | {{image reference="current-down.png" width="800" /}} |
| |
1.1 | 39 | |
| |
11.1 | 40 | With **Release notes**, **Download URL**, **id** and **Version**. |
| |
1.1 | 41 | |
| |
11.1 | 42 | ; Download URL |
| 43 | : should be {{{attach:<the name of your attachment>}}}, for example {{{attach:totem-1.0.xar}}}. | ||
| 44 | ; id | ||
| 45 | : should be 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. | ||
| 46 | ; Version | ||
| 47 | : is whatever the version number is, for example ##1.0##. | ||
| |
1.1 | 48 | |
| |
11.1 | 49 | 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 | 50 | |
| |
11.1 | 51 | Save the extension page (Save & View). |
| |
1.1 | 52 | |
| |
11.1 | 53 | == Step 5 == |
| |
1.1 | 54 | |
| |
11.1 | 55 | When you go back to the extension page, you should now see a label saying "Installable with Extension Manager". |
| |
1.1 | 56 | |
| |
11.1 | 57 | {{image reference="installable-with-extension-manager.png" width="800" /}} |
| 58 | |||
| 59 | 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. | ||
| 60 | |||
| 61 | == Step 6 == | ||
| 62 | |||
| |
1.1 | 63 | {{info}} |
| |
11.1 | 64 | Skip this step if your extension does not depend on other extensions. |
| |
1.1 | 65 | {{/info}} |
| 66 | |||
| |
11.1 | 67 | In our example, the extension depends on the [[Multiselect custom display>>extensions:Extension.Multiselect custom display]] extension. |
| |
1.1 | 68 | We need the ID of the dependency extension (In our example : **org.xwiki.contrib:displayer-multiselect-suggest**). |
| 69 | |||
| |
11.1 | 70 | To get the ID of the dependency extension, you need to edit the extension in edit object mode. |
| |
1.1 | 71 | Click Edit on extension page and append **?editor=object** to the URL in order to be switched into Object Edit mode. |
| |
11.1 | 72 | In our example the URL is the following: http://extensions.xwiki.org/xwiki/bin/edit/Extension/Multiselect+custom+display?editor=object |
| |
1.1 | 73 | |
| |
11.1 | 74 | 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 | 75 | |
| |
11.1 | 76 | 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. |
| 77 | Click cancel or close the tab ({{warning}}DON'T CLICK SAVE{{/warning}}). | ||
| |
9.2 | 78 | |
| |
11.1 | 79 | {{image reference="extension-id.png" width="800" /}} |
| |
1.1 | 80 | |
| |
11.1 | 81 | When you got the ID, go back to your extension edit page to declare the dependency. |
| 82 | 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 | 83 | |
| |
11.1 | 84 | {{image reference="add-new-dep.png" width="800" /}} |
| |
1.1 | 85 | |
| |
11.1 | 86 | 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 | 87 | |
| |
11.1 | 88 | When done editing the dependency, save the extension page (Save & View). |
| |
1.1 | 89 | |
| |
11.1 | 90 | {{image reference="current-dep.png" width="800" /}} |
| |
1.1 | 91 | |
| |
11.1 | 92 | 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. |
| 93 | Extensions.xwiki.org will automatically remove it if something is broken with the extension after adding a dependency. | ||
| |
1.1 | 94 | |
| |
11.1 | 95 | == Step 7 == |
| |
1.1 | 96 | |
| |
11.1 | 97 | 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 | 98 | |
| |
11.1 | 99 | 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 | 100 | |
| |
11.1 | 101 | {{image reference="install-extension.png" width="800" /}} |
