Show last authors
1 {{box cssClass="floatinginfobox" title="**Contents**"}}
2 {{toc/}}
3 {{/box}}
4
5 = Pages =
6
7 * Generally, put all your pages in a single space dedicated for the application you're developing (e.g. ##Faq##, ##Scheduler##, ##IRC##, ##AppWithinMinutes##, etc). The name must be as short as possible while still being understandable of course and without overusing abbreviations.
8 * Technical pages must be put in a subspace named ##Code##
9 * All technical pages must be ##hidden##
10 * Technical pages without children must be Terminal pages
11 * Pages must be written in XWiki Syntax 2.1
12 * Page content must contain the minimum of HTML (since HTML doesn't translate in discrete XDOM elements and thus are not always handled by all Renderers). For example don't use {{code}}<div class="something">...</div>{{/code}} and instead use {{code}}(% class="something" %)(((...))){{/code}}. One notable exception is for HTML forms for which we don't have a macro yet.
13 * Applications must usually be registered in the Applications Panel using the [[Add Application Extension Point>>platform:ExtensionPoint.AddApplicationUIX]]. A page named ##ApplicationsPanelEntry## must be created for that. If only Admins should see the application then you'll need to add {{code}}#if ($hasAdmin)...#end{{/code}} in the ##Parameters## section of the Extension Point implementation.
14 * Name your class/sheet/templates as follows where ##XXX## is your business name (e.g. ##Faq##, ##IRCBot##, etc): ##XXXClass##, ##XXXSheet##, ##XXXTemplate##
15 * Reuse [[existing UI components>>platform:DevGuide.FrontendResources]] as much as possible
16 * Put an XClass definition in a document by itself and refrain from adding XObject(s) in that XClass document. It enables better separation of concern and also helps for upgrades and solves some dark magic issue (a.k.a bug :)) with XWiki import which could import the XObject before the XClass and cause some havoc...
17 * If it makes sense, provide a Macro so that users can easily add a view of the app on the home page (added in their Dashboard as a Gadget). For example:
18 ** FAQ app already provides a ##~{~{faq}}## gadget to list all entries for a given FAQ app
19 ** Index app already provides a ##~{~{document}}## gadget to list all documents matching some criteria
20 ** Blog app doesn’t currently provide such a gadget (it provides a Velocity macro but that’s not a gadget)
21 ** Forum app should provide a ##~{~{forums}}## gadget too to list all forums and a ##~{~{forum}}## one to list entries from a given forum
22 ** etc
23
24 = Java =
25
26 * Page content should only contain presentation logic and not business logic. Business logic need to be written in Java in the following manner:
27 ** Create a component role (i.e. interface) to represent the business domain
28 ** Create an implementing component class, usually suffixed with ##Manager## (e.g. ##FaqManager##, "IRCBotManager##, etc)##
29 ** Create a [[Script Service>>extensions:Extension.Script Module]] implementation component to expose some API to scripts and perform necessary permission checks. Never throw an exception, return ##null## instead and offer a way to check for an error and to get the exception from the script, usually by putting the exception in the context and using ##lastexception## as context key name.
30
31 = Internationalization =
32
33 * If you need Translations for the Java code, use a ##ApplicationResources.properties## file located at the root of your JAR (it'll be automatically registered at runtime).
34 * Application must be internationalized using the [[Translation Macro>>extensions:Extension.Translation Macro]] and the [[Localization Script Service>>extensions:Extension.Localization Module||anchor="HFromVelocity"]]
35 * Translations must follow the rules defined in [[dev:Community.DevelopmentPractices||anchor="HTranslationPropertyNaming"]].
36
37 = General =
38
39 * Don't use deprecated API! Always use the most recent APIs.
40 * No API requiring Programming Rights must be used as much as possible (if there's a need, it should be raised to the XWiki Committers who may add missing APIs if need be)
41 * Do not use Skin-specific resources since this will make your Application work only on that Skin and it'll get broken as soon as XWiki changes its default Skin. For example the Colibri-skin brought a ##noavatar.png## image. However the Flamingo Skin (which came after the Colibri Skin) didn't define it and all [[Applications that were using ##$xwiki.getSkinFile("noavatar.png")## were broken>>https://github.com/xwiki-contrib/application-forum/commit/3d3a99e5665265607a41d8ce04f38c6ebb8c2d7a]]. Instead use resources located in the ##resources/## directory, such as ##$xwiki.getSkinFile("icons/xwiki/noavatar.png")##. If the resource you need only exist in a specific Skin, consider raising an issue to make it available more globally.
42 * Must work with the [[supported browsers>>doc:Community.BrowserSupportStrategy]] and the [[supported databases>>doc:Community.DatabaseSupportStrategy]]
43
44 = Build & Release =
45
46 * Create a Maven project for your application and extend the top level POM
47 * Always format your wiki pages using ##mvn xar:format##
48 * In your POM always try to depend on the oldest version of commons/rendering/platform dependencies for which your code works. At least, ensure that your Applications works on the latest LTS version of XWiki. This will allow the largest number of users to use your application.
49 * Your application should be published on http://extensions.xwiki.org so that all XWiki users can use it easily! When describing your extension you might look at the [[corresponding documentation>>contrib:Main.WebHome||anchor="HDocumenting"]].
50 * Set ##xwiki.extension.namespaces## in the POM when an extension will only work when installed on the root namespace. See [[documentation>>extensions:Extension.XWiki Commons - Extension - Repository - Maven||anchor="HCustomproperties"]].
51
52 = Tests =
53
54 * Write unit tests (using Mockito for mocking) to prove that the Java code works as expected (see existing code for examples).
55 * Always create functional tests to prove that the application works as expected (see existing code for examples).

Get Connected