Changes in Magnolia 6 UI

This page covers the changes in Magnolia 6 UI as accumulated over Magnolia releases 6.0, 6.1.x and 6.2.x.

Summary

Magnolia UI 6.x comes with a completely resurfaced UI featuring the new Find Bar at its core. We have also rewritten select parts of the UI framework, particularly the content app framework. We generally adhere to the same concepts as before, but we have developed better implementations by using Vaadin 8.

The new implementations simplify app mechanics and configuration and use less custom Vaadin code, thus enabling cleaner and faster customization.

Magnolia UI 6.x contains both the UI framework used in Magnolia 5.7 (referred to as Magnolia 5 UI) and the Magnolia 6 UI framework. You can use:

  • Magnolia 5 UI components as well as your custom components and modules that rely on the previous Magnolia UI. We provide backward compatibility at both runtime and compile-time levels.

  • New Magnolia 6 UI implementations.

All UI components from both implementations are rendered with the new resurfaced theme design.

A large number of classes have been replaced or deleted, with many definition converters introduced for easier migration. See changes-in-magnolia-6-ui.csv for a full list of changes.

Apps configured in the new App Launcher layout will cause entries to appear in the log. To keep the log tidy, we recommend adjusting your App Launcher layout configuration and removing any apps you don’t use.

Why we have changed things

The main reasons for rewriting some of the UI components include:

  • Replacing the deprecated Vaadin 7 with Vaadin 8 (classes and frameworks)

  • Developing new implementations that are more component-driven so that the components are easier to reuse

  • Decreasing the amount of custom front-end (GWT) code and instead using the new stock Vaadin

  • Simplifying app mechanics and configuration

The resulting implementations are easier to maintain for us and cleaner and faster to customize for you.

What is preserved

In Magnolia UI 6.2, the functions and frameworks known from version 5.7 and earlier remain. By preserving class names and Magnolia module names, we keep runtime backward compatibility of custom modules with custom classes extending Magnolia classes.

Class names

Class and package names of the classes existing in Magnolia 5.7 have not changed and are still available in Magnolia UI 6.2. You can use these classes or extend them in your custom code.

Magnolia module names

A Magnolia module defines dependencies to other Magnolia modules and many other tasks. A Magnolia module can be defined with one file (i.e. a module descriptor). The Magnolia module descriptors of the UI project reside in Maven modules.

In Magnolia UI 6.2, no Magnolia module has been removed. The names of the Magnolia modules are still the same.

All previously known Magnolia modules still exist with the same name and provide the same functions. However, the module descriptor files defining those Magnolia modules may have been relocated due to changes in the composition of the Maven modules.

The magnolia-ui-framework-compatibility Maven module contains the module descriptors for the ui-contentapp and ui-framework Magnolia modules. The magnolia-ui-framework Maven module defines the new ui-framework-core Magnolia module.

What has changed

Look and feel

With Magnolia 6.x, the whole UI has been resurfaced to provide a modern, state-of-the-art user experience. At its core, the UI features the new Find Bar. All components of Magnolia 5 UI and Magnolia 6 UI are rendered using the new resurfaced theme design.

Maven modules

From Magnolia 5.7 and earlier, seven Maven modules have been removed. The classes of these modules are not lost. Instead, they have been relocated to the new magnolia-ui-framework-compatibility module or to the still existing magnolia-ui-framework module. New implementations have been added to the new magnolia-ui-framework-jcr module.

Removed Maven modules

  • magnolia-ui-actionbar

  • magnolia-ui-contentapp

  • magnolia-ui-dialog

  • magnolia-ui-form

  • magnolia-ui-imageprovider

  • magnolia-ui-vaadin-integration

  • magnolia-ui-workbench

We have created Maven relocations for these modules. This ensures backward compatibility for compile-time dependencies.

Added Maven modules

  • magnolia-ui-framework-jcr

    <dependency>
  <groupId>info.magnolia.ui</groupId>
  <artifactId>magnolia-ui-framework-jcr</artifactId>
</dependency>

  • magnolia-ui-framework-compatibility

    <dependency>
  <groupId>info.magnolia.ui</groupId>
  <artifactId>magnolia-ui-framework-compatibility</artifactId>
</dependency>

Features

Magnolia UI 6.2 brings, among others, the following new features:

  • Resurfaced design of the admin interface

  • Integrated Find Bar

  • Simplified app definition

  • Improved back-end data binding

    • datasource replacing contentConnector for apps and subapps

      • Flexible and versatile provisioning of data source components (DataProvider, PropertySet, etc.)

      • Clear and reusable data source observation mechanism

    • DataProvider replacing Container

      • Works with domain objects (for example, JCR nodes) instead of items

    • PropertySet replacing Item

      • Describes how to interact with domain objects to access/modify their properties via lambda functions

  • Flexible form definition

    • Simplified field API

    • Ability to define complex fields using form definitions

    • Separation of binding and logic

    • Custom layout support for forms

  • Generic field definition

    • Better compatibility with the new, more type-safe Vaadin data-binding APIs

What are the Magnolia 6 and Magnolia 5 UI frameworks

The Magnolia UI project version 6.x contains both the UI framework used in Magnolia 5.7 (referred to as Magnolia 5 UI) and the Magnolia 6 UI framework. You can use either framework.

Magnolia 5 UI

In Magnolia 6, Magnolia 5 UI has been relocated to the magnolia-ui-framework-compatibility module. Many Magnolia apps still rely on this old framework. The fully qualified class names have not changed, which ensures runtime compatibility for older custom components based on the classes from the Magnolia 5 UI framework.

Magnolia 6 UI

In the Magnolia 6 UI framework, the core components of the UI are located in the magnolia-ui-framework module inherited from Magnolia 5.7. The new magnolia-ui-framework-jcr module is also part of Magnolia 6 UI.

UI modules

For more information on the Magnolia 6 UI modules, refer to UI module.

Backward compatibility

The API changes are marginal. We provide backward compatibility at both runtime and compile-time levels.

Runtime compatibility

All classes from Magnolia UI 5.7 are also available in Magnolia UI 6.2. They have kept their fully qualified class names, which provides binary compatibility. Compiled custom modules (JAR files) built with Magnolia 5.7 also work in Magnolia 6.2 with the 6.2 UI.

Magnolia Maven module names are still the same. You do not have to change Magnolia module dependencies.

The binary compatibility together with the same-named Magnolia modules ensures runtime backward compatibility.

Compile-time compatibility

Module and submodule structures have been reorganized (see module changes). We have created Maven relocations for the removed modules. This ensures that you do not have to update the Maven module dependencies within the custom modules that depend on Magnolia UI modules.

How to upgrade

Make sure you upgrade your entire Magnolia bundle, not just the UI modules.

For general information on upgrading your Magnolia projects, read Upgrading to Magnolia 6.2.

With Maven

Make sure to set the version for the Magnolia UI project to 6.2.

In your bundle(s)

If you have a custom bundle based on a preconfigured Magnolia bundle, set the magnoliaBundleVersion property to 6.2. The Magnolia bundle will manage the UI version accordingly. For an example, see Upgrading Maven-managed webapps.

In custom modules

The composition of the submodules of the UI project has changed. Some modules have been removed, and their classes have been relocated to the magnolia-ui-framework-compatibility module. See Maven modules.

Since we have created Maven relocations for the removed modules, you do not have to change the dependencies to them within your custom modules.

However, to reflect the actual dependencies and to improve the readability of your POM files, you may want to replace the dependencies to the removed modules with the new compatibility module:

  1. Remove all dependencies from these Maven modules:

    • magnolia-ui-actionbar

    • magnolia-ui-contentapp

    • magnolia-ui-dialog

    • magnolia-ui-form

    • magnolia-ui-imageprovider

    • magnolia-ui-vaadin-integration

    • magnolia-ui-workbench

  2. Instead, add a dependency to magnolia-ui-framework-compatibility.

Manually

If you choose to do this manually, make sure you upgrade the entire bundle and not just the UI modules. Please follow the instructions in Upgrading manually.

Status

The following apps make use of the improved implementations (compatibility modules exist for their old implementations):

  • Assets

  • Definitions

  • Notifications

  • Pages

  • Personas

  • Preview

  • Resource Files

  • Segments

  • Tags

  • Tasks

Note that most of the other apps still rely on the old implementations. We will adapt them soon.

Magnolia 6.2 UI modules

Here is a list of all modules in version 6.2 of the Magnolia UI project. The list includes both the Maven modules and the Magnolia modules.

The Magnolia module column refers to the Magnolia module that belongs to the given Maven submodule.

Maven

groupId

artifactID

Function

Magnolia module

info.magnolia.ui

magnolia-ui-project

Parent reactor

n/a

info.magnolia.ui

magnolia-ui-framework

The primary module/SDK for Magnolia app development

This provides (among others) the content app framework, IoC support for UI components and scopes, Vaadin 8 data-binding facilities and UI view/state management.

It also offers convenience builders for selected Magnolia UI components (for example, alerts and dialogs).

ui-framework-core

info.magnolia.ui

magnolia-ui-api

This defines some core components for the UI such as:

  • info.magnolia.ui.api.action.Action,

  • info.magnolia.ui.api.app.App,

  • info.magnolia.ui.api.app.SubApp,

  • info.magnolia.ui.api.message.Message and others.

n/a

info.magnolia.ui

magnolia-ui-framework-jcr

JCR implementation of the Magnolia 6 UI framework

ui-framework-jcr

info.magnolia.ui

magnolia-resurface-theme

Magnolia 6 Vaadin theme based on Valo.

info.magnolia.ui

magnolia-ui-vaadin-common-widgets

Magnolia custom Vaadin/GWT components and extensions

This module contains mainly former Magnolia 5 widget implementations. For Magnolia 6, most of the components have been reimplemented with plain Vaadin. Consequently, this module may be split and partially deprecated in any future version.

n/a

info.magnolia.ui

magnolia-ui-mediaeditor

Magnolia 6 UI Media Editor

ui-mediaeditor

Magnolia stock apps

info.magnolia.jcrbrowser

magnolia-jcr-browser-app

JCR browser app

jcr-browser-app

info.magnolia.sample

magnolia-sample-app

Sample app

sample-app

Magnolia 5 compatibility

info.magnolia.ui

magnolia-ui-framework-compatibility

This module brings support for running Magnolia 5 content apps in Magnolia 6.

In particular, it contains former Magnolia 5 content-app components such as the workbench, forms and dialogs or image provider. It also provides JCR implementations of the deprecated Vaadin 7 Data API (for example, JcrNodeAdapter and HierarchicalJcrContainer).

The following Magnolia 5 Maven modules have been relocated to this module:

  • magnolia-ui-actionbar

  • magnolia-ui-contentapp

  • magnolia-ui-dialog

  • magnolia-ui-form

  • magnolia-ui-imageprovider

  • magnolia-ui-vaadin-integration

  • magnolia-ui-workbench

ui-contentapp

ui-framework

info.magnolia.ui

magnolia-ui-vaadin-theme

Magnolia 5 Vaadin theme.

n/a
Related topics
Feedback

DX Core

×

Location

This widget lets you know where you are on the docs site.

You are currently perusing through the DX Core docs.

Main doc sections

DX Core Headless PaaS Legacy Cloud Incubator modules