Best Practices: XWiki Application and Modules Organization

Best Practices: XWiki Application and Modules Organization

Introduction

This document has the objective of describing how to best write an XWiki Application or Module. It explains:

• It describes the different parts that can make an XWiki Application
• How to organize the pages in spaces and how to name the pages
• Naming conventions for the different pages, the translations, the CSS
• Conventions for the Application documentation

General Organization

An module should separate it's data and it's code. Modules should be built to be able to have data in several XWiki spaces, which allows to instanciate the module multiple times.

The only exception would be for applications that would spread multiple spaces on purpose. However it should be most often possible to handle this by having space level sheets showing only data from the current space and global sheets showing data from the whole Wiki.

Naming Conventions

Module Name

It is best to choose a module name between 5 and 10 characters. Your module name should represent your data well. The wiki module name is usually using capital letters. The module name used in the CSS or Javascript or Translations strings is in lower case.

Spaces

• Code Space

• Data Space

Classes

The classes should be stored in the code space and should be suffixed by 'Class'. The properties of the classes should be all lower case. They should be written in english and represent their meaning as much as possible. The 'title' and 'name' property should be kept for a field that can be used as a title for the document.

There can be multiple classes per module.

Sheets

The sheets is used for coding the presentation of a document of your class. The template is an sample document that can be used to pre-initialize data in your documents using this class.

There is usually only one sheet per class.

A sheet should be coded only using the XWiki Public API. It should be made to work both in view more or in edit mode (inline). A good example of a sheet that uses many functions available (tooltips and validation) is available in this tutorial.

Templates

There is usally one template per class, but it is possible to have multiple templates, though this requires more user-interface work.

Translations

Translations are used to store strings to translate the user interface of your application.

The translations strings are each on one line and should be prefixed by the module name in lower case and by the sub-module or page name in which it is used:

mymodule-sheet-title=Title
mymodule-sheet-description=Description
mymodule-sheet-errormessage-cannotsave=The document {0} cannot be saved

Translations strings can contain wiki syntax or HTML which can be interpreted. You have to be extra carefull to not use wiki syntax or HTML without knowing it (for example < > & are special characters). Parameters named {0} {1} {2} can be used in translations.

CSS

CSS should use a similar naming convention as translations. CSS can be stored either in skins files or in wiki pages.

.mymodule-sheet-p {
 // etc..
}
#mymodule-sheet-title {
 // etc..
}

When stored in wiki pages CSS should be surrounded by the pre and slash-pre macros that prevent wiki syntax to be executed in the content.

Javascript

Modules can provide Javascript to extend the functionnality of the wiki

JS functions should be named by the module:

function mymodule-init() {
}
function mymodule-openwindow() {
}
etc..

Macros

Macros should be used extensively to modularize the code in the wiki. Macros can be stored in wiki pages or in skins files.

Macros should be named by the module and the submodule or page that uses it:

## comment explaining the macro
#macro(mymodule-sheet-header $param1 $param2)

#end ## end macro sheet-footer

## comment explaining the macro
#macro(mymodule-sheet-footer $param1 $param2)

#end ## end macro sheet-footer

Groovy

Groovy should be used when more logic is needed. There can be one or multiple groovy classes in the module. If possible we should stick to one module. Functions should use the submodule or page in the function names when it makes sense.

Example code is:

public class Groovy {
 def context;

 public setContext(context) {
  this.context = context;
 }

 public sheetAdd(param1, param2) {
   return param1 + param2;
 }
}

Groovy code can be instanciated in velocity using

#set($mymodule = $xwiki.parseGroovyFromPage("MyModuleCode.Groovy"))
$module.setContext($context)
$module.sheetAdd($param1, $param2)

Plugins

Plugins are optional possibilities offered to developers of modules, as an alternative solution to groovy. Plugins should be name using the module name.

Plugins should be instanciated this way:

#set($mymodule = $xwiki.mymodule)
$module.sheetAdd($param1, $param2)