Release Notes for XWiki 10.10

Version 9.1 by Alex Cotiugă on 2018/11/29

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.

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.

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:

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:

  • Not a breakage.
    • Violation type:
      java.annotation.attributeValueChanged
    • Code:
      ## Old:
      @interface org.xwiki.stability.Unstable

      ## New:
      @interface org.xwiki.stability.Unstable
  • Not a breakage: class moved to a legacy module
    • Violation type:
      java.class.removed
    • Code:
      ## Old:
      class org.xwiki.velocity.introspection.AbstractChainableUberspector
  • Not a breakage: class moved to a legacy module
    • Violation type:
      java.class.removed
    • Code:
      ## Old:
      interface org.xwiki.velocity.introspection.ChainableUberspector
  • Not a breakage: class moved to a legacy module
    • Violation type:
      java.class.removed
    • Code:
      ## Old:
      class org.xwiki.velocity.introspection.ChainingUberspector
  • Not a breakage: class moved to a legacy module
    • Violation type:
      java.class.removed
    • Code:
      ## Old:
      class org.xwiki.velocity.introspection.LinkingUberspector
  • Not a breackage
    • Violation type:
      java.class.nonFinalClassInheritsFromNewClass
    • Code:
      ## Old:
      class org.xwiki.rendering.transformation.TransformationException

      ## New:
      class org.xwiki.rendering.transformation.TransformationException
  • Not a breackage
    • Violation type:
      java.class.nowCheckedException
    • Code:
      ## Old:
      class org.xwiki.rendering.transformation.TransformationException

      ## New:
      class org.xwiki.rendering.transformation.TransformationException
  • As RssMacro now inherits from AbstractBoxMacro, its parameter class needs to inherits from BoxMacroParameters. This could only break compatibility if a class inheriting from RssMacroParameters defines a method with same name and parameters than in BoxMacroParameters but different return type. We consider this risk as acceptable since the chances are very low and in case it occurs, the fix for the user would be easy.
    • Violation type:
      java.class.nonFinalClassInheritsFromNewClass
    • Code:
      ## Old:
      class org.xwiki.rendering.macro.rss.RssMacroParameters

      ## New:
      class org.xwiki.rendering.macro.rss.RssMacroParameters

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

Tags:
   

Get Connected