Module Support

Parent and Child Swiz Instances

Swiz supports the concept of parent and child instances. Typically, this capability is used in conjunction with Modules. When you load a module that contains a Swiz instance as a child of another Swiz-based application, the framework will create a parent-child relationship between these two instances of Swiz. This happens automatically, meaning that the developer should not have to do any manual setup or configuration to use this feature. There is a sample application that demonstrates how Swiz can work with Modules at the Github repository.

Here is a graphical representation of how the module support works and what capabilities it offers:

The one main issue that developers encounter related to module support has to do with Swiz metadata-based event handling. The [EventHandler] metadata tag only contains a string value representing the event class and constant name. As a result, when Swiz attempts to validate the event, you will receive an error if that event class was not compiled into the Module. This is because Swiz cannot locate the event class in the ApplicationDomain. The developer must ensure that event classes defined outside of the module are included in the compiled module. In practice, this simply means adding a variable declaration somewhere that is typed to that event. As long as an actual reference to the event type exists somewhere within the module, that class will be compiled into the module. This allows Swiz to locate the class reference and validate the event constants.

Note that this is not actually a Swiz-specific issue. The compiler only includes classes that are actually referenced in an application; all others are discarded for optimization purposes.

The Local and Global Scopes

Swiz offers some additional control over how events are dispatched and handled between parent and child Swiz instances. Most developers will probably never need to concern themselves with this fine-grained control, but it is described here for the cases where it is desired.

The [Dispatcher] and [EventHandler] metadata tags allow for an optional attribute called scope, which can be set to "local" or "global". The default value for both of these attributes is "global".

If a [Dispatcher] metadata tag specifies scope="local", the dispatcher for that Swiz instance is injected. When scope="global" is specified, the dispatcher for the top-level Swiz instance is injected.

Similarly, if an [EventHandler] metadata tag specifies scope="local", only events dispatched through the local dispatcher are handled by the decorated method. When scope="global" is specified, events dispatched through the global dispatcher are handled.

Since this may make more sense when visualized, here is a graphic depicting the local and global scopes: