Wiki source code of Contributing an XWiki XAR Extension
Version 11.1 by Eduard Moraru on 2015/02/14
Show last authors
| author | version | line-number | content |
|---|---|---|---|
| 1 | = How to contribute an extension on http://extensions.xwiki.org = | ||
| 2 | |||
| 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). | ||
| 4 | |||
| 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"]]. | ||
| 6 | |||
| 7 | == Step 1 == | ||
| 8 | |||
| 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). | ||
| 10 | |||
| 11 | Then type the name of the extension to create (e.g. ##TotemApplication##) into the **Contribute Extension** box and click **Add**. | ||
| 12 | |||
| 13 | {{image reference="new-extension.png" width="800" /}} | ||
| 14 | |||
| 15 | == Step 2 == | ||
| 16 | |||
| 17 | After clicking the **Add** button you will be redirected to the edit form of your new extension. | ||
| 18 | |||
| 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. | ||
| 21 | |||
| 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 | |||
| 28 | Add the .xar file as an attachment to your extension document. | ||
| 29 | |||
| 30 | == Step 4 == | ||
| 31 | |||
| 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**. | ||
| 33 | |||
| 34 | {{image reference="add-down-info.png" width="800" /}} | ||
| 35 | |||
| 36 | Now you should be back at the edit page with a **Current Downloads** section added. | ||
| 37 | |||
| 38 | {{image reference="current-down.png" width="800" /}} | ||
| 39 | |||
| 40 | With **Release notes**, **Download URL**, **id** and **Version**. | ||
| 41 | |||
| 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##. | ||
| 48 | |||
| 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. | ||
| 50 | |||
| 51 | Save the extension page (Save & View). | ||
| 52 | |||
| 53 | == Step 5 == | ||
| 54 | |||
| 55 | When you go back to the extension page, you should now see a label saying "Installable with Extension Manager". | ||
| 56 | |||
| 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 | |||
| 63 | {{info}} | ||
| 64 | Skip this step if your extension does not depend on other extensions. | ||
| 65 | {{/info}} | ||
| 66 | |||
| 67 | In our example, the extension depends on the [[Multiselect custom display>>extensions:Extension.Multiselect custom display]] extension. | ||
| 68 | We need the ID of the dependency extension (In our example : **org.xwiki.contrib:displayer-multiselect-suggest**). | ||
| 69 | |||
| 70 | To get the ID of the dependency extension, you need to edit the extension in edit object mode. | ||
| 71 | Click Edit on extension page and append **?editor=object** to the URL in order to be switched into Object Edit mode. | ||
| 72 | In our example the URL is the following: http://extensions.xwiki.org/xwiki/bin/edit/Extension/Multiselect+custom+display?editor=object | ||
| 73 | |||
| 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. | ||
| 75 | |||
| 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}}). | ||
| 78 | |||
| 79 | {{image reference="extension-id.png" width="800" /}} | ||
| 80 | |||
| 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**. | ||
| 83 | |||
| 84 | {{image reference="add-new-dep.png" width="800" /}} | ||
| 85 | |||
| 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. | ||
| 87 | |||
| 88 | When done editing the dependency, save the extension page (Save & View). | ||
| 89 | |||
| 90 | {{image reference="current-dep.png" width="800" /}} | ||
| 91 | |||
| 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. | ||
| 94 | |||
| 95 | == Step 7 == | ||
| 96 | |||
| 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##. | ||
| 98 | |||
| 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. | ||
| 100 | |||
| 101 | {{image reference="install-extension.png" width="800" /}} |
