To allow for widgets to cooperate without tight coupling, it is very useful to share a basic event vocabulary. The LaxarJS Runtime already defines the semantics of core event patterns. For application-level events, LaxarJS Patterns provides an additional vocabulary, which may be grouped into a handful of pattern families. Before starting with the patterns, make sure that you are familiar with the LaxarJS Core Concepts and the LaxarJS events manual.
For efficient usage of the available pattern libraries in your widgets, you should consult the API docs as well.
Most application-level events have to do with resources, actions and flags. There is a common theme to how these patterns are used: Widgets define what events generally concern them, but the page configuration is used to constrain where or when they are interested in these events:
- an email viewer is interested in resource-events, but only for the currently selected email resource, not for the mailbox resource
- a navigation activity may be interested in action-events, but only in those generated by the next and previous buttons, not in those generated by the save button
- a widget presenting real-time stock market information is interested in flag-events, but only those that tell wether its container popover widget is currently open, so that it may pause updates otherwise
Possibly the most important family of patterns, resource events deals with sharing, validating and persisting application resources. Here, resource usually refers to a JSON representation of a REST resource, for example in HAL format. However, LaxarJS and the patterns described here do not actually make assumptions about the origin or the internal structure of resources, except that they are directly representable as JSON objects. This means that it is perfectly acceptable to obtain resources through a different mechanism than HTTP (such as WebSockets or localStorage).
The resource patterns cover events starting with the following topics:
didReplaceanddidUpdatevalidateRequest,willValidateanddidValidatesaveRequest,willSaveanddidSave
Widgets may publish requests for action to indicate that the user has triggered some functionality outside of their own scope. Depending on the page configuration, other widgets will respond to these actions in whatever way is appropriate or configured for them. Widgets may respond using the will/did-mechanism, for long running actions.
The actions pattern covers events starting with the following topics:
takeActionRequest,willTakeActionanddidTakeAction
Flags allow widgets to communicate boolean state. For example, one activity could track validation events from all widgets on a page and publish a flag describing the overall validation state. A navigation widget could then enable or disable its "save" button according to that state.
The flag pattern covers events starting with the following topics:
didChangeFlag
Sometimes widgets and especially activities have to indicate an error situation that is not recoverable (such as a network problem). The error events can be used to broadcast these problems, and have another component handle them, through means such as logging, displaying a problem message to the user or navigating to an error page.
The error pattern covers events starting with the following topics:
didEncounterError