Release Notes for XWiki 10.10-rc-1

Last modified by Ilie Andriuta 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.

For users, this version brings a protection when a page containing an XClass is moved or renamed. By default, the PDF export looks better now. In addition, the recent auto-suggestion feature has been enabled in a few places.

For developers, a new asynchronous framework has been created. It allows the execution of desired parts of the rendering of a page to be executed asynchronously, with an AJAX request. This makes the rendering of the page faster, making the least important parts visible after the page is loaded.

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.

To finish, more than 30 bugs have been fixed since XWiki 10.9.

New and Noteworthy (since XWiki 10.9)

Full list of issues fixed and Dashboard for XWiki 10.10-rc-1.

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.

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.

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.

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.

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.

Miscellaneous

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

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

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: 

  • German
  • French
  • Norwegian

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 70Not Tested
Firefox30.pngMozilla Firefox 63New and Noteworthy Features + Jira Tickets Marked as Fixed in the Release Notes + Smoke tests
Edge30.pngMicrosoft Edge 17Not Tested
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.7Smoke tests
oracle.pngOracle 11.2New and Noteworthy Features + Jira Tickets Marked as Fixed in the Release Notes
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

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

Thanks to them!

Tags:
Created by Adel Atallah on 2018/11/05
   

Get Connected