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.

This is the first release of the 8.x cycle. This version introduces a new experimental minimal XWiki distribution and a new Distribution Wizard step to create the first user with administration right instead of importing the Admin user. It also adds many improvements related to nested spaces on copy and rename features, location picker, link syntax. Various new option have been added to the chart macro and as usual you will find many more improvements in the detailed release note.

New and Noteworthy (since XWiki 7.4.2)

Full list of issues fixed and Dashboard for 8.0.

Rename and Copy UI

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

  

  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.

  

  See the Page Lifecycle documentation for more information.

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

  

  

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

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.

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:Page@file.jpg translates technically to image:Page.WebHome@file.jpg) and for attach: syntax (e.g. attach:Page@file.ext translates technically to attach:Page.WebHome@file.ext).

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)

Disable header and footer in PDF export

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

Performance Improvements

• 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 when XWiki restarts. This prevents recompilation of CSS files and thus improves a lot first time access to (sub)wiki pages.

For more informations about this, please see the LESS module Cache.

New XWiki distribution

The work on a minimal 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 extensions.xwiki.org for now).

The size of this new distribution is still not very far from the XWiki Enterprise one (188MB compared to the 219MB of XWiki Enterprise); 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 a limitation in XWiki 8.0 that we hope to fix in 8.1: supporting upgrades of invalid flavor (propose a valid new flavor in this case).

This minimal distribution is still experimental and should not be put in production yet but the momentum has been started and we excited by the new opportunity that Flavors will bring to XWiki!

Custom Admin User

XWiki Enterprise has always had a hardcoded Admin user (with password admin). This was causing security issues since admins had to change the password explicitly or they'd risk anyone being able to connect to their instance...

This time is now gone and from now on you are asked to register your own user which will be the owner of the wiki (meaning that whatever you do, you won't ever loose Admin Rights for that user, unless you change the owner of course) when you install XWiki from scratch. Note that we've kept a standard Admin user for the all in one Jetty/HSQLDB package for the moment.

Chart Macro Additions

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

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

  

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

  

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

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".
• The main wiki owner now has Programming Rights by default and not only Admin Rights
• Better error checking for the Color Theme Displayer: In the administration, an error message is now displayed if the configured Color Theme is invalid. It could happen after an upgrade if you were using an old Colibri Theme.

  

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

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). Note that this API is not bundled by default and you'll need to install it with the Extension Manager if you wish to use it.

Deprecated and Retired projects

• Colibri skin moved to https://github.com/xwiki-contrib/skin-colibri
• Color Theme application moved to https://github.com/xwiki-contrib/skin-colibri
• Old XWiki 1.0 syntax rendering framework moved to https://github.com/xwiki-contrib/xwiki-platform-oldrendering
• XWiki 1.0 rendering parser moved to https://github.com/xwiki-contrib/xwiki10-parser
• XWiki 1.0 chart macro moved to https://github.com/xwiki-contrib/xwiki-platform-chart-macro10

Upgrades

The following dependencies have been upgraded:

• Bouncy Castle 1.54
• HTMLCleaner 2.16
• Jackson 2.7.1
• JGroups 3.6.7
• FOP 2.1
• Slf4j 1.7.14
• CSS4J 0.20
• Joda-Time 2.9.2
• slf4j 1.7.16
• Logback 1.1.5
• Doxia 1.17
• Aether 1.1.0
• Less4j 1.16.0
• Pygments 2.1.1
• org.eclipse.sisu.plexus 0.3.3
• Tika 1.12
• Groovy 2.4.6
• JGroups 3.6.8
• httpclient 4.5.2
• slf4j 1.7.18
• Jackson 2.7.2
• logback 1.1.6

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: 

• Danish
• French
• Latvian
• Dutch
• Polish
• Portuguese (Brazil)
• Russian
• Slovak

Tested Browsers & Databases

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

	Browser	Test Result
	Google Chrome 49	Not Tested
	Mozilla Firefox 34	Jira Tickets Marked as Fixed in the Release Notes
	Internet Explorer 10	Not Tested
	Internet Explorer 11	Not Tested

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

	Database	Test Result
	HyperSQL 2.3.3	Not Tested
	MySQL 5.x	Not Tested
	Oracle 11.x	Not Tested
	PostgreSQL 9.4.5	Jira Tickets Marked as Fixed in the Release Notes

Performances tests compared to 7.4.2

The important speed boost in first access of the UI is due to LESS cache being kept when restarting. See Performance Improvements for more.

Summary

"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

Memory

More details on performance comparison on single wiki between 8.0 and 7.4.2.

Known issues

• Bugs we know about

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.

New Space prefix for wiki links

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

• Removed constant that shouldn't have been there
  org.xwiki.chart.ChartGenerator: Field COLORS_PARAM has been removed, but it was previously a constant