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.

This version brings some usability improvements such as simpler to use Include and Display macros, a new experimental and more performant notification store, and a lot of developer-level improvements (the work continued for the new User API, easier to implement inline editing of forms, API to modify configuration sources, a Mail obfuscation API, and more).

New and Noteworthy (since XWiki 12.3)

Full list of issues fixed and Dashboard for 12.4.

For Users

Selection preserved when switching between WYSIWYG and Source

 
We upgraded the CKEditor Integration extension and the new version comes with a long-awaited feature: the selection / caret is preserved when switching between WYSIWYG and Source area. This makes it really easy to:

• check the wiki syntax that corresponds to the current WYSIWYG selection
• check how the selected text from the Source area is rendered when switching back to WYSIWYG

Exclude Heading in Include/Display Macros

 
It's now possible to exclude the heading from an included page for both Include and Display macros, if the first element of that page is a heading.

Miscellaneous

• Simplify usage of Include macro: It's now simpler to use the Include and Display macros. Some complex and never-used parameters have been removed from the WYISWYG editor's macro dialog UI. Specifically, the page parameter is now hidden and for the Include macro the context parameter is now deprecated (and thus hidden). This also allows to display a single way to choose the reference of the included/displayed page and to ensure that users use the provided page picker.

• Object editor does not save automatically on object creation/deletion anymore: The behaviour of the Object editor changed to be more consistent: the changes performed like object addition or deletion are now only saved when clicking on the save button.

  Note that for developers we introduced new saving parameters to allow adding and deleting objects on a single save.

For Admins

• New experimental event store: A new Solr based event store has been introduced. It's still disabled by default (will be enabled as soon as the user notification use case is fully refactored to use it) and meant to be used more and more to replace the current Hibernate based event and event status store.

For Developers

Extension Manager improvements

• Extension without any associated file are now supported (Extension#getType() return null or empty string in this case)
• Maven modules of type pom or dependencies of type pom produce Extension with empty type
• In general Extension Manager now have a better support for Maven dependencies of type different from the default type (this produce extensions with different ids on Extension Manager side)

User Properties

 
There's now an API to modify user properties. Scripting example:

Default object sheet supports in-place editing

 
If you create a new application on top of XWiki following the manual FAQ tutorial you'll notice that starting with this version the application entries are editable in-place, from view mode. You can achieve the same thing for an existing application by copying and adjusting the code of the XWiki.ObjectSheet page over your existing sheet. Just make sure you update the name of the class used in the copied code.

Miscellaneous

• Configuration permissions: It's now possible to implement permission checking for ConfigurationSource properties, to decide who has the rights to view or modify them. To implement this check for your ConfigurationSource component, you need to implement the ConfigurationSourceAuthorization component role.

• More locale-oriented APIs: We deprecated Document#getTranslationList() in favor of the new Document#getTranslationLocales() so if you have Velocity scripts using $doc.translationList you'll notice a deprecation warning in the server logs which you can avoid by using $doc.translationLocales instead.

  We also added XWiki#getAvailableLocales() so you can now replace

  $xwiki.getXWikiPreference('languages').split('\s*[|, ]\s*')

  with $xwiki.availableLocales in your Velocity scripts.

• Deprecated Mail Script Services: The $services.mailsender and $services.mailstorage Script Service entry points have been deprecated in favor of $services.mail.sender and $services.mail.storage.

• Mail Address HTML Displayer: An HTML Displayer for email addresses (i.e. objects of type javax.mail.internet.InternetAddress) has been added (it displays the email address obfuscated if obfuscation is on). It's not used anywhere but can be called. Scripting example:

  {{velocity}}
  #set ($email = $services.user.properties.email)
  {{html}}
  $services.display.html.display('javax.mail.internet.InternetAddress', $email)
  {{/html}}
  {{/velocity}}

• Mail Address Conversion: There's now a Converter to convert from a String to an InternetAddress and vice versa. It's especially important since we've modified the User API's get/setEmail() to use an InternetAddress. This allows using Velocity scripts that call APIs accepting an InternetAddress by passing a string. For example:

  $services.user.properties.setEmail("[email protected]")

• Ability to hide macro parameters in WYSIWYG: Thanks to the introduction of a new @ProperyDisplayHidden annotation that can be placed on Macro parameter classes, it's now possible to hide the parameter inside the WYSIWYG's Macro editor. This is useful to hide complex parameters that should only be used in wiki edit mode for example.

  Example:

  public class IncludeMacroParameters
  {
  ...
     /**
       * @param type the type of the reference
       * @since 3.4M1
       */
      @PropertyDescription("the type of the reference")
      @PropertyGroup("stringReference")
      @PropertyAdvanced
     // Marking it as Display Hidden because it's complex and we don't want to confuse our users.
      @PropertyDisplayHidden
     public void setType(EntityType type)
      {
         this.type = type;
      }
  
     /**
       * @param page the reference of the page to include
       * @since 10.6RC1
       */
      @PropertyDescription("The reference of the page to include")
      @PropertyDisplayType(PageReference.class)
      @PropertyFeature("reference")
     // Display hidden because we don't want to confuse our users by proposing two ways to enter the reference to
     // include and ATM we don't have a picker for PageReference types and we do have a picker for EntityReference string
     // one so we choose to keep the other one visible and hide this one. We're keeping the property so that we don't
     // break backward compatibility when using the macro in wiki edit mode.
      @PropertyDisplayHidden
     public void setPage(String page)
      {
         this.reference = page;
         this.type = EntityType.PAGE;
      }
  }

• Mail Obfuscation APIs: There are now 2 new APIs related to Email Address Obfuscation:

  • API to get whether or not email addresses should be obfuscated. Scripting example:
    #if ($services.mail.general.shouldObfuscate())
    ...
  • API to obfuscate an email address. Scripting example:
    $services.mail.general.obfuscate('[email protected]')

• Configuration modifications: There's now a setProperties() API to modify ConfigurationSource properties. Scripting example:

  {{groovy}}
  import org.xwiki.configuration.*
  
  def cs = services.component.getInstance(ConfigurationSource.class, 'mailsend')
  cs.setProperties(['host' : 'localhost'])
  println cs.getProperty('host')
  {{/groovy}}

Upgrades

The following runtime dependencies have been upgraded (they have a different release cycle than XWiki Commons, XWiki Rendering and XWiki Platform):

• log4j API 2.13.2
• XStream 1.4.12
• Woodstox 6.2.0
• Tika 1.24.1
• Joda-Time 2.10.6
• Jackson 2.11.0
• JNR POSIX 3.0.55
• JNR FFI 2.1.13
• JGroups 4.2.3
• Infinispan 9.4.19.Final
• ICU4J 67.1
• Guava 29.0-jre
• Groovy 2.5.11
• Checker Qual 3.4.0
• Caffeine 2.8.2
• CKEditor Integration 1.44
• CKEditor Integration 1.45

Translations

The following translations have been updated: 

• French
• Russian

Known issues

• Bugs we know about

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 <project> <version - 1>:

Credits

The following people have contributed code and translations to this release (sorted alphabetically):

• Clemens Robbenhaar
• Manuel Leduc
• Marius Dumitru Florea
• Simon Urli
• Thomas Mortagne
• Usama ahmad
• Vincent Massol
• xrichard