How to contribute an extension on http://extensions.xwiki.org

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 that provides an UI to manage the extensions within a wiki. Extensions are mainly XARs (e.g. XWiki applications, wiki macros). 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 (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. This is the easiest and also the recommended way.

Step 1


Go to http://extensions.xwiki.org and login (you can create an account for the xwik.org community if you do not already have one).

Then type the name of the extension to create (e.g. TotemApplication) into the Contribute Extension box and click Add.

new-extension.png

Step 2

After clicking the Add button you will be redirected to the edit form of your new extension.

In the Source field, you can put the URL of the GitHub repository containing your application's code.
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.

extension-info.png

Once you've done that, just save the TotemApplication page (Save & View).

Step 3

Add the .xar file as an attachment to your extension document.

Step 4

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.

add-down-info.png

Now you should be back at the edit page with a Current Downloads section added.

current-down.png

With Release notes, Download URL, id and Version.

Download URL
should be attach:<the name of your attachment>, for example attach:totem-1.0.xar.
id
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.
Version
is whatever the version number is, for example 1.0.

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.

Save the extension page (Save & View).

Step 5

When you go back to the extension page, you should now see a label saying "Installable with Extension Manager".

installable-with-extension-manager.png

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.

Step 6

Skip this step if your extension does not depend on other extensions.

In our example, the extension depends on the Multiselect custom display extension.
We need the ID of the dependency extension (In our example : org.xwiki.contrib:displayer-multiselect-suggest).

To get the ID of the dependency extension, you need to edit the extension in edit object mode.
Click Edit on extension page and append ?editor=object to the URL in order to be switched into Object Edit mode.
In our example the URL is the following: http://extensions.xwiki.org/xwiki/bin/edit/Extension/Multiselect+custom+display?editor=object

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.

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.
Click cancel or close the tab (DON'T CLICK SAVE).

extension-id.png

When you got the ID, go back to your extension edit page to declare the dependency.
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.

add-new-dep.png

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.

When done editing the dependency, save the extension page (Save & View).

current-dep.png

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.
Extensions.xwiki.org will automatically remove it if something is broken with the extension after adding a dependency.

Step 7

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.

Once you verify that the extension was successfully installed (and works) on your local wiki, then the process of creating the extension is complete.

install-extension.png

Tags:
Created by Mohamed Boussaa on 2015/02/17 10:09
    

Get Connected