Migration guide for developers

Written by The Jahia Team

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

Changing the group ID of a module cannot be done if another version of the module is resolved or started on your Jahia instance. We advise to do this operation when changing the parent version from 7.x to 8 for a smoother migration (to prevent issues during module deployment, and dependency resolution), and then follow the regular process described in the how to upgrade guide:

Replace the org.jahia.modules group id with your own group ID in the new version of your module compatible with Jahia 8
Upgrade your instance of Jahia from 7.3 to 8 using the fix applier
Before the first startup, copy the new version of your module in the digital-factory-data/modules folder (corresponds to step 4 of the How to upgrade guide)
Eventually, uninstall the old versions which are not compatible with Jahia 8 once Jahia has started

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:

Declare your module by creating the src/main/resources/javascript/apps/jahia.json file.
Register the app by creating the JS file that was declared in the first step.
Declare the route to your setting panel.
Activate the translation support for labels
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.

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

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.