This is the first release of the 3.x cycle. Conforming to the general themes of the 3.x cycle, a lot of features have been polished and improved, and a few new features have been introduced as well. The highlights of this release are: 

• Twitter-like messaging and networking inside the wiki,
• a new filesystem storage for attachments which allows huge attachments to be uploaded without requiring a lot of memory or database storage,
• improved dashboard editing,
• better cross-browser support and improved functionality for the WYSIWYG editor,
• a revamped UI for administration, improved office presentation import with a new gallery macro, 
• live suggestions for the search input, 
• a new UI for changing user avatars. 

On the developers' front, we've made it easier to reuse the XWiki rendering engine outside our own codebase, by extracting two new top level projects:

• XWiki Commons, holding generic modules not tied to the rest of the platform, 
• XWiki Rendering, holding all the XWiki-independent modules of the rendering engine.

We've setup a Jira dashboard to present the work done for the whole 3.0 release. In summary, 510 issues have been closed by 14 committers (and other contributors providing patches), out of which 236 are fixed bugs.

New and Noteworthy (since XWiki Enterprise 2.7)

Redesign of the Administration Application

We have redesigned the administration application providing a new layout and new icons (designed by Ciprian Amaritei). Administration sections are now grouped in several categories displayed using a vertical menu. Each section has been modified in order to be consistent with our Vertical Layout Usage Form Standard. The sections have been reorganized as well, making them more intuitive.

The WYSIWYG content editor can now be easily configured from the wiki administration. Look for the WYSIWYG Editor section under Applications category. You may still need to scan the list of available plugins and features in order to know what to enable. In the future we're hoping to integrate this information in the administration section.

Message Stream

Users can now post status messages which will be visible on the main dashboard and on the user profile page.

Users can follow each other's activity streams.

In order to see the members of your network and the network activity you can use the Network menu:

which leads you to the Network tab from the user profile page:

Dashboard Editing

A visual editor for dashboards has been implemented and is accessible by editing the page that contains a dashboard. Advanced users should use the Inline edit mode to edit the dashboard. In edit mode gadgets can be dragged by their title bar and moved around in different columns of the dashboard.

A new gadget can be added by choosing from the macros in the wiki, using a dialog similar to the WYSIWYG editor macro dialog.

A gadget can be removed from the dashboard using the gadget settings action.

Search Live Suggestions

This release introduces the first iteration on a "suggestions as you type" feature for the search box.

The suggestions proposed come from several sources, configurable in the wiki administration under the Search Suggest section. The sources configured by default include "Document name", "Document content", "Attachment name", "Attachment content" and "Users".

Gallery Macro and Office Presentation Viewer

The Gallery Macro helps you create a simple image gallery where images are displayed using a slide-show view. You can use images from any source, both internal (attached to a wiki page) and external. The gallery macro collects all the images it finds in the macro content. The Office Macro has been improved to use the gallery macro when displaying office presentations:

Attachment Selector Macro

Attachment Selector Macro is now bundled with XWiki Enterprise.

The UI for changing the user's avatar has been modified to use the attachment selector macro:

WYSIWYG Editor Improvements

Cross-Browser Support

The WYSIWYG content editor now has better support for Opera, Chrome and Safari browsers.

Improved Macro Support

In order to fix XWIKI-5691 and a few related bugs we had to refactor the way macros are displayed inside the rich text area of the WYSIWYG content editor. Along with this we introduced a few improvements in the way users interact with macros. Here's a list of changes:

• Macros are displayed now 100% like in view mode. Previously we were using a button HTML element to protect the macro output which gave macro output an inherent box layout. This was noticeable especially for multi-line in-line macros. This is fixed now:

  

• Macros that have output are emphasized only when hovered or selected.
• You can navigate the macro output with the arrow keys. The macro output feels like the rest of the content except that you can't edit it in place.
• You can copy content from the macro output.
• Press Enter to edit macro.
• Press Space to toggle between collapsed and expanded state.
• Ctrl + Shift + R reloads the macros.
• Ctrl + Shift + E expands all/selected macros.
• Ctrl + Shift + C collapses all/selected macros.
• Ctrl + Shift + M to open the insert macro wizard.

Known issues that we'd like to fix for 3.0 final:

• You can cut text from macro output.
• You can drag text into/from macro output.
• Placing the caret before/after a macro is still tricky.

Filesystem Attachment Storage

This storage engine allows very large attachments (over a gigabyte!) to be added to documents in the wiki while reducing load on the database. The Filesystem Attachment Store is fully implemented, with all the attachment-handling parts available as filesystem stores: the main attachment content store, the attachment history store, and the attachment trash store.

A disadvantage is that searching inside attachments is no longer possible using standard HQL (as is done in the DatabaseSearch implementation); this continues to be possible using Lucene.

We need feedback on how well it works before we can declare it production-ready, so we welcome all feedback from users, good and bad.

To enable it:

• Make the following changes to your xwiki.cfg file, under the "Storage" section:
  #-# The attachment storage.
  xwiki.store.attachment.hint=file
  
  #-# The attachment versioning storage. Use 'void' to disable attachment versioning.
  xwiki.store.attachment.versioning.hint=file
  
  #-# The attachment recycle bin storage
  xwiki.store.attachment.recyclebin.hint=file

The maximum attachment size will still be bounded by a configuration parameter so if you want to start attaching mega huge attachments right away, logged in as an administrator, open the<your site>/xwiki/bin/edit/XWiki/XWikiPreferences?editor=object page and scroll down until you find Maximum Upload Size, and change that number to something huge like: 999999999999. Then click save at the bottom of the page.

• Numbers that are too large cannot be parsed but the one above is known to be small enough. You will just have to live with only attachments smaller than a petabyte.

If you have an existing wiki and you want to start taking advantage of the attachment store, you can use the Filesystem Attachment Porter to move the attachments over to the filesystem. The description of the porter also contains more information about filesystem attachment storage in general so reading the page is recommended even if you don't need it.

Extension Manager

• Add minimalistic XAR support
  • Install/uninstall/upgrade a xar extension
  • The xar can have infinite number of pages and attachments, it's just limited by the size of each attachment right now until the storage API support fully streamed attachments
  • Very limited upgrade: import adds a new version to make sure not to loose anything, there is no real document merging handling
  • Delete pages from old version not in the new version when upgrading a XAR extension
• Add multiwiki support (install any extension on a specific wiki only)
• Add extension events

See Extension Module documentation for more details.

Rendering and Commons Top Level Projects

We have created a new top level project called XWiki Commons, which contains libraries that are generic enough to be reused outside of the XWiki project. New modules are now located under the org.xwiki.commons group id at http://maven.xwiki.org/releases/org/xwiki/commons/ .

We have also created a new top level project called XWiki Rendering, which contains a generic rendering engine. New modules are now located under the org.xwiki.rendering group Id, at http://maven.xwiki.org/releases/org/xwiki/rendering/. The modules in this project are independent of the XWiki core (they only rely on the new xwiki-commons modules), so they can be easily reused.

Miscellaneous

Besides the major features described above this release brings lots of bug fixes as well as improvements in various domains of XWiki, including PDF export, color theme editor and UI consistency. See the release notes for 3.0 Milestone 1, Milestone 2, Milestone 3 and Release Candidate 1 for details.

Translations

• The following translations have been updated: ca, cs, de, es, fr, gl, hi, hr, it, lv, nl, no, pl, pt, ro, ru, sk, sv, uk, vi, zh, zh_TW.

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 the improvements listed above.

Migration Notes

The Velocity engine was updated to version 1.7

We had to fix the following problems on the velocity code bundled with XWiki Enteprise:

• Escape quotes in interpolated strings (both ' and ") by doubling them ('' and "") (See VELOCITY-555)
• XABLOG-117: Blog application broken under Velocity 1.7
• XAADMINISTRATION-200: Configurable sections are broken ("configuration cannot be displayed because it was last edited by Admin who doesn't have permission to edit this page")
• XE-806:  Upgrade activity macro to work with velocity 1.7

Macro evaluation strategy

The main change is that Velocity 1.7 changed the way macro evaluations work. While before it was more flexible with many possible outcomes depending on what parameters were passed, and how they were used inside the macro, the current version simplified a lot the internal logic of variable assignments inside macros, which resulted in a critical regression for us. The same change was introduced between 1.6.0 and 1.6.1, but was reverted in 1.6.2 when we notified them of the regression, with the decision to go further with the change in 1.7.

To better understand the kind of code that doesn't work, take this example:

But:

This means that only macros that are supposed to assign and return a value in one of its formal parameters will stop working, and only when the formal and actual parameters have different names. Macros with signatures like:

The only macro in the global macros.vm that was broken by this change was #setVariableFromRequest, which is already fixed in the released version.

Now there's also a generic #setVariable ("variableName" $value) macro which can be used to emulate the call by sharing behavior in custom macros. How to use it:

Suppose you had a macro like this:

Here $isGlobal is the output variable which now doesn't always work. The updated version of the macro can be written as:

Pay attention to the last two lines in the macro.

In Velocity, when rendering $variable, where $variable is undefined or null, will cause the variable name to be printed instead. As it happens, when inside a macro, what gets printed is the name of the actual parameter (the one passed in the macro call), and not the formal one (the one declared in the macro definition). So, whenever $isGlobal is rendered as a string, the name of the actual parameter is obtained.

#set ($isGlobal = $util.null) will make sure that no matter what the previous value of the variable was, $isGlobal will be null from this point forward, and "$isGlobal" will output the name of the actual parameter.

When calling #setVariable ("$isGlobal" $result), the first parameter will contain the name of the actual parameter used when calling #isBlogGlobal.

Inside the #setVariable macro, the wanted variable is assigned using #evaluate.

Quotes and apostrophes inside strings

The second change is the escape syntax used inside strings for quotes and apostrophes. While before this used to work:

now this snippet would throw an exception. Trying to escape an apostrophe inside an apostrophe-delimited string would have failed even before.

In Velocity 1.7 it is possible to place both single and double quotes inside a string, by doubling that character. For example:

Update dashboard macro calls

Because of the implementation of XWIKI-5938, when upgrading from 2.x to 3.0, if the dashboard macro was used in its form from 2.5 (with the macro calls in the source of the page), it needs to either be manually converted to the objects form (if you want to benefit from all the dashboard improvements described above) either be converted it to a simple container macro with columns layout (if the focus is only column layouting of content). 

The steps to take are:

• if you want to benefit from all the dashboard improvements
  
  1. remove the content of the dashboard macro?
  2. use the visual dashboard editor (as described above in these release notes) to add the gadgets you need on the dashboard. If you need advanced content, such as custom scripts, etc, you can also use the objects editor for the current page to edit the XWiki.GadgetClass objects attached to the page.
• if you only need columns layout content
  
  1. modify the {{dashboard}} macro call to a {{container layoutStyle="columns"}} macro call, leaving the same content in the macro.

Note that the default Main.WebHome page distributed in XWiki Enterprise contains a dashboard, so if you upgraded XE and didn't upgrade this page, you'll need to manually upgrade that dashboard or manually merge it with the one from the 3.0 version.

This change also affects all the pages that included Main.Dashboard, such as the default spaces WebHomes, since Main.Dashboard contains a dashboard macro call. On upgrade of Main.Dashboard, if not upgraded as well, these pages will appear as empty. To restore previous behaviour, replace the {{include document="Main.Dashboard" /}} macro call with a {{dashboard source="Main.Dashboard" /}} call.

Update web.xml

Due to the package rename done for XWIKI-6158 when upgrading from 2.x to 3.0 you must edit your web.xml file and replace all occurrences of com.xpn.xwiki.wysiwyg with org.xwiki.wysiwyg.

XWiki Preferences

Several rarely used and deprecated preferences have been removed from the XWiki.XWikiPreferences class, in order to make way for more useful settings. If you were using any of these preferences, and you want to import the new XWikiPreferences document when upgrading, you should re-add that property manually afterwards. Here's the list of removed properties:

• convertmail - used by the old invitation manager, never really used in practice outside Curriki
• editbox_height and editbox_width - configurations for the size of the textarea elements, now fully styled with CSS
• macros_languages, macros_mapping, macros_groovy, macros_velocity, macros_wiki, macros_wiki2 - old macro polymorphism mechanism available in the xwiki/1.0 rendering and the WYSIWYG editor
• menu - configuration for the left-hand section in the extinct dodo skin
• notification_pages - mechanism for registering xwiki/1.0 documents containing Groovy code as notification listeners; both the syntax and the notification mechanism are deprecated, consider rewriting these listeners as components
• pageWidth - unused customization for the layout of the skin, an early experiment for the old finch skin, never fully used or exposed
• renderXWikiGroovyRenderer, renderXWikiRadeoxRenderer, renderXWikiVelocityRenderer - customizations for the xwiki/1.0 rendering process
• webbgcolor - old setting for the extinct dodo skin{{/dashboard}}

Included relative Links/Images

When using the {{include}} macro, links and image references found in the included document are now resolved locally, i.e. against the included document and not against the including document. This allows to have working relative links in documents even when those document are included from other documents.

Note the following broken use case:

• You have a first document (let's call it MyPage) doing an include of another document (let's call it Sheet)
• In Sheet you call $doc.getValue("content") where content is a textarea property containing wiki syntax
• Now imagine that in MyPage there's an Object and in the content property content there's a local image referenced (e.g. image:my.png).
• You'll suddenly find that the image is broken when viewing MyPage.

The issue is that Sheet is doing something not correct (which was working before), which is to directly inject wiki syntax but it looses the information about the source document. One solution to fix this is to use $doc.display("content") instead. A better solution (slightly more performant since it doesn't involve an internal execution of the HTML Macro) is to use:

In addition, you should be aware of a bug introduced in XE 3.0 with the following use case:

• You have a page with a link to the current page: [[label>>]]
• You include this page using the {{include}} macro
• You'll find that the link will point to the included page and not the including page as you'd expect.

This has been fixed in XE 3.1.1 and XE 3.2 (see XRENDERING-136 for details).

API Breakages

The following xwiki-core APIs were modified since XWiki Enterprise 2.7 (API breakages in modules that were moved to Rendering or Commons top level projects are not included):

The following XWiki GWT APIs were modified since XWiki Enterprise 2.7: