Abstract
The goal is to finalize the API and settle for naming and feature set. The documentation, both javadoc and otherwise also needs to be improved.
Design
We should finalize the API in terms of finding the right level of abstraction. The API should guide the app developer and not expose internals.
App Framework
The framework is a set of interfaces and abstract utility classes that assist by implementing an app.
These interfaces and classes are in magnolia-ui-framework.
The key interfaces are: App AppController AppContext SubAppContext.
The implementation AppController and the location handling are in magnolia-ui-admincentral in the not so appropriate package name info.magnolia.ui.admincentral.app.simple.
Action: Find a better package structure
Action: Clean upp AppContext and SubAppContext from methods used internally only.
Packaging
The current packaging needs to be rethought.
See Concept - package reorganisation concretes
AppController
References
Abstract
The App controller that manages the lifecycle of running apps and raises callbacks to the app.
It provides methods to start, stop and focus already running {@link App}s.
Registers handlers to the following location change events triggered by the {@link LocationController}:
- LocationChangedEvent
- LocationChangeRequestedEvent
Usages
- The AppController takes care of LocationChangedEvents coming from info.magnolia.ui.admincentral.app.simple.AppControllerImpl#onLocationChanged which can for example be fired by the info.magnolia.ui.framework.location.LocationController#goTo when clicking on icon in the AppLauncher. It takes the Location passed and extracts AppName and subAppId and gets the corresponding AppDescriptor from the info.magnolia.ui.framework.app.launcherlayout.AppLauncherLayoutManager.
- It creates a new AppContext for the App
- keeps history of running app and currently focused app
- used by the MagnoliaShell to query the current Status of the appController
- Used by FieldBuilders to get the AppContext and ComponentProviders for opening ChooseDialogs.
Current Issues
The AppController is in general in a good shape. Interface is well defined and usages are legit.
Some technical ideas and questions
general question:
usage of FocusEvent: seems to not be used consistently. Could also be extended to get rid of the setViewPort and associated calls
usage of appId is should be changed to appName
some methods take the appId and the location as parameter, appId is part of the location
info.magnolia.ui.admincentral.app.simple.AppControllerImpl#setViewPort
use focus event instead?
info.magnolia.ui.admincentral.app.simple.AppControllerImpl#getAppWithoutStarting
apparently the idea was to actually start the app for this usage
info.magnolia.ui.admincentral.app.simple.AppControllerImpl#startIfNotAlreadyRunningThenFocus
only used in test cases. see general question about focusEvent
info.magnolia.ui.admincentral.app.simple.AppControllerImpl#startIfNotAlreadyRunning
deprecated, maybe not right, see focusEvent
info.magnolia.ui.admincentral.app.simple.AppControllerImpl#doStartIfNotAlreadyRunning
this also checks if the app is running, if so it delegates to that app.. wrong naming
info.magnolia.ui.admincentral.app.simple.AppControllerImpl#stopApp
only used internally
info.magnolia.ui.admincentral.app.simple.AppControllerImpl#onLocationChanged
too heavy, should delegate to methods rather, see focusEvent
AppContext
References
Abstract
The AppContext serves multiple different purposes:
- An app uses the AppContext to interact with the App Framework. Some examples:
- resolve the configured App Label for setting the correct title in the tab.
- send notification Messages to the MessagesManager
- The AppController uses it to delegate handling of location changes and to the app and subApp
- Takes care of reading subApp configurations and mapping locations to to the correct subApp
- creates both componentProviders for App and subApp
Issues
There is definitely room for improvement in this class.
The general problem: used heavily by the appController and also for the app itself to get contextual information: serving multiple needs. see
The idea of AppContext is to expose functionality to the App. That is, to an instance of an app.
It should not expose methods that are only used by AppControllerImpl. These should be hidden from all other classes.
If necessary AppControllerImpl#runningApps should be changed to <String, AppContextImpl>. Also if the intention of AppContextImpl is unclear it should be renamed to reflect the fact that is not just the default implementation of AppContext, it does much more and in fact fullfils much of the contract defined by AppController.
- rename the AppController to AppLauncher or similar, introduce a new AppController class which takes care of the contract to the AppLauncher and keep the AppContext as thin as possible, only serving contextual information to the actual App
- Move some of the functionality of AppContext into the info.magnolia.ui.framework.app.launcherlayout.AppLauncherGroupEntry
- info.magnolia.ui.admincentral.app.simple.AppContextImpl#getDefaultSubAppDescriptor
- info.magnolia.ui.admincentral.app.simple.AppContextImpl#getSubAppDescriptorById
Tasks
Documentation
UML Diagrams