Release Notes for XWiki 10.10

Last modified by Vincent Massol on 2018/12/06
Contents

The following regressions or important bugs were found after this version was released, and are fixed in following releases. Depending on whether you're affected by them you may decide to postpone installing this version and wait for the next one:

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.

In this version, we introduced a new protection helper to prevent users from breaking the wiki when an XClass page is being refactored, we improved the PDF export look and we started to enable the new auto-suggestion feature in some places.

It's now possible to easily enable asynchronous execution and caching for panels, wiki UI extensions and wiki macros, this making the rendering of the page faster.

Among other things, Wiki Macros can now have typed parameters and it is now possible to make the content of a macro editable inline with the WYSIWYG editor.

New and Noteworthy (since XWiki 10.9)

Full list of issues fixed and Dashboard for for 10.10.

For Users

Improved performances

 
We have enabled asynchronous rendering of several UI elements: side Panels, Menu entries and more. This allows to have the page content rendered much faster than before giving a nice feeling of increased performance and snappiness.

async-panels.png

Inline Macro Content Editing

 
The macro content can now be edited inline with the WYSIWYG editor, if the macro is used on a separate line (stand-alone, not inside a paragraph of text) and the macro descriptor declares that its content is rendered without being transformed. There are a few macros that do this at the moment (box, info, warning, error and figure macros) but we're planing to add support for more macros in the next versions.

See the CKEditor Integration documentation for more information.

Prevent users from deleting/moving/renaming pages containing used XClass

 
Users are now warned when they make refactoring operations (delete, move or rename) in pages that contain used XClass. Simple users are forbidden to realize those operations, whereas advanced users get an UI to allow them selecting the pages to refactor. 

menu_rename_simpleuser.png
menu_rename_cancelled.png
menu_rename_advanceduser.png

Auto-suggestion of pages

 
The auto-suggestion of pages feature has been implemented in new places:

  • Administration Descriptor section
  • Template Provider Sheet

page-picker-01.png
page-picker-02.png

Improved default look and feel of PDF export

 
The look and feel of the default PDF export was slightly improved: sans serif font is now used by default and some graphic elements were added to better separate the regions of the page (header, footer, etc.).

Selection_104.png

For Admins

Execute JavaScript Inside Editing Area

 
The CKEditor has a new configuration option to enable the loading of the JavaScript Skin Extensions inside the editing area. This can improve the way macros are displayed inside the editor, if they require JavaScript, but it has some downsides. Check the CKEditor Integration documentation for more information.

ckeditor-loadJavaScriptSkinExtensions.png

For Developers

New asynchronous rendering framework

 
It's now possible to easily enable asynchronous execution and caching for panels, wiki UI extensions and wiki macros.

The following fields have been added:

  • Asynchronous rendering (async_enabled): a boolean indicating if the element should be executed asynchronously. Disabled by default.
  • Cached (async_cached): a boolean indicating if the result of the execution of the element should be cached. Disabled by default.
  • Context elements (async_context): the context information required for the execution of the element (current user, current document, etc.). It's also used to generate the cache key.

A org.xwiki.rendering.async.AsyncContext Java class and corresponding $services.async script service have been introduced to control:

  • if the asynchronous execution should be enabled/disabled in the current context (in which case any following execution of panels will be synchronous no matter how it was configured in the first place for example).
  • a set of methods to help register a set of entities and components which should lead to cache invalidation if they are modified, for the current asynchronous execution.
  • a way to register some custom resources to remember. Their cached results will be reinjected later (for example it's used to remember the skin extensions required by a cached element). One can then implement org.xwiki.rendering.asyncAsyncContextHandler to restore them when using the cached content.

Context save/restore

 
New tools have been introduced to help save and restore contextual information. It's useful for example when transferring contextual information from one thread to another to execute asynchronous tasks. This is done trough org.xwiki.context.concurrent.ContextStoreManager.

It's possible to add support for more contextual information by implementing org.xwiki.context.concurrent.ContextStore components. See documentation for more details.

On Jobs side a new context property have been added to the org.xwiki.job.Request to automatically restored passed context data before executing the job.

Create a job to delete all from the recycle bin

 
It is now possible to create a job for permanently delete elements from the recycle bin. It is supported in the Refactoring Script Service as explained in its documentation.

Allow wiki macros to indicate the type of parameters

 
You can now specify the Java type of a wiki macro parameter. It used to not be possible and all wiki macro parameters were Strings.

Macro content can be declared to be inline editable

 
Some part of the macro content can be declared as inline editable: the user will then be able to edit those parts of the content directly in the wysiwyg editor.

In order to make this available you need to specify 2 information when declaring the macro:

  1. the type of the macro content
  2. the parts of the macro that can be editable inline

Specify the type of the macro content

 

You need to specify it in the constructor of the DefaultContentDescriptor: 

public DefaultContentDescriptor(String description, boolean mandatory, Type type)

The type of a content which can be editable inline, is List<Block>.
In order to simplify its declaration, we created a constant that can be immediately used:

new DefaultContentDescriptor("Content of the message", true, Block.LIST_BLOCK_TYPE));

Specify the parts of the macro that can be editable inline

When declaring the result of the macro by overridding execute method, you can specify which parts of the macro will be editable inline, by specifying some metadata.

For example, if you want to declare a block containing a logo which is always the same and a block which will be editable inline you can specify it like that:

ResourceReference imageReference = // declare the reference to the image logo
Block logoBlock = new ImageBlock(imageReference, true);
List<Block> content = this.contentParser.parse(content, context, false, context.isInline()).getChildren(); // parse the existing content and get its children blocks
Block editableContent = new MetadataBlock(content, this.getNonGeneratedContentMetadata()); // specify the right metadata in order to make the content editable inline
return Arrays.asList(logoBlock, editableContent);

The obtained result for the rendering will look like:

<!--startmacro:myMacro|-||-|content-->
<span id="logo"><img src="mylogo.png" /></span>
<div data-xwiki-non-generated-content="java.util.List&lt; org.xwiki.rendering.block.Block &gt;" class="xwiki-metadata-container">
    <p>my editable content</p>
</div>
<!--stopmacro-->

The syntax used inside the editable part can be declared by using a syntax metadata. 

Consider that nested macro will be editable inline, only if they also declare an editable content. On the same idea, if a nested macro declare an editable content, it can be used only if the parent macro also declare an editable content.

Please note that between 10.10RC1 and 10.10 the metadata changed its name.
So with 10.10RC1, in the above snippets you should replace the method getNonGeneratedContentMetadata by getUnchangedContentMetadata, and the html attribute data-xwiki-non-generated-content by data-xwiki-unchanged-content.

Miscellaneous

  • Mark the scripts that are safe to be executed inside the WYSIWYG editor: The WYSIWYG editor doesn't execute the JavaScript code inside the editing area by default. If you need this then you need to:

    • Enable the loading of the JavaScript Skin Extensions from the WYSIWYG editor administration section
    • Mark the scripts that are safe to be loaded inside the editing area:
      #set ($discard = $xwiki.jsx.use('Path.To.MyMacro', {'wysiwyg': true}))

    Check the CKEditor Integration documentation for more information.

  • Script API to access the macro descriptor: The rendering script service has been extended with APIs to resolve a macro id and to access the macro descriptor:

    #set ($macroId = $services.rendering.resolveMacroId('info/xwiki/2.1'))
    #set ($macroDescriptor = $services.rendering.getMacroDescriptor($macroId))

    Check the Rendering Module documentation for more information.

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:

 BrowserTests performed and results
Chrome30.pngGoogle Chrome 70New and Noteworthy Features + Jira Tickets Marked as Fixed in the Release Notes
Firefox30.pngMozilla Firefox 63Not Tested
Edge30.pngMicrosoft Edge 17Smoke tests
IE30.pngInternet Explorer 11Smoke tests
Safari30.pngSafari 12Not Tested

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

 DatabaseTests performed and results
hypersql.pngHyperSQL 2.4.1Not Tested
mysql.pngMySQL 5.7New and Noteworthy Features + Jira Tickets Marked as Fixed in the Release Notes + Smoke tests
oracle.pngOracle 11.2Not Tested
postgresql.pngPostgreSQL 10Smoke tests

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

 Servlet ContainerTests performed and results
tomcat-icon.pngTomcatNot Tested
jetty-icon.pngJetty (XWiki Standalone packaging)New and Noteworthy Features + Jira Tickets Marked as Fixed in the Release Notes
jetty-icon.pngJettyNot Tested

Performances tests compared to 9.11.8

Summary

All the performance boosts are coming from the asynchronous rendering and caching of various elements of the skin. We need to analyze in details what is stored in the increased memory use but various new caches have been added so it's not suprising (notification preference cache, groups cache, cached skin elements). The degraded indexing speed will need to be analyzed too. Even if there are more documents to index in 10.10 (+3%), it's probably not enough to explain the x2 difference.

"similar": difference is lower than 10%
"slightly": difference is lower than 20%

Note that most of the speed related values are an average of very moving results, a lot of things is happening during a HTTP request and it's far from stable duration (that's why 10% may sounds a lot for something called "similar" but the variable can go up and down around 5% sometimes so 10% average is really not that much of a clear win). Dumbbench based tests are executed several times and the lowest result is selected.

Speed

ActionsDifference
Jetty startupsimilar
First accessnot existing page without UIsimilar
not existing page with UIslightly faster
Reloadnot existing page without UIsimilar
not existing page with UI-30%
empty page without UIsimilar
empty page with UI-23%
Main.WebHome without UIsimilar
Main.WebHome with UI-20%
SOLRFull SOLR reindexsimilar
SOLR sync when index is emptyx2
SOLR sync when there is nothing to do+23%
Result of search finding lots of resultsslightly faster
Result of search finding one resultslightly faster
RenderingPage with 1000 macros without UIsimilar
Page with 1000 html macros without UIsimilar
Wiki creationFrom flavorslightly slower
From templateslightly slower

Memory

ActionsDifference
Heap Memory after jetty startup +8M used
Heap Memory after full SOLR index +23M

More details on performance comparison on single wiki between 10.10 and 9.11.8.

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.

API Breakages

The following APIs were modified since  XWiki 10.9:

Failed to execute the [groovy] macro. Cause: [startup failed: Script1821.groovy: 9: unable to resolve class XmlSlurper  @ line 9, column 12.      result = new XmlSlurper().parseText(xml)                ^  1 error ]. Click on this message for details.

Credits

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

Adel Atallah
Alex Cotiugă
Anca Luca
Clemens Klein-Robbenhaar
Clément Aubin
Edvard
Guillaume Delhumeau
Mario-Hofstaetter
Marius Dumitru Florea
Paul Panțiru
Sergiu Dumitriu
Simon Urli
Thomas Mortagne
Vincent Massol
xrichard
XWiki

About

About

Support

Platform

User Guide

Admin Guide

Developer Guide

Projects

XWiki

Extensions

Other

Contribute

Status

Practices

Under the Hood

Get Involved

Get Connected