Release Notes for XWiki 10.10-rc-1

Version 2.1 by Guillaume Delhumeau on 2018/11/15

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.

<insert description of release here>

New and Noteworthy (since XWiki 10.9)

Full list of issues fixed and Dashboard for XWiki 10.9.

For Users

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. 

Auto-suggestion of pages

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

  • Administration Descriptor section
  • Template Provider Sheet

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

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.

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.

Moved Modules

<description deprecated, retired and moved projects>

Upgrades

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

  • <list libraries that have been upgraded>

Translations

The following translations have been updated: 

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 <version>

<issues specific to the project>

API Breakages

The following APIs were modified since <project> <version - 1>:

Credits

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

<code contributors>

Tags:
   

Get Connected