This 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.
<div class=”clear”>
for floatsjmix:unconcentrated
is replaced by jmix:visibleInContentTree
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:
jmix:cmContentTreeDisplayable
mixin that needs to be replaced by jmix:visibleInContentTree
You will also be able to retrieve your server ID, which is required to request a Jahia 8 license key.
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.
Update the parent version to 8.0.0.0 in your pom.xml
file.
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:
org.jahia.modules
group id with your own group ID in the new version of your module compatible with Jahia 8digital-factory-data/modules
folder (corresponds to step 4 of the How to upgrade guide)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:
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.
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.
This section about section is applicable for Jahia 8.0.1+
Jahia 8.0.1 introduces two security improvements for actions:
requiredMethods="GET,POST"
in the Spring action files (see example). This has been applied to the following core actions:
In summary, when upgrading to Jahia 8.0.1 you must do the following with actions:
The following actions are deprecated in Jahia 8.0.1:
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:
src/main/resources/javascript/apps/jahia.json
file.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
. See here for an example of a server administration panel declaration.administration-sites
. See here for an example of a site administration panel declaration.jcontent
. See here for an example of the declaration of a panel in the additional accordion.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:
import {DefaultEntry} from '@jahia/moonstone/dist/icons';
Then use in the route declaration
icon: <DefaultEntry/>
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>')
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.
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 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).
If you were using the jmix:cmContentTreeDisplayable
mixin 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.
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.
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.
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.
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 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
.
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.
Note: this has been fixed in 8.0.2
If you were using custom spring configurations for pickers and need them in v8, you'll need to rebuild your customization following the documentation customizing Content Editor pickers.
Note: customization of pickers is supported from 8.0.2.