Magnolia Shell

The Magnolia Shell is the visual layer of Magnolia, the look and feel that makes M5 instantly recognizable. The Shell creates the user interface that you see when you log into the system: the green background, the Magnolia logo and the three Shell app icons: Apps, The Pulse and Favorites.

Magnolia Shell as an app container

In Magnolia 5, an app is a tool with a very narrowly focused interface that enables you to work on one set of closely related tasks or one specific set of data. An app does not necessarily work on a single, physical data set such as the pages of a site. It may cover multiple physical data sets required to solve the task or tasks that the app covers. Apps contain sub-apps. Once an App has been launched, its app tile on the Apps screen changes color to indicate it is running. You can switch back to the Apps screen at any time, provided no modal dialogs (action in progress) are open. On the App screen you can switch to or launch another App. At the user interface level, Magnolia Shell is the area below the header where the apps live. It is the lighter green part of the browser viewport that displays the currently running app.

But the Shell is not only visual chrome for the system itself. It also makes your own app look like it belongs to Magnolia. The Shell imposes a shared visual identity on all apps, making them fit in with the rest of the UI. For a helpful analogy, think of the Magnolia Shell as the operating system on a computer. On Mac OS X the dock and the menu are immutable. They are always present, providing a place for starting applications and for those applications to add their menus. The Windows 8 style UI on provides a common look and feel for Windows apps. It creates a familiar interface on all devices running the Microsoft operating system. That’s exactly what the Magnolia Shell does.

From a functional viewpoint the Shell is a container that provides basic services for apps. It allows you to launch apps and display dialogs. It is also responsible for visual effects when you switch between apps. For example, when you go back to the Apps screen to launch another app, the app that was just running fades into the background. This see-through effect is called the app stack. It tells you that the app is already running, and if you go back to that app, you will find your work is in the same state as you left it.

AdminCentral

If you are familiar with Magnolia 4 you can probably tell by now that the Magnolia Shell is roughly synonymous with the old AdminCentral. The term AdminCentral is still valid and applicable in Magnolia 5. Administering the system is done in AdminCentral, which uses the Magnolia Shell for its UI.

The old AdminCentral was responsible for creating a fixed UI layout. When you clicked a command in the menu on the left, the content was displayed on the right. That behavior was predictable and easy to learn because it was fixed. Similarly, the Magnolia Shell provides a UI that stays the same from one Magnolia instance to another.

The Magnolia Shell user interface is protected, which means you cannot change it. The UI is part of Magnolia’s visual identity. It makes the system instantly recognizable and allows users to get oriented quickly. This is why we don’t allow you to edit the Shell or its elements. However, you can add your own app on the Apps screen and even create your own app groups.

What end users need to know about the Shell

End users such as editors and admins perceive the Magnolia Shell as the administration interface. The Shell allows users to launch and switch between apps, check notifications, and bookmark their favorite places and tasks. The Shell helps the user start an app and then hands over control of the app to the user. This is the case for all apps, even the three native apps. The Shell is not responsible for what happens inside the app. For this reason, end users likely never need to know anything about the Shell. It is just something that keeps things running in the background.

What developers need to know about the Shell

As an app developer it is good to know what the Magnolia Shell does. However, once you know what it does you can safely forget about the Shell and consider it an operating system detail.

Think of the Shell as a toolbox. It defines the things you can and cannot do in the system. Those things are basic services at a rather low level. This means that you typically don’t need to interact with the Shell directly. There are more intuitive shortcuts for common app development tasks.

For example, the Shell is responsible for sending messages to the Pulse. However, you don’t need to know which exact Shell method to invoke in order to send such a message. In your app code, create a reference to an AppContext object instead. This object provides shortcuts for sending messages, displaying confirmation dialogs and many other everyday things. It is more straightforward to interact with the AppContext object than with the Shell itself.

Tasks of the Magnolia Shell

In summary, the Shell does the following:

• Provides an environment to run apps in.
• Creates the system user interface.
• Accommodates the App Launcher, the Pulse dashboard and provides ways to open both.
• Provides a place to show system and application notifications using icons and message panels.
• Provides access to a user's profile, personal settings and messages.
• Switches between running apps. Makes app transitions visible to the user.
• Provides window management.
• Displays dialogs. Handles dialog modality.
• Accepts long-running tasks initiated by apps and sees them being run through to the end.
• Offers tools to move and copy content between apps and subapps.
• Groups apps
• May act as a filter to only show apps and dashboard data pertaining to a specific site or project.

In order to use the services of the Shell, inject a reference to the AppContext object in your app code.

public class HelloWorldApp extends BaseApp {
    private AppContext appContext;

    @Inject
    public HelloWorldApp(AppContext appContext, AppView view) {
        super(appContext, view);
    }
    ...
}

Magnolia Shell as a UI element

In the user interface, the Shell is equivalent to the browser viewport. It is the parent container. Inside the Shell is the App Framework. The framework is like a process manager for apps; it manages the app lifecycle (start, stop, focus). In your app code you can request the App Framework to do tasks for you. The framework in turn talks to the Magnolia Shell, hiding the low level details. 

The next level down are the tabs. Each application must have at least one tab but it can have many. For example, the Pages app has one tab called Pages. For each Web page that you edit the app opens a new tab.

A tab contains a Workbench. It is the area of the UI where the app data is displayed. For example, in the Pages app the data is a list of pages. You can display data in three different views: tree, list or grid.