Best practices

Java APIs

Data Model

XDocument and XObject manipulation should be done using the DocumentAccessBridge. This allows the XWiki data model APIs to be used without incurring a build dependency on the xwiki "oldcore" module, which is very large. This XWiki doc page has more information.

...we seem to havemigrated away from this approach as it was unfortunately limiting what we can do

Escaping in the code

We should use various escape tools to avoid bugs in UI (citing Sergiu here):

$escapetool.xml()

escapes only XML special characters (<'&">) and is to be used whenever the text is placed inside a HTML or XML block, either inside a {{html wiki="false"}} macro, or in a .vm file on disk.

$!{services.rendering.escape()}

escapes wiki markup, and is to be used in wiki pages, outside the {{html}} macro, whenever we don't want things like --dashed--, **bold, or [[link]] to be rendered. Inside {{html wiki="true"}} both kinds of output are possible, so both types of escapes are needed, example: $!{services.rendering.escape(${escapetool.xml('The **bold** and the <em>beautiful</em>.')})}

$escapetool.javascript()

escapes the text to be placed inside a javascript code. To BE REVIEWED, not sure when exactly need this one

Migrations

- First 3 digits are the current XWiki version- 4th is always 9 for us- 5th is a counter (e.g. first migration wihin the same release may be 71290, second is 71291)- the number after PhenoTips is the issue number

Reading XObjects under a document

This code is for reading the XObjects "RemoteMatchingServiceConfiguration" under the document XWikiPreference that is found in the space "XWiki". The order of the code lines is only for illustration.See ApplicationConfiguration.java and XWikiAdapter.java for the full code.

Frontend Components

Javascript files

XWiki has two primary ways of including Javascript files: on the filesystem and as XObjects (of the JavaScriptExtension class). Best practice is for the files to reside on the filesystem, in order to

Enable a natural editing experience with amenities like linting and syntax-highlighting

Streamline the edit-debug-commit cycle, since using the JavaScriptExtension approach necessitates a XAR export and mvn xar:format before committing

In order to have the file available on the filesystem for use, do the following:

Add a new project to your component's maven project, with a name ending in "-resources", e.g. "patient-measurements-resources" for the "patient-measurements" project.

In the new project, add your JS files under src/main/resources/resources/uicomponents/phenotips (there are purposely two "resources" directories in that path). Files here will automatically be placed at webapps/phenotips/resources/uicomponents/phenotips in PT's "base-war" distribution after you complete this procedure.

Add your package to the base WAR's POM, at components/base-war/pom.xml. There are two entries to make here, see the commitdiff below for an example.

After completing this procedure, you can now include the JS files using