Application Development Best Practices

Last modified by Marius Dumitru Florea on 2023/12/07 11:21


  • 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.
  • Technical pages must be put in a subspace named Code
  • All technical pages must be hidden
  • Technical pages without children must be Terminal pages
  • Pages must be written in XWiki Syntax 2.1
  • Don't require Programming Rights for your wiki pages to work (as much as possible). This has several drawbacks
    • If a user without Programming Rights edits the page, the page will be broken
    • If an Admin without Programming Rights installs an extension containing this page, it won't work
  • 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 <div class="something">...</div> and instead use (% class="something" %)(((...))). One notable exception is for HTML forms for which we don't have a macro yet.
  • Applications must usually be registered in the Applications Panel using the Add Application Extension Point. A page named ApplicationsPanelEntry must be created for that. If only Admins should see the application then you'll need to add #if ($hasAdmin)...#end in the Parameters section of the Extension Point implementation.
  • Name your class/sheet/templates as follows where XXX is your business name (e.g. Faq, IRCBot, etc): XXXClass, XXXSheet, XXXTemplate
  • Reuse existing UI components as much as possible
  • 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 emoticon_smile) with XWiki import which could import the XObject before the XClass and cause some havoc...
  • 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:
    • FAQ app already provides a {{faq}} gadget to list all entries for a given FAQ app
    • Index app already provides a {{document}} gadget to list all documents matching some criteria
    • Blog app doesn’t currently provide such a gadget (it provides a Velocity macro but that’s not a gadget)
    • Forum app should provide a {{forums}} gadget too to list all forums and a {{forum}} one to list entries from a given forum
    • etc


  • Page content should only contain presentation logic and not business logic. Business logic need to be written in Java in the following manner:
    • Create a component role (i.e. interface) to represent the business domain
    • Create an implementing component class, usually suffixed with Manager (e.g. FaqManager, "IRCBotManager, etc)
    • Create a Script Service implementation component to expose some API to scripts and perform necessary permission checks. Make sure to read the best practices for script services.


  • If you need Translations for the Java code, use a file located at the root of your JAR (it'll be automatically registered at runtime).
  • Application must be internationalized using the Translation Macro and the Localization Script Service
  • Translations must follow the rules defined in DevelopmentPractices.


  • Don't use deprecated API! Always use the most recent APIs.
  • 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)
  • 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. 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.
  • Must work with the supported browsers and the supported databases

Build & Release

  • Create a Maven project for your application and extend the top level POM
  • Always format your wiki pages using mvn xar:format
  • 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.
  • Your application should be published on so that all XWiki users can use it easily! When describing your extension you might look at the corresponding documentation.
  • Set xwiki.extension.namespaces in the POM when an extension will only work when installed on the root namespace. See documentation.


  • Write unit tests (using Mockito for mocking) to prove that the Java code works as expected (see existing code for examples).
  • Always create functional tests to prove that the application works as expected (see existing code for examples).

Get Connected