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

The Magnolia Shell uses essentially two Viewports, the Apps viewport for M5 apps, and the Shell Apps viewport for our three system-wide apps - Appslauncher, The Pulse, and Favorites. This concept page describes how these two viewports are displayed in the browser, what their states are, and how they perform animated transitions between these states.

One of the key concepts introduced here consists in delegating the transition logic, keeping it well separated from the viewports inner displaying logic. These concepts have been implemented in version 5.0 Alpha1 s008.

Error rendering macro 'jira'

Unable to locate Jira server for this macro. It may be due to Application Link configuration.

The Problem

Maintaining a consistent client state of the application can quickly become complex and challenging. When dealing with animated transitions, one has to guarantee that every "block" always ends up in its expected state (e.g. visibility, position, opacity), while still maintaining a high level of interaction and visual feedback. Furthermore, it has to integrate smoothly with other dynamic features such as server-side location handling or swiping gestures.

There had been already two iterations of work on the transitions for M5 prior to the conference. The first one basically provided the effects based on the static HTML prototype, while the second one focused on reorganizing and simplifying the flow of transitions, defining them at the right levels (cf. M5 Transitions Chart TODO). Basically it's easier to have n elements always performing 1 transition, than 1 element conditionally using n different transitions. Concretely, the Apps and Shell apps viewports are displayed at the same x,y coordinates; the Shell view is then responsible for setting which viewport is "active", i.e. presented to the user (setActive). This is the displaying logic at the viewport level. Each of these two viewports then has its own way to present one visible app (setVisibleApp), this is the application level.

So far so good, the concept of triggering transitions on these two entry points was implemented, but code-wise it was done essentially within the VShellViewport class, where the viewport displaying logic is. Adding all the animated transition logic in there made it hardly readable, hence hard to maintain. Here were the main gripes when considering the refactoring:

  • 4 effect-driven animation delegates (effects for showing viewport, hiding viewport, showing an app, hiding an app)
  • Shell view should not hold transition logic, changing the viewport's animation delegates to adjust "effects" based on situation
  • animation delegate fields and boolean flags galore
  • show/hide methods way too complex due to late integration of the curtain animation
  • totally unself-explanatory JQuery callbacks
  • z-index switching folklore, trying to keep curtain depth sandwiched between viewports
  • instant shell apps transitions had no chance to be integrated smoothly

Also concept-wise, the former AnimationDelegates were according to effect (slide-in, fade-out, shalala), not really providing any delegation relief to the viewport class. Finally, all viewports used to extend VPanelWithCurtain, even those which didn't need a curtain.


  • Cleaner, well separated code
  • Role-driven animation delegates, per viewport type (e.g. "this is the shell apps viewport transition between apps")


Transition Delegates:

  • Same two entry points as before
    • VShellViewport#setActive
    • VShellViewport#setVisibleApp(was setVisibleWidget)
  • But… drop private animation methods in favor of transparent transition delegates
    • TransitionDelegate#setActive
    • TransitionDelegate#setVisibleApp
  • Provide fallback when no transition is needed
    • VShellViewport#doSetActive
    • VShellViewport#doSetVisibleApp
    • BaseTransitionDelegate class, simply falling back to this default viewport behavior
    • M5 still perfectly usable without any transition

The Transition Delegate Flow Chart:


Shell Viewports:

  • Drop z-index swapping of viewports in favor of fixed z-indices (see z-index composition below)
    • Removing complexity of curtain index
    • Reducing dynamic inline styles
  • No longer attach curtain behind shell apps viewport when active, but on top of apps viewport when inactive
    • Fixed z-index  
    • Curtain is needed to cover apps, meaning same position and same size, whereas the shell apps viewport changes position (slide transitions).
    • Apps viewport holds the curtain logic; displaying the curtain depends on whether apps viewport still has at least one running app.
  • drop VPanelWithCurtain class
  • Keep common and special behaviors well separated
    • VShellViewport does viewport activation, changing visible app, vaadin update and widget container logic
    • VShellAppsViewport adds instant transitions with deferred refresh
    • VAppsViewport adds curtain, swipe and app preloader logic


  • Code diet (esp. VShellViewport) and clear separation of roles
  • Clear curtain logic
  • Zoom-out on close: deferred DOM removal logic also got clearer
  • CSS simplified with less dynamic inline rules
  • Smoother integration of the instant transitions mechanism
  • Improved javadoc


  • Updated JQuery and CSS3 transitions plugin to fix a bug
    • CSS transitions could not be stopped, resulting sometimes in empty shell viewport
  • Removed main launcher navigation lock, transitions are bulletproof
  • New transition: background running apps zoom-in on restore
  • Shell apps viewport activation now also happens instantly
  • No labels