Written by The Jahia Team
   Estimated reading time:

his topic lists changes that developers should be aware of in Jahia 8. Please review the changes carefully. We also strongly encourage you to read the Migration guide for functional administrators and Migration guide for system administrators guides and the known issues and limitation page.

Several modifications were made in Jahia that require you to update your modules.

Overview

Things to consider

  • POM.xml update required
  • Compilation for Jahia 8.0
  • Check Maven Group ID, org.jahia.modules is reserved for Jahia
  • Review Spring updates, consider OSGI for future development
  • Assess use of Site Settings by your module -->see updates to server and site settings
  • Assess usage of Contribute Mode Settings on content area and lists, see change to Content Type restrictions
  • Redirections to back office interfaces
  • Templates only: change to default use of <div class=”clear”> for floats
  • jContent tree display changes. jmix:unconcentrated is replaced by jmix:visibleInContentTree.

Helper module

To help you assess what you need to do with each of your modules, you can deploy our helper module (available on the store) in your Jahia 7.3 environment. It provides a new entry in Administration>System Components>V8 Migration Helper. From there, you will be able to generate a report on the modules currently deployed on your server to help you identify modules that:

  • use org.jahia.modules as group id, which need to use your own group id
  • declare Server Settings and Site Settings that you need to declare again to specify precisely where they should appear in Jahia
  • use Spring that will require a particular attention
  • use custom date formats in their definition
  • use the jmix:cmContentTreeDisplayablemixin that needs to be replaced by jmix:visibleInContentTree
  • use Contribute Mode settings in templates

You will also be able to retrieve your server ID, which is required to request a Jahia 8 license key.

Modules require new compilation

When you upgrade to Jahia 8.0, you must change the parent version in the pom.xml file for your modules and recompile them using JDK 8 as target version. Jahia 7 modules cannot be deployed on Jahia 8. You may have to handle a couple cases, mentioned previously and explained in this topic, but no major refactoring is needed.

POM update

Update the parent version to 8.0.0.0 in your pom.xml file.

Maven group ID

Ensure that you are not using org.jahia.modules as group ID for your modules as this group ID is reserved for Jahia modules (as such modules require a Jahia signature).

Spring

At Jahia, we firmly believe in OSGi and use it over Spring for our new developments. We are also in the process of removing Spring from our own modules. This will take time. In Jahia 8, we are now exposing:

  • Spring 3.2 for module compatibility. As you may not be able to refactor all your modules to be fully OSGi, you can keep using this Spring version to ease your migration process.
  • Spring 5.2. This is provided through a Karaf feature and is not used by Jahia itself. Use it if you need a more recent version of Spring and if you cannot refactor your modules to use OSGi.

The following information shows how to update modules only if you plan to continue using Spring 3.2. If your module still needs to use Spring 3.2 which is provided by Jahia core, then you will have to explicitly declare the following requirement in the POM file:

<require-capability>osgi.extender;filter:="(osgi.extender=org.jahia.bundles.blueprint.extender.config)"</require-capability>                    

In this process, you may face dependency issues at module deployment time. You will need to clean up some Spring dependencies and explicitly declare the missing ones. For instance, if your module is using org.springframework.core.io.Resource, then you need to explicitly declare a Maven dependency to the Spring framework to fix the issue.

Rules

If your module defines rules, due to the way rules are registered, as soon as a file with .xml is present in the META-INF/spring folder, a Jahia spring context is required to register the rules.
If the XML file is not used then remove it, or if it is not related to a Jahia Spring context then move it to another location. 

Site Settings and Server Settings

Declaration of settings

Navigation updates in Jahia 8 change where Site Settings and Server Settings can display. Now you must explicitly declare the location of your custom Site Settings, Server Settings, and User Dashboard panels.

This is done in four easy steps, part of our app-shell module documentation:

  1. Declare your module by creating the src/main/resources/javascript/apps/jahia.json file.
  2. Register the app by creating the JS file that was declared in the first step.
  3. Declare the route to your setting panel.
  4. Create the JSON resource bundles files in src/main/resources/javascript/locales/.

These four steps have been followed in this commit, in order to declare the Site setting publication panel in the Additional accordion in jContent. In the end ,it was only a matter of creating the javascript folder in the site-settings-publication module.

Here are the suggested locations to use for your settings:

  • Administration>Server accordion
    The location for your Server Settings. The target must start with administration-server.  See here for an example of a server administration panel declaration.
  • Administration>Site accordion
    The location for your Site Settings that relate to administration functionality. Users require the Site administration access permission to see these panels. The target must start with administration-sites. See here for an example of a site administration panel declaration.
  • jContent>Additional accordion
    The location for your Site Settings that fill functional purposes, for example, that are used by editors. The target must start with jcontent. See here for an example of the declaration of a panel in the additional accordion.
  • Dashboard>My workspace
    The location for the User Dashboard panels, which are settings panels that belong to a user. The target must start with dashboard. See here for an example of a dashboard panel declaration.

Using icons for these entries

For consistency, we advise you to use an icon only for entries at the first level. Subentries should not have icons.

Note that it is currently not possible for you to easily declare a new icon to use for your settings. Alternatively, you can use:

  • Our DefaultEntry icon
    You need to import it in the file declaring the route
    import {DefaultEntry} from '@jahia/moonstone/dist/icons';
     Then use in the route declaration
     icon: <DefaultEntry/>
  • Your own icon in SVG format, for instance
    icon: window.jahia.moonstone.toIconComponent('<svg style="width:24px;height:24px" viewBox="0 0 24 24"><path fill="currentColor" d="M19 6V5A2 2 0 0 0 17 3H15A2 2 0 0 0 13 5V6H11V5A2 2 0 0 0 9 3H7A2 2 0 0 0 5 5V6H3V20H21V6M19 18H5V8H19Z" /></svg>')

Usage of material UI

If you have multiple Site or Server Settings and are using Material UI, ensure that you wrap the top-level render with StylesProvider from Material UI and generate the class names with your own prefix, for example:

<StylesProvider generateClassName={createGenerateClassName({productionPrefix: ‘sample-settings-app’})}>
...
</StylesProvider>

This addition avoids class name conflicts with multiple instances of Material UI. See this FAQ for more information.

You do not have to make other modifications to display your custom settings panel in Jahia.

Redirections to back office interfaces

The new Jahia interface uses slightly different URL patterns. We have set the following redirections for compatibility reasons to avoid 404 links. If you were using these URLs in your modules, it is advised that you update these URLs when possible to keep your code up-to-date. As we have included these redirections, this change on your side is not mandatory.

URL pattern in 7.3 Redirection in 8.0
/cms/edit/ /jahia/page-composer/
/cms/contribute/ /jahia/page-composer/
/cms/contentmanager/ /jahia/jcontent/
/administration /jahia/administration
/cms/dashboard /jahia/dashboard

By default, areas do not add <div class="clear"></div> anymore

By default in Jahia 7, areas and lists add <div class="clear"></div> in generated HTML to handle floats. The workaround was to set the omitFormatting property to true (as its default value was false) when developing your template, for example: <template:param name="omitFormatting" value="true"/>.

We have changed this behavior. By default (if omitFormatting is not set), Jahia does not add <div class="clear"></div> to handle floats. You can see the modification in github here: https://github.com/Jahia/default/pull/12/files

If you want to preserve the previous behavior, you must use <template:param name="omitFormatting" value="false"/> . While you can also fork the list.jsp view, this is not advised as you will not benefit from potential updates on this file (or you will have to manually report them on your fork).

jmix:visibleInContentTree replaces jmix:cmContentTreeDisplayable

If you were using the jmix:cmContentTreeDisplayablemixin to display your content type in Content and Media Manager tree as a content folder, then you need to use jmix:visibleInContentTree instead. This new mixin enables you to display such content in content trees without adding a dependency to jContent in your module. You also need to remove the dependency to Content and Media Manager in your module.

Contribute mode settings

See the Removal of Contribute Mode and continuity of Contribute mode settings section in the Functional administrators migration guide for context before reading the following instructions.

If you were using Contribute mode settings in your templates, then the settings will not be applied in Page Composer and jContent. You need to define these restrictions in the List restriction section in Studio.

studio-area-restrictions.png

The migration helper module includes such modules in its report. If you are not using the migration helper module, you can execute the following query using the JCR Query console from the tools:

SELECT * FROM [jmix:contributeMode] where isdescendantNode("/modules")                    

If the query returns results and those results are under a /templates node, you will need to perform the modifications described above if you want to keep your contribution restrictions.

Permission changes

Jahia 8 includes several new permissions and replaces several permissions from Jahia 7.3. We recommend you to learn about these changes in the Migration guide for system administrators.

Content Editor related

Template mixin

Template mixins are not supported in Content Editor 2.0. Template mixins provide the ability to display a field depending on the value of a mixin or another field. We advise you not to update your modules to bypass this limitation. They will be supported in Content Editor 2.1 which will be released soon after V8. In the meantime, you can access such fields by using the legacy UI, available under the Advanced options tab in Content Editor.

Custom Java validator

Mandatory fields and regular expression validation are supported by Content Editor. However, custom Java validators are not. If you have implemented custom validators, please reach out to Jahia support.

Cache mixin

Cache mixin (originally in the Options tab) is now hidden by default to make the user experience simpler for editors. If you need to access the mixin, the legacy Options tab is available under Advanced options tab in Content Editor. If you need to show it again for all users, see Displaying cache and skins options.

Skinnable mixin

Skins mixin (originally in the Layout tab) is now hidden by default to make the user experience simpler for editors. If you need to show it again for all users, see Displaying cache and skins options.

Date format in the form

Date format in CND files is not supported anymore. The date format in the UI depends exclusively on the language of the user in Jahia. If the editor uses Jahia in English, it will be mm/dd/yyyy, if the editor uses Jahia in French it will be dd/mm/yyyyy.

Images in choicelist

Content Editor cannot display images in choicelists which are dropdowns that display in Content Editor. If this is a significant issue for your organization, please reach out to Jahia support.