Release Notes for XWiki 8.0

Version 11.1 by Thomas Mortagne on 2016/03/15

This is the release notes for XWiki Commons, XWiki Rendering, XWiki Platform and XWiki Enterprise. 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 7.4)

Full list of issues fixed and Dashboard for 8.0.

Asynchronous Copy and Rename Page

The copy and rename page operations are now performed asynchronously, in a background thread, when triggered from the UI. Clicking on the Copy/Rename button takes you to a status page where you can see the options that have been selected and the progress of the operation. The advanced users have access to the operation log.

copyProgress.png

The progress bar is replaced with the operation status at the end in order to let you know if the operation succeeded or failed. You can use the breadcrumbs to navigate to the new page or the old one.

renameStatus.png

See the Page Lifecycle documentation for more information.

Improved Location Picker

The location picker used on the Create, Copy and Rename page UI is now hiding the advanced edit fields (wiki, parent and name) for simple users. Simple users will have to use the tree picker to select the target location. As a consequence the form validation is now performed on the fields that are visible to the current user.

simpleLocationPickerValidation.png

Link syntax improvements for Nested Pages

With the addition of Nested Pages, a discrepancy appeared between the UI and the wiki syntax. The UI always talks about (nested) pages and never about spaces, but in the wiki syntax you would still have to specify both the space and the name of a page when linking to it (e.g. writing [[Some.Nested.Page.WebHome]] if you want to create a link to the nested page Some.Nested.Page). The same applies to image: or attach: syntax. The technical reason for this was that, at the wiki syntax level, untyped links were always being resolved to doc: type links.

To improve this, we have added a new space: type link which allows you to simply write [[space:Some.Nested.Page]] and have made this the new default type that untyped links resolve to.

The outcome is that you can now simply type [[Some.Nested.Page]] and you will create a link to the nested page Some.Nested.Page.

For backwards compatibility with the existing untyped links, we have implemented the same mechanism we have applied for URLs, which is to:

  • first try to link to an existing terminal page (i.e. if Some.Nested.Page is actually a terminal page inside the Some.Nested space; this was the previous default behavior)
  • if no such terminal page exists, then link to the non-terminal page (i.e. Some.Nested.Page.WebHome) for both when the non-terminal page exists or when it does not (and should be a wanted link)

The same thing applies for image: (e.g. image:[email protected] translates technically to image:[email protected]) and for attach: syntax (e.g. attach:[email protected] translates technically to attach:[email protected]).

More details and examples can be found in the XWiki link syntax documentation page on your XWiki instance.

Relative links to sibling Nested Pages

To better support backwards compatibility with the pre-Nested-Pages behavior when the current document is a non-terminal document and an untyped relative link (e.g [[Page]]) has not been resolved using the above mentioned algorithm (i.e. as a terminal or non-terminal child of the current page), we perform 2 additional checks:

  • we try to link to an existing terminal page that is a sibling of the current page (i.e. [[Page]] is resolved to the equivalent of [[doc:currentPageParent.Page]])
  • if no such terminal page exists, then link to the non-terminal page that is a sibling of the current page (i.e. [[Page]] is resolved to the equivalent of [[doc:currentPageParent.Page.WebHome]]) for both when the non-terminal page exists or when it does not (and should be a wanted link)

Color Theme Displayer

In the administration, an error message is displayed if the configured color theme is invalid. It could happen after an upgrade if you were using an old Colibri Theme.

ColorThemeDisplayer.png

Disable header and footer in PDF export

It's now possible to disabled the display of header and footer (usually the page name and date) when exporting a PDF.

pdfExportOptions.png

LESS Module

  • For performances reasons, we have set a limit for the number of LESS CSS compilations that can be done simultaneously.
  • For the same reason, the LESS cache is not cleared anymore at XWiki launch.

For more informations about this, please see LESS Module.

New XWiki distribution

The work on a new as small as possible distribution of XWiki has started. The key goal is to try to have a WAR as small as possible on which you install one of the Flavors automatically found in the registered repositories (meaning http://extensions.xwiki.org/ for now).

The size is still not very far from XE (188M compared to the 219M XE), one important limitation is that we kept some old plugins because they are hard to install as extensions (you need to modify xwiki.cfg and restart). We need to convert them to proper components so that we can move them to contrib as "pure" extensions.

There is still two important known limitation in that version that we hope to have in 8.0 final or 8.1 at worst:

  • make flavors search in the Distribution Wizard asynchronous, the step is blocked for a long time right now which is not very nice
  • support upgrade of invalid flavor (search for a valid replacement in that case)

It's still experimental and should be avoided in production but the move has started and we are very excited by the new opportunity this will bring!

Custom admin user to replace standard Admin user

Since XWiki exists you got a user Admin with password admin in the default XAR. This time is now gone and you are now asked to register your own user which will be the owner of the wiki (meaning whatever you do you can't loose admin right on it, unless you change the owner) when you install XWiki from scratch. We kept a standard Admin user for the all in one jetty/hsqldb package so the change won't be visible in this one.

newwelcome.png

customuser.png

Automatically generated main wiki descriptor

The XE XAR does not contain any descriptor for the main wiki anymore. This descriptor is now automatically created/updated at start and associated to the domain name found in the URL that was used to access the wiki the first time.

Chart Macro Additions

There are several new parameters that can now be set when using the Chart Macro:

Parameter nameDefault valueDescription
backgroundColorGrey backgroundBackground color of the non-chart area, specified using an hexadecimal notation, e.g. FFAACC (first 2 letters are for Red, following 2 are for Green and last 2 are for Blue).
plotBackgroundColorWhiteBackground color of the plot area, specified using an hexadecimal notation (see backgroundColor).
plotBorderColorBlackColor of the plot border, specified using an hexadecimal notation (see backgroundColor).
borderColorBlackColor of the outer graph border, specified using an hexadecimal notation (see backgroundColor).
legendBackgroundColorWhiteBackground color of the legend box, specified using an hexadecimal notation (see backgroundColor).
plotBorderVisibletrueWhether the border for the plot area is visible or not. Valid values are true and false.
legendVisibletrueWhether the legend is displayed or not. Valid values are true and false.

Examples:

  • Pie chart with no legend displayed, no border, no title and white background:
    {{chart type="pie" source="inline" params="range:B2-D5;series:columns;backgroundColor:FFFFFF;plotBackgroundColor:FFFFFF;plotBorderVisible:false;legendVisible:false" width="320" height="240"}}
    |=|=X|=Y|=Z
    |Q1|1.2|3.4|1.3
    |Q2|4.5|3.4|2.3
    |Q3|1.2|4.5|9.0
    |Q4|3.4|1.2|1.2
    {{/chart}}

    pieChartWhite.png

  • Colored background:
    {{chart type="pie" source="inline" params="range:B2-D5;series:columns;backgroundColor:FFFF11;plotBackgroundColor:11FFFF" title="Chart Test" width="320" height="240"}}
    |=|=X|=Y|=Z
    |Q1|1.2|3.4|1.3
    |Q2|4.5|3.4|2.3
    |Q3|1.2|4.5|9.0
    |Q4|3.4|1.2|1.2
    {{/chart}}

    pieChartColor.png

In addition, it's now possible to perform advanced customization of the generated chart.

Rename and Copy UI

  • Updated the rename page UI's field labels and descriptions to mention that the update links also updates the relative links inside the renamed page and not just the backlinks. Also moved the count displays from the field label to the field's description, where applicable, in both the rename and the copy UI, for better UI consistency.

    renameRewording-Step1.png

    copyRewording-Step1.png

  • The copy and rename UI now have the children and links options checked by default. We believe it`s better to preserve data consistency by default, even with the cost o having to go through lengthy operations (like when renaming a document with many children).

Miscellaneous

  • The WebDAV feature is now configured using Servlet 3.0 annotations and is not bundled by default anymore.
  • The Statistics Application is no longer installed by default. The same applied for the Charting Plugin.
  • The "Create Page" Panel now supports creating Nested Spaces (i.e. you can use references in the Space input field and you now need to escape special characters if you wish to have a space containing '.' or ':' characters for example).
  • The Active Installs Dashboard now displays the Java versions in an aggregated format, displaying only major + minor (e.g. "1.7", "1.8"). This makes it simpler to analyze the versions of Java used for XWiki.
  • When deleting a non-terminal page and the only child of that page is the 'WebPreferences' terminal page, the 'Affect children' checkbox will be checked by default. Normally, it would be unchecked, but in this case we`ve noticed that it`s very easy to forget about that document (since it's hidden and automatically created when going into 'Page Administration') and your deleted page might still show up in some places because of that leftover. You can still uncheck it if you know what you are doing.
  • The Link Label Generator nows supports Nested Pages by default and several new configuration formats have been introduced:
    • %s now uses the full space name (e.g. space1.space2). Note: Prior to 7.4.2/8.0M2 this was only displaying the last space name
    • New %ls option: displays the last space name.
    • New %np option: displays the nested page name (i.e. will display the space name for Nested Pages).
    • New %NP option: displays the nested page name with spaces between camel case words, i.e. "My Page" if the page name is "MyPage".
  • main wiki owner now have programming rights and not only admin rights

See the full list of JIRA issues fixed in this release.

For Developers

Extension Manager improvements

Feature version

Each extension feature now have its own version. See Extension Module Virtual Extensions for more details.

Namespace constraint

It's now possible to indicate a constraint on where an extension can be installed (only root namespace, etc.).

In Maven you can do that using <xwiki.extension.namespaces> custom property. See Maven Connector for more details.

Compare Extensions

org.xwiki.extension.Extension and org.xwiki.extension.ExtensionId now implement  Comparable to make easier manipulate them (order lists, find out if we are doing an upgrade or a downgrade, etc.).

Edit Action Events

Two new JavaScript events are available in edit mode:

  • xwiki:actions:beforePreview
    This event is fired after the user clicks on the "Preview" button from an edit mode, but before the edit form is validated. You can use this event to update the form fields before they are submitted to the preview action.
  • xwiki:actions:beforeSave
    This event is fired after the user clicks on the "Save" or "Save & Continue" button from an edit mode, but before the edit form is validated. You can use this event to update the form fields before they are submitted to the save action.

See the JavaScript API documentation for more information.

New SVG Rasterizing API

New API to convert a vector-based SVG content into some binary format that can be displayed in browser (i.e. rasterizing).

Deprecated and Retired projects

Upgrades

The following dependencies have been upgraded:

Miscellaneous

  • Generated URLs for document-based skin extensions (SSX and JSX) now contain the version of the document, so when a change is made to the extension the browser don't use an outdated version from its cache.
  • Support for chaining uberspectors, first introduced in XWiki as an enhancement of Velocity 1.5, has been part of the official library since Velocity 1.6. As such, we're deprecating our custom classes that provide this functionality. See the upgrade instructions
  • the XWiki Select Widget now offers a javascript API in the form of a jQuery plugin, to get the current value or clear the selection.
  • the WYSIWYG editor script service has a new method to render a document as a full HTML page. You can use it like this:

    <textarea class="wysiwyg">$escapetool.xml($services.wysiwyg.render('Some.Content.Template'))</textarea>
    The main difference between this API and the existing $doc.getRenderedContent() is that it replaces the skin extension hooks with the corresponding resource includes (e.g. style sheets includes), allowing us to define a WYSIWYG editor content template in a wiki page.

  • Replaced a few String-based APIs by Locale-based equivalents
  • All Document Events are now Cancelable and it's now possible for an EventListener implementation to cancel saving a Document.
  • Added new binding in the WatchList email template: subscriberReference. For example, this can be used to create a URL to the subscriber (i.e. user receiving the message) profile, where the notifications can be disabled:
    $xwiki.getURL($subscriberReference, 'view', 'category=notification')
  • It's now possible to directly compare a org.xwiki.extension.version.Version (at least its default implementation) to a String. Makes a lot easier to manipulate versions in Velocity for example. For example, before 8.0M2 you had to write:
    #set ($supportsNS = $services.extension.core.getCoreExtension('org.xwiki.platform:xwiki-platform-model').id.version.compareTo($services.extension.parseVersion('7.2')) >= 0)

    You can now write:

    #set ($supportsNS = $services.extension.core.getCoreExtension('org.xwiki.platform:xwiki-platform-model').id.version.compareTo('7.2') >= 0)
  • Developers can now enable the CSS Source Maps feature in the LESS Module, to help the CSS debugging.
  • GroupedJob#getGroupPath() can return null to not be grouped anymore

Translations

The following translations have been updated: 

Tested Browsers & Databases

The QA Tests are executed after the release has been done. Thus, they are being prepared now and will be published soon.

Performances tests compared to <last super stable version>

<a summary of the comparison with latest super stable version>

More details on <link to the test report>.

Known issues

Backward Compatibility and Migration Notes

General Notes

When upgrading make sure you compare your xwiki.cfg, xwiki.properties and web.xml files with the newest version since some configuration parameters may have been modified or added. Note that you should add xwiki.store.migration=1 so that XWiki will attempt to automatically migrate your current database to the new schema. Make sure you backup your Database before doing anything.

Issues specific to XWiki 8.0 Milestone 1

  • The WebDAV feature is now configured using Servlet 3.0 annotations and is not bundled by default anymore.
    • If you were using this feature, you should check the Instructions to install it manually.
    • If you were not using it, you should make sure to edit your web.xml to remove all the Servlet and Filter definitions for WebDAV (search for dav in web.xml).
  • If you have custom Velocity Uberspectors that implement org.xwiki.velocity.introspection.ChainableUberspector or extend org.xwiki.velocity.introspection.AbstractChainableUberspector, update them to org.apache.velocity.util.introspection.ChainableUberspector and org.apache.velocity.util.introspection.AbstractChainableUberspector. If you have a custom list of uberspectors specified under runtime.introspector.uberspect.chainClasses, just use the runtime.introspector.uberspect property for defining the list. Otherwise your custom configuration will be ignored!
  • If you wish to use '.' or ':' characters in the "Create Page" Panel you'll now need to escape them. For example: My\.Space\:name
  • If, in your application/custom code, you were using XWiki.EntityReferenceTree in the JavaScript API, you will need to update your code to the new structure of the children property of an XWiki.EntityReferenceTreeNode. Previously, the children property was a map of <nameString, XWiki.EntityReferenceTreeNode>. Now, it was changed to a map of <nameString, <XWiki.EntityType, XWiki.EntityReferenceTreeNode>> because, at each level, you can have both a XWiki.EntityType.DOCUMENT and a XWiki.EntityType.SPACE node with the same name (i.e. siblings) and the old implementation did not consider this case, thus creating a bug. Using the new structure, the bug is fixed, but old code had/has to be updated.

Mail API Unique Message Identifier

In order to solve XWIKI-12165, the unique identifier of each mime message sent has been changed to a SHA1 based on the Message-ID header and the list of recipients of the mails, ensuring uniqueness during a newsletter or mailing sending. To introduce this change, the MailContentStore and the MailListener API has been broken, and now use a new ExtendedMimeMessage instead of the simple MimeMessage for all arguments. The values messageId returned or used as argument in the API is no more equivalent to the Message-ID header, but is now the unique identifier returned by ExtendedMimeMessage#getUniqueMessageId(). Finally, the MessageMimeMessageFactory now returns cloned MimeMessage without changing the Message-ID.

We've introduced the possibility to explicitly create a link to a Space in XWiki Syntax 2.1, e.g. [[space:Space1.Space2]]. However if you had a subwiki named space the new notation will conflict with the syntax for referencing that wiki. Thus you'll need to edit existing links such as [[space:something]] to [[doc:space:something]]. And if you wish to reference a given space in the space subwiki, you'd write [[space:space:something]].

API Breakages

The following APIs were modified since XWiki 7.4.2:

  • Allow associating a version different from the extension version to the features and allow indicating namespace constraint in an extension
    org.xwiki.extension.Extension: Method 'public java.util.Collection getAllowedNamespaces()' has been added to an interface
    org.xwiki.extension.Extension: Method 'public org.xwiki.extension.ExtensionId getExtensionFeature(java.lang.String)' has been added to an interface
    org.xwiki.extension.Extension: Method 'public java.util.Collection getExtensionFeatures()' has been added to an interface
  • Deprecating this class in favor of the standard library class with the same name
    org.xwiki.velocity.introspection.AbstractChainableUberspector: Removed field inner
    org.xwiki.velocity.introspection.DeprecatedCheckUberspector: Removed org.xwiki.velocity.introspection.ChainableUberspector from the set of implemented interface
    org.xwiki.velocity.introspection.DeprecatedCheckUberspector: Removed org.xwiki.velocity.introspection.AbstractChainableUberspector from the list of superclasse
    org.xwiki.velocity.introspection.MethodArgumentsUberspector: Removed org.xwiki.velocity.introspection.ChainableUberspector from the set of implemented interface
    org.xwiki.velocity.introspection.MethodArgumentsUberspector: Removed org.xwiki.velocity.introspection.AbstractChainableUberspector from the list of superclasse
  • Young API. Better name
    org.xwiki.platform.flavor.FlavorManager: Method 'public org.xwiki.extension.repository.result.IterableResult searchFlavors(org.xwiki.platform.flavor.FlavorQuery)' has been added to an interface
  • Not really a breackage. Just moved to its own module.
    com.xpn.xwiki.plugin.diff.DiffPlugin: Class com.xpn.xwiki.plugin.diff.DiffPlugin removed
    com.xpn.xwiki.plugin.diff.DiffPluginApi: Class com.xpn.xwiki.plugin.diff.DiffPluginApi removed
  • Removed constant that shouldn't have been there
    org.xwiki.chart.ChartGenerator: Field COLORS_PARAM has been removed, but it was previously a constant
Tags:
   

Get Connected