Release Notes for XWiki 14.1

Last modified by Ilie Andriuta on 2022/03/01

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 latter 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.

The following regressions were introduced in this release (and found after it was released). Please check them out and if they impact you we recommend waiting to upgrade to a version where they are fixed.

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:

[[Caption content>>image:some_image.png]]

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:

[[~[~[xwiki.org~>~>https://www.xwiki.org~]~]>>image:some_image.png]]

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):

Translations

The following translations have been updated: 

Tested Browsers & Databases

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

 BrowserTested on:
Chrome30.pngGoogle Chrome 98Tests run and results
Firefox30.pngMozilla Firefox 97
Edge30.pngMicrosoft Edge 98Jira Tickets Marked as Fixed in the Release Notes
Safari30.pngSafari 15Not Tested

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

 DatabaseTested on:
hypersql.pngHyperSQL 2.6.1Not Tested
mariadb.pngMariaDB 10.6Not Tested
postgresql.pngPostgreSQL 14
mysql.pngMySQL 8
oracle.pngOracle 19cNot Tested

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

 Servlet ContainerTested on:
tomcat-icon.pngTomcat 9.0.59
jetty-icon.pngJetty 10.0.7 (XWiki Standalone packaging)
jetty-icon.pngJetty 10.0.7Not Tested

Known issues

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

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.

Consequently, any updated document queued for upgrade when the server is stopped will be discarded, and some users will not be notified of their mentions.
Please make sure that the queue size is at zero before upgrading (see JMX).

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:

$xwiki.jsfx.use('js/scriptaculous/effects.js')
$xwiki.jsfx.use('js/scriptaculous/dragdrop.js')

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

require(['scriptaculous/dragdrop'], function() {
 // Do your thing.
});

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.

less.js 4.1.2 upgrade

Less.js has been upgraded from 2.5.3 to 4.1.2 and the new version comes with some breaking changes. First of all, you should know that less.js is currently used only for color theme preview in the color theme editor, so this upgrade has no effect on how the color theme is applied when accessing your wiki. Then, the color theme preview may be broken only if you customized the color theme using the Advanced section (@lessCode). Check the change log to see what has been changed between version 2.5.3 and 4.1.2. The most important breaking change we noticed is related to Math operations: by default no division is performed outside of parens using / (slash) operator. This means you need to check your @lessCode text area for division operations and wrap them with parentheses. Don't worry, the preview window should show the Less compilation error pointing you to the line you need to fix.

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
Tags:
   

Get Connected