UI Context API
This page describes the purpose, scope and use cases of the UIComponentContext
in the Magnolia 6 UI framework.
The UiComponentContext
is used to share a state between UI components.
- Example
import info.magnolia.ui.framework.ContextProperty;
import info.magnolia.ui.framework.UiComponentContext;
public interface ExampleContext extends UiComponentContext {
ContextProperty<String> value(); //implementation of ContextProperty is created at runtime
}
|
Scope
UIComponent
can create instances of UiComponentContext
which are shared by child components.
import info.magnolia.ui.UIComponent;
import info.magnolia.ui.ValueContext;
import javax.inject.Inject;
import com.vaadin.ui.Label;
import com.vaadin.ui.VerticalLayout;
public class ParentComponent extends VerticalLayout implements UIComponent {
public ParentComponent() {
final ValueContext<String> valueContext = bindContext(ValueContext.class);
valueContext.set("sharedValue");
//the ValueContext instance created above gets injected into child components:
final ChildComponent componentA = create(ChildComponent.class);
final ChildComponent componentB = create(ChildComponent.class);
addComponents(componentA, componentB);
}
public static class ChildComponent extends Label {
@Inject
public ChildComponent(ValueContext<String> valueContext) {
setCaptionAsHtml(true);
setValue(valueContext.getSingleOrThrow());
}
}
}
Observation
ContextProperty
can react upon value changes:
import info.magnolia.ui.ValueContext;
import info.magnolia.ui.framework.ContextProperty;
import javax.inject.Inject;
import com.vaadin.ui.Notification;
public class Observation {
@Inject
public Observation(ValueContext<?> valueContext) {
final ContextProperty<?> current = valueContext.current();
current.observeNullable(strings -> Notification.show(strings + " are selected!"));
}
}
Use cases
-
ValueContext
, holds the selection or value that the related UI components operate with. -
LocaleContext
, used in various editors which:-
Allow editing localized content.
-
Support switching between supported languages within the same session.
-
-
FilterContext
, a data filter context. Typically, it is mutated by the UI and consumed by Vaadin data providers in order to filter the displayed data sets accordingly. -
info.magnolia.ui.contentapp.ContentBrowserSubApp.LocationContext
orinfo.magnolia.ui.contentapp.detail.ContentDetailSubApp.LocationContext
, holds the location of a browser or detail subapp.
In the Browser subapp
The ValueContext
and LocaleContext
are injected into the Browser subapp.
As these contexts have not yet been bound in the parent component, the injection mechanism creates new instances.
These contexts are synchronized. The ValueContext
changes are reflected into the location and vice versa.
Grid view
The ValueContext
changes (the server side updates such a new item creation, for example) are propagated to a grid selection and a grid selection (when the user selects an item, for example) is propagated to the ValueContext
).
This mechanism ensures that the ValueContext
— injected for example into the actions — points to an up-to-date selection.
The FilterContext
holds column filter updates and propagates those into the grid’s data provider.
Action bar
The ActionbarView
updates visible sections and actions on ValueContext
selection.
Action is a typical consumer of an injected UIContext
.
import info.magnolia.ui.ValueContext;
import info.magnolia.ui.api.action.AbstractAction;
import javax.inject.Inject;
import javax.jcr.Node;
import javax.jcr.RepositoryException;
public class ExampleAction extends AbstractAction<ActionDefinition> {
private final ValueContext<Node> valueContext;
@Inject
public ExampleAction(ActionDefinition actionDefinition, ValueContext<Node> valueContext) {
super(actionDefinition);
this.valueContext = valueContext;
}
@Override
public void execute() {
final Node currentSelection = valueContext.getSingleOrThrow();
try {
final Node newSelection = currentSelection.addNode("aNewChildNode", "mgnl:content");
newSelection.getSession().save();
valueContext.set(newSelection);
} catch (RepositoryException e) {
throw new RuntimeException(e);
}
}
}
In dialogs
Dialogs opened in the grid view are populated from the same instance of the ValueContext
.
Link field choosers are a good example of a component specific UIContext . The contexts in the choosers should not be synchronized with the contexts of the underlying grid from which the dialog is opened.
|
Even though the detail subapps are opened from the same browser, each subapp holds its own ValueContext . Therefore, the form can be written to its own underlying item.
|