This is the release notes for XWiki Commons, XWiki Rendering and XWiki Platform. They share the same release notes as they are released together and have the same version.

This release adds support for displaying images from the page content in a lightbox and extends the image syntax to support image captions. The later requires HTML5 so we added support for HTML5 in various places, such as the HTML Macro, WYSIWYG Editor, rendered diff. For developers we introduce a new API to perform asynchronous document static analysis, which is currently used to collect mentions from page content or comments, and will be soon used to collect backlinks. Another notable change is the jQuery upgrade which comes with some API breakages so please make sure you read the migration notes.

New and Noteworthy (since XWiki 14.0)

Full list of issues fixed and Dashboard for 14.1.

For Users

Display images in a lightbox

 
Users can now open images from the page content in a lightbox. While hovering an image, a toolbar will appear with options for opening the image in lightbox mode or to download it. The lightbox will display the image along with some information about it, depending if it's attached to a wiki page or it's an external one, and with some actions like download, toggle the browser full screen mode or start a carousel play of all images found in the page content. You can toggle the visibility of the image caption and action buttons by clicking on the image.

The lightbox feature is disabled by default and can be enabled from the Administration, Look & Feel -> Lightbox section. Checkout the documentation for more information.

Image Captions

 
The XWiki 2.0 and 2.1 syntax now supports captioned images. The syntax:

is rendered as an image with "Caption content" as caption when the image is alone in a paragraph (e.g. the image syntax is surrounded by blank lines). The caption content supports full XWiki syntax. If you want to use nested links you need to escape the link syntax with a single escape character. For instance, the following syntax:

generates an image with a link to xwiki.org in the caption.

Image captions are also supported in the WYSIWYG editor. In the image dialog the checkbox "Captioned image" can be used to add/remove the caption of an image. The caption can be edited directly below the image.

Miscellaneous

• HTML 5 support in the HTML Macro: The HTML macro supports HTML 5 and switches to HTML 5 whenever the content is output as HTML 5. This means that in most cases (for example, when using the default Flamingo Skin), the HTML macro can be used to insert new HTML tags like the <video>-tag into the content of a page while having the clean-parameter enabled.

• HTML 5 support in the rendered differences: The rendered differences between different revisions of a page now correctly display HTML 5 tags like figures and captions for changed content. This is in particular relevant with the new figure caption support but can also be good for custom HTML that includes tags not supported by HTML 4.

• Changes to "Own Event" and "System Event" notification filters: The "Own Event" and "System Event" notification filters are not blocking anymore the notifications that target explicitly the user. See the Notification Application documentation for more information about these filters.

For Admins

No changes!

For Developers

Asynchronous document static analysis

 
A new asynchronous document static analysis API is now available in the Index Application. This API allows to queue and consume persistent document analysis tasks. This API is used in this release as an underlying implementation of the mentions analysis, and will be used soon to perform the analysis of the backlinks of the pages.

Miscellaneous

• Ability to exclude some locations from the Location Picker: The Location Picker Macro exposes an additional parameter exclusions allowing to exclude some locations (nested pages) from the list of locations that can be picked.

• Localization API: We added two methods to the LocalizationManager:

  • a helper method to search for a given translation key in the specified locale and to render it as plain text:
    String getTranslationPlain(String key, Locale locale, Object... parameters)
  • a method to get the configured default locale:
    Locale getDefaultLocale()

  The first one was already available in the script service (under a different name: $services.localization.render()), so we exposed the second one too:

  $services.localization.defaultLocale

  Checkout the Localization Module documentation for more information.

• (X)HTML 5 parsers added: Two new parsers for HTML 5 and XHTML 5 have been added to the XWiki rendering framework. They are largely based on the existing parser for XHTML 1.0 but support <figure> and <figcaption> tags. The former is based on the latter, but passes the given HTML code to the HTML cleaner first to obtain valid XML. These parsers are the basis for the new HTML 5 support in the WYSIWYG editor but can also be used in other contexts to convert HTML 5 to XDOM, e.g., in the context of an importer.

• HTML 5 support in the WYSIWYG editor: The WYSIWYG Editor Module now uses HTML 5. See below for additional notes on backwards-compatibility. Not all HTML 5 features are supported, yet, the main new feature is support for parsing figures with captions. There should be a closer match between the HTML code in the editor and the HTML code in view mode but this might require adaptations for WYSIWYG editors and extensions extending them. This has also consequences for renderers that should handle figure and figure caption events not just in macro contexts (due to the figure macro).

• Cluster members are uniquely identified: Each member of a cluster is now uniquely identified. The id is automatically generated once at startup and stored in the permanent directory.

Upgrades

The following runtime dependencies have been upgraded (they have a different release cycle than XWiki Commons, XWiki Rendering and XWiki Platform):

• Apache Xerces 2.12.2
• Apache XML Graphics Commons 2.7
• Checker Qual 3.21.2
• CKEditor Integration 1.60.1
• Closure Compiler v20220202
• Error Prone annotations 2.11.0
• Hibernate 5.6.5
• HSQLDB 2.6.1
• Infinispan 13.0.6.Final
• JAXB Runtime 2.3.6
• jQuery 3.6.0
• lessjs 4.1.2
• Liquibase 4.7.1
• MariaDB connector 3.0.3
• Netty 4.1.74.Final
• node 16.3.2
• PostgresSQL connector 42.3.2
• Protobuf Java 3.19.4
• SLF4J 1.7.36
• Tika 2.3.0
• Tour Application 1.3.4
• @vue/cli-service 4.5.15

Translations

The following translations have been updated:

• German
• French
• Norwegian
• Russian

Tested Browsers & Databases

Here is the list of browsers we support and how they have been tested for this release:

	Browser	Tested on:
	Google Chrome 98	Jira Tickets Marked as Fixed in the Release Notes
	Mozilla Firefox 97	Not Tested
	Microsoft Edge 98	Not Tested
	Safari 15	Not Tested

Here is the list of databases we support and how they have been tested for this release:

	Database	Tested on:
	HyperSQL 2.6.1	Not Tested
	MariaDB 10.6	Jira Tickets Marked as Fixed in the Release Notes
	PostgreSQL 14	Not Tested
	MySQL 8	Not Tested
	Oracle 19c	Not Tested

Here is the list of Servlet Containers we support and how they have been tested for this release:

	Servlet Container	Tested on:
	Tomcat 9.0.58	Jira Tickets Marked as Fixed in the Release Notes
	Jetty 10.0.7 (XWiki Standalone packaging)	Not Tested
	Jetty 10.0.7	Not Tested

Known issues

• Bugs we know about

Backward Compatibility and Migration Notes

General Notes

• When upgrading make sure you compare and merge the following XWiki configuration files since some parameters may have been modified, removed or added:
  • xwiki.cfg
  • xwiki.properties
  • web.xml
  • hibernate.cfg.xml
• Add xwiki.store.migration=1 in xwiki.cfg so that XWiki will attempt to automatically migrate your current database to any new schema. Make sure you backup your Database before doing anything.

Issues specific to XWiki 14.1-rc-1

Mentions

The underlying implementation of the Mentions Application, H2 MVStore is now replaced by the newly introduced Asynchronous document static analysis module. When upgrading to 14.1RC1+ the H2 MVStore files are not used anymore.

WYSIWYG API

The WYSIWYG editor script service has been changed to parse and render HTML 5 instead of XHTML 1.0. The actual changes should be subtle in most cases and all HTML code that has been previously parsed should still be parsed but the new caption support (see above) requires that the WYSIWYG editor preserves <figure> and <figcaption>-tags. Further, as the <tt> HTML tag is obsolete in HTML 5, it is replaced by a <span class="monospace"> which is equivalent to the HTML output in view mode. WYSIWYG editors can detect the new version through the presence of the new method getHTMLSyntax() that currently returns the Annotated HTML 5 syntax. The bundled CKEditor integration has been adapted for this change.

Prototype.js and Scriptaculous loaded from WebJars

The following JavaScript files were removed from the XWiki WAR and are now loaded from their WebJars:

• js/prototype/prototype.js
• js/scriptaculous/effects.js
• js/scriptaculous/dragdrop.js

prototype.js was loaded by default on every page and it still is so there's no reason to worry about it. On the other hand, effects.js and dragdrop.js weren't loaded by default so if you have code that loads them from the skin, using for instance:

then you need to update it to load them using RequireJS, such as:

See this commit for a migration example.

jQuery 3.6.0 upgrade

jQuery has been upgraded from 2.2.4 to 3.6.0 and the new version comes with a couple of API breakages. We recommend reviewing the jQuery upgrade guide for versions 3.0 and 3.5. Existing code should not be broken during the 14.x XWiki cycle because we are going to load the jQuery migrator plugin which ensures backward compatibility. Nevertheless we recommend refactoring your JavaScript code to use the latest jQuery APIs as soon as possible, to ensure it will continue to work after we stop loading the jQuery migrator plugin.

API Breakages

The following APIs were modified since XWiki 14.0:

Real breakages

Real backward compatibility breakages that we have unwillingly accepted to do for the reasons mentioned in each violation below.

• Change in a generated class for the REST model to integrate new originalMetadataAuthor information.
  • Violation type:
    java.annotation.attributeValueChanged
  • Code:
    ## Old:
    class org.xwiki.rest.model.jaxb.Page
    
    ## New:
    class org.xwiki.rest.model.jaxb.Page

Credits

The following people have contributed code and translations to this release (sorted alphabetically):

• Eduard Moraru
• Gankov Andrey
• Jarle Sandmo
• Manuel Leduc
• Marius Dumitru Florea
• Michael Hamann
• Oana-Lavinia Florean
• Simon Urli
• Simpel
• Thomas Mortagne
• Vincent Massol
• jingkaimori
• slauriere
• u74a8 zhou
• xrichard