Following the goals established for the 3.x cycle, XWiki Enterprise 3.2 pushes forward in the directions of the Application Within Minutes and Extension Manager features. The highlights of this release are: 

• many extension manager improvements
• new implementation of the sheet system making it easier to bind sheets to objects without an explicit inclusion of the sheet in the document content
• user dashboards giving each user the possibility to configure their own home page
• introduction of wiki workspaces, as a more collaborative way of managing an XWiki virtual farm
• improvements of search results scoring
• storage improvements, bringing in numerous performance and compatibility improvements
• conversion of the panels application to the XWiki 2.0+ syntax
• easier activation and configuration of Google Analytics

And on the developers' front:

• CSRF prevention enabled by default
• support for DocBook syntax
• xwiki-commons and xwiki-rendering are now published on the central Maven2 repository
• some major code cleanup due to the retirement of some very old plugins and the move of legacy/deprecated code into separate modules

We've setup a Jira dashboard to present the work done for the whole 3.2 release. In summary, 338 issues have been closed by 12 committers (and other contributors providing patches), out of which 32 are new features, 84 are improvements and 149 are fixed bugs.

New and Noteworthy (since XWiki Enterprise 3.1)

Extension Manager improvements

Progressing towards the completion of the extension manager, 3.2 adds support for:

• virtual extensions, or aliases for extensions that have changed their identifier
• automated 3-way merging of wiki documents, which brings update capabilities for XAR extensions
• better error reporting during installation, upgrade or removal of extensions
• XWiki repository REST protocol has been rewritten
• local extensions repository moved from ~/.xwiki to container persisted directory
• display all the extensions metadatas when resolving it

New implementation of the sheet system

In preparation for the Application Within Minutes major feature, this release introduces a new way of associating objects with the sheets used for displaying them. Whereas until now the content of the document had to explicitly contain an {{include}} statement in order to display an attached object, an object can pull its sheet automatically. This frees up the document content for a more useful purpose.

The new sheet detection mechanism allows for more flexibility. Whereas with the old {{include}} mechanism sheets could only be bound to a specific document, the new implementation brings a plethora of additional options: sheets can be associated globally to a class, they can be differentiated on a specific action (allowing to use different sheets for view, edit or export), they can be specified for different users or groups, or even forced explicitly via request parameters.

With the new sheet mechanism, form editing can now be performed using the /edit/ action, either automatically for documents containing sheet-bound objects, or explicitly forced using the editor=inline request parameter. In consequence, the /inline/ action has been deprecated.

Most of the classes/sheets bundled with XWiki Enterprise have been updated already to use the new mechanism. Upgraded wiki instances containing documents which still rely on the old sheet inclusion mechanism will continue to work, but it's recommended to update them.

You can read more about this feature on the Sheet Module documentation page.

User Dashboards

After wiki- and space-wide dashboards, this release brings support for personal dashboards. Each user can define their own dashboard in their profile document, and they can use it either in their profile document, or display it instead of the homepage default dashboard.

Wiki Workspaces (Experimental)

We have adopted the Workspace Application as an XWiki platform project. In a few words, the Workspace Application allows regular users to create workspaces where they can collaborate on a specific topic. A workspaces is, in essence, a regular subwiki that is to be used by a group of global users. It allows global users to join or be invited and to easily navigate through the available workspaces and back to the main wiki.

The Workspace Application is best suited for intranets or any other use case that involves having only global users and going back and forward through projects or departments that are separated in subwikis. It is not intended for environments such as wiki farms, where each subwiki is a bubble, having its own users, oblivious about other subwikis or the main wiki. This later use case is better served by XWiki Enterprise Manager.

The Workspace Application is not bundled by default with any XWiki product, but it can be installed as an extension.

Improved search results scoring

The search results retrieved by the Lucene plugin have been for a long time the target of many complaints, since documents that were actually relevant for a query usually appeared too low in the results list. This issue has now been improved, by scoring results differently depending on the field where the search query matches. A hit on the document title will ensure that the document will be among the first results, while a hit on the owner document's name of an attached image will place the image towards the end.

Storage improvements

The version of Hibernate used by XWiki has been upgraded to 3.6.7, bringing in numerous performance and compatibility improvements. Additionally, the mapping and configuration files have been reviewed, upgraded and simplified. InnoDB, which used to be only recommended, is now enforced by default when creating a new database or table in MySQL. Further performance enhancements for default installations come from the fact that the proper indexes needed for efficient database access are now auto-created at startup, eliminating the need for manual configuration.

Converted the Panels application to the new XWiki syntax

Although only a rewrite, with no new features, this makes it easier to edit panels. Several panels have also been cleaned up and optimized, minimizing the use of inline HTML, which was replaced with wiki markup.

Easier activation and configuration of Google Analytics

In older versions, XWiki provided a velocity template that could be edited to enable Google Analytics. Still, this required either access to the server or overriding a template in the skin document, which was not that easy to discover. Starting with this version, there is a custom section in the wiki Administration which makes it extremely easy to enable Google Analytics tracking.

The new implementation also allows to define different tracking accounts for each wiki, and to use more than one tracking account per wiki.

For Developers

CSRF prevention is enabled by default

Cross-site request forgery is an exploit which allows a malicious site to perform arbitrary actions on the victim site on behalf of a currently logged in user. Starting with version 2.5 XWiki comes with a built-in prevention mechanism against CSRF. Although this protection was introduced about a year ago, it wasn't enabled by default since several actions were broken by this change. While we now expect almost everything to work fine, please report any problem you might find.

New rendering features: DocBook syntax and {{comment}} macro

The XWiki rendering engine includes support for parsing from and rendering into the DocBook syntax, thanks to the corresponding Doxia modules. Among other usecases, this means that:

• XWiki pages can be transformed into DocBook documents to be further transformed into other formats, like man pages or epub documents, making XWiki a better tool for documentation writing
• existing DocBook documents can be imported directly into an XWiki instance, thereby benefiting from the lifecycle of any wiki document, such as easy on-line editing and instant HTML preview
• the xwiki-rendering project can be integrated in a tool to convert wiki markup into DocBook content

A new {{comment}} macro is provided for including textual comments inside documents, other than HTML <!--comments --> inside a {{html}} macro or Velocity #* comments *# inside a {{velocity}} macro.

Improvements to the Suggestion and Spotlight Search widgets

Extensive polishing and bugfixing work has been done for the Spotlight-like search, making it more stable and easier to use and customize. Some improvements include the option to display only one "loading" status for all the suggestion sources, the option to display hints next to each search result, better highlighting of matches between the input text and the displayed items, plus various bugfixes.

New JavaScript testing framework

Unit tests for JavaScript code can now be written using the Jasmine framework for behavioral-driven development.

Example tests for the input suggestions widget:

Named parameters for the event stream

The new event stream module offers support for arbitrarily named parameters to be associated with stored events. This is a better way of dealing with extra parameters than the old up to 5 numbered parameters supported by the ActivityStream plugin. The limitation is that both the name and the value must be strings of at most 255 characters. Read more about the event stream module and how to use these named parameters in the module's documentation.

GPG signed artifacts

Starting with this release, all build artifacts will be signed by one of the XWiki developers using a PGP signature. Such signatures are available in our maven repository as .asc files next to each artifact. We advise you to check the signatures of the files you download to make sure there are no problems with them.

To check the signatures, you should:

# Install GPG, if it's not already installed on your system
# Download both the artifact and its .asc counterpart
# Run gpg --verify --keyserver-options auto-key-retrieve=true artifact-file.jar.asc

Official HTTPS support

While our sysadmins have been able for a very long time to use the right configuration for Tomcat, Apache HTTPD and the AJP connector between them, starting with 3.2 the XWiki community pledges to officially maintain proper HTTPS support for XWiki.

xwiki-commons and xwiki-rendering published on the central maven repository

Starting with this version, xwiki-commons and xwiki-rendering are deployed on the central maven repository, which makes it easier to reuse modules from these projects inside a third party application, unrelated to XWiki.

New location for storing persistent data

Because of a bug in the old core, it was very hard to configure a directory where data could be safely stored. This bug has been fixed for the 3.2 release. Additionally, a new API for accessing this directory has been introduced, a few components have been updated to use this location, and in the default standalone distribution a new data/ directory is configured to store permanent data.

Deprecated and Retired projects

By default, the platform is now free of legacy code. Deprecated features have been officially removed, but are still included via aspects for backwards compatibility in the final distribution packages. For each module that had legacy code, there is a corresponding module in xwiki-commons-legacy or xwiki-platform-legacy that generates an extended jar containing the deprecated classes or methods on top of the clean code. Apart from moving already deprecated code, such as old observation events or the backwards-compatibility aspects for the old core, new deprecations appeared in this release:

• the old XWikiCache API, replaced by the cache module
• the old notification system, replaced by the observation module
• the support for the old @Requirement way of declaring injected dependencies; @Inject combined with @Named should be used instead

Several very old and unmaintained projects have been retired as repositories in the xwiki-contrib organization on GitHub:

• adwords plugin
• Albatross skin
• alexa plugin
• calendar plugin and application
• exoplatform plugin
• photo album application
• S5 presentation application
• workstream application

The swizzle-based plugin for interacting with Jira has been replaced by a new jira module which uses the new REST APIs offered by Jira instead of the deprecated XML-RPC services. The old swizzle plugin code is no longer maintained, but it can be retrieved from older tags.

Various

• XCOMMONS-14: Added new XML manipulation methods to the XMLUtils helper class.
• XCOMMONS-17: Added a bridge that converts LogBack log events into observable events.
• XCOMMONS-19: Added new methods to $escapetool for encoding test into the Quoted-Printable and the B and Q MIME encodings. These methods are usually needed when generating emails.
• XWIKI-6832: Added support for OpenOffice 3.3.

Upgrades

The following dependencies have been upgraded:

• Aether 1.13
• batik-rasterizer 1.7
• commons-configuration 1.7
• commons-lang 3.0.1
• Doxia 1.2
• Groovy 1.8.2
• Hibernate 3.6.7 Final (and related dependencies)
• hibernate-validator 4.2.0.Final
• HTML Cleaner 2.2
• Jetty 7.4.5
• JodConverter 3.0-beta-4-xwiki-20110822
• jruby 1.6.3
• Logback 0.9.30
• Lucene 3.4
• Reflections 0.9.5
• Selenium 2.7.0
• slf4j 1.6.2

Miscellaneous

Besides the major features described above, this release brings lots of bug fixes as well as improvements in various domains of XWiki, including color theme usage and refreshing, observation events, annotations, multilingual mode, PDF export, special characters handling, section editing, deleted document and attachments trash, flickering integration tests, and many build reusability and enforcements. See the full list of closed issues and the release notes for 3.2 Milestone 1, Milestone 2, Milestone 3 and Release Candidate 1 for details.

Translations

The following translations have been updated:

• German
• French
• Italian
• Latvian
• Dutch
• Russian
• Swedish
• Simplified Chinese

Supported Browsers

Here's the list of supported browsers for this version (i.e. browsers that we've tested as working):

Internet Explorer

8

Internet Explorer

9

Firefox

3.6.23

Firefox

7.0

Firefox

7.0.1

Chrome

14

Known issues

• Bugs we know about

Test Report

You can check the manual test report to learn about what was tested and the results on various browsers.

Backward Compatibility and Migration Notes

General Notes

You may also want to import the default wiki XAR in order to benefit from all the improvements listed above.

Issues specific to XWiki Enterprise 3.2

• The behavior of the HTML Macro has changed slightly (as a consequence of the upgrade to HTML Cleaner 2.2): CDATA elements not located inside SCRIPT or STYLE elements are now removed when cleaned (i.e. when the clean parameter is true). If you don't want any cleaning done, use clean="false".
• Since the Lucene engine has been upgraded to a new major version, you should completely rebuild the index. This can be done from the main wiki administration, in the Search section.
• See the retired section above for the list of removed modules. The most important one is the removal of the Albatross skin from the distribution. Be careful to review your xwiki.cfg file and update the xwiki.defaultskin and xwiki.defaultbaseskin properties and make sure their values is now colibri (unless you wish to continue using Albatross, in which case you'll need to install an older release of the Albatross skin in your installation).
• The ehcache library is no longer packaged by default. If you've configured a second level hibernate cache using this library, make sure you manually download it in the libs or replace your configuration with another cache engine.
• The oscache based implementation of the xwiki cache module is no longer packaged by default. If you'd like to use this specific implementation, make sure you explicitly include it in your distributions.
• See the backward compatibility and migration notes for the new implementation of the sheet system.
• The permanent data storage directory is now by default data, in the root of the standalone distribution. This is where you'll find, for example, the Lucene index, the custom extensions installed by the extension manager, or the attachments when the filesystem attachment storage is configured. If you're upgrading from an older version, make sure you first move the existing data from the jetty/work/ directory. You can configure the location of the permanent data storage in xwiki.properties via the container.persistentDirectory setting, and, for older code using the XWiki.getWorkDirectory method, in xwiki.cfg via the xwiki.work.dir setting.

Fixing applications broken by the CSRF prevention mechanism

If your application has been broken by this change, usually all it takes to make it compatible with the CSRF prevention mechanism is to add a hidden field inside the submitted forms, or to add a request parameter to the data-altering URLs:

If you want to completely disable this feature, edit WEB-INF/xwiki.properties and add csrf.enabled = false at the end.

API Breakages

The following xwiki-core APIs were modified since XWiki Enterprise 3.1: