Magnolia 5.3 reached end of life on June 30, 2017. This branch is no longer supported, see End-of-life policy.

Page tree
Skip to end of metadata
Go to start of metadata

(warning) Magnolia 5.1+ In order to add custom widgets or Vaadin addons to your Magnolia app, you need to provide a new WidgetSet. This means, you need to compile the new WidgetSet and configure Magnolia to use it.

WidgetSet basics

A Vaadin Widgetset is a GWT module that ties together client side component implementations used by a particular Vaadin application. It is the part of the client side terminal that creates components from UIDL messages generated by the server side. – WidgetSet - Vaadin

Important to know about WidgetSets:

  • In any GWT or Vaadin application, there can be only one WidgetSet. Since the Magnolia admin UI is a Vaadin application, Magnolia can have only one WidgetSet too.  Therefore, it should inherit all the WidgetSets you intend to use.
  • Your custom WidgetSet must always inherit Magnolia's default WidgetSet info.magnolia.widgetset.MagnoliaWidgetSet.
  • A WidgetSet must always be GWT-compiled before you run your Web application, and it has to be recompiled every time the client-side code changes or when you add a new Vaadin add-on.

For further information about Vaadin client-side development and ways to compile the Widgetset, see the Book of Vaadin or the GWT project website.

Using a custom WidgetSet

Once your widgetset is compiled, tell Magnolia to use it. Edit your webapp's magnolia.properties file and set the key magnolia.ui.vaadin.widgetset. The expected value is a WidgetSet qualified name in the format that Vaadin expects, without the .gwt.xml extension, for example some.vaadin.package.SomeWidgetset.

Change the following entry in {your-webapp}/src/main/webapp/WEB-INF/config/default/magnolia.properties:

magnolia.properties
# Set the location of your custom Vaadin WidgetSet and theme.
# Your widgetset should always inherit Magnolia's default WidgetSet (info.magnolia.widgetset.MagnoliaWidgetSet)
# Your theme should always include Magnolia's default theme (admincentral)
magnolia.ui.vaadin.widgetset=info.magnolia.widgetset.MagnoliaWidgetSet
magnolia.ui.vaadin.theme=admincentral

(warning) As of 5.3, Magnolia's default widgetset was relocated to info.magnolia.widgetset.MagnoliaWidgetSet. If you haven't updated your magnolia.properties, we will automatically fall back to the new widgetset but will issue warnings during upgrade, and whenever a user logs in to Magnolia. To get rid of these warnings, simply adapt your webapp's magnolia.properties as shown above.

For the sake of completeness, please mind that the widgetset name in use for Magnolia 5.2.x is still info.magnolia.ui.vaadin.gwt.MagnoliaWidgetSet.

Recommended setup

Since Magnolia 5.3, we extracted our default Vaadin WidgetSet out of the Magnolia UI project, and we now bring it in as a dependency of the bundle. There were two key reasons to do this:

  • Any of our Magnolia modules may bring its own client-side code or additional Vaadin add-ons.
  • We isolate the resource-intensive GWT compilation to a dedicated maven module, hence no longer affecting build time and stability of the Java code base.
    • The resulting module only consists of two files: the widgetset.gwt.xml file and the maven pom — with appropriate settings for the vaadin-maven-plugin.

What this means for your project, is that you can leverage the exact same approach to integrate Magnolia's default WidgetSet with your custom client-side widgets or Vaadin add-ons. This helps keeping your dependencies and client-side code in the modules where they belong, while giving you more flexibility to integrate third-party modules along the way.

Below is an example of such setup for a custom WidgetSet: