The following information is intended as a guide for plugin authors wishing to develop custom screen and control providers to extend the natively implemented screen and control objects with extra functionality, new ways of rendering, extra validation, and so on.
The first thing to note is that the actual plugin objects are the custom screen and control providers, not the custom screens and controls themselves. A Web Determinations session (represented by the SessionContext object) may have at most one of each provider. If multiple implementations of one or both of these providers are found, one will be non-deterministically (from the perspective of a plugin developer) chosen. Every time a control or screen is required, Web Determinations will query the provider registered (if one exists) to retrieve a custom screen or control for the current InterviewScreen or ControlInstance object in the current session context. It is up to the provider implementation to provide concrete instances of CustomScreen and CustomControl objects (or concrete implementations of any subinterfaces, such as CustomInputControl as appropriate) if the provider determines that it can. Otherwise the provider is required to return a null object.
The CustomScreen and CustomControl implementations served by the providers are required to be packaged up and deployed in a plugin archive in the same way that all other plugins are deployed. These dependencies don't necessarily have to be deployed into the very same archive as the providers that reference them, but they must be located inside one of the plugin archives loaded.
Custom screen and control providers are PlatformSessionPlugin implementations, meaning that they belong on a particular platform session (SessionContext).
Custom screen provider
To provide a custom screen provider implementation, it is necessary to implement the CustomScreenProvider interface. The implementation of this interface consists of:
- Implementing the standard getInstance(args : RegisterArgs) : Plugin method.
The specific instance of RegisterArgs passed through is PlatformSessionRegisterArgs, which encapsulates the current SessionContext. In this way, plugin authors can determine whether or not they would like their custom screen provider implementation to be registered on a particular session based on such data as the session's rulebase. It is in this way that multiple custom screen providers may be deployed without contesting with each other for registration against a particular session (for example, have one per rulebase).
- Implementing the getScreen(context : SessionContext, iScreen : InterviewScreen) : CustomScreen method.
This is the method queried each time a Screen object is required. If the provider can provide a custom screen instance for the given session context and Web Determinations Engine screen model object then it must return it. Otherwise, this method must return null.
Custom screens
Custom screens are defined by implementing the CustomScreen interface. The implementation of this interface consists of:
- Implementing the processAndRespond(context : SessionContext, uri : URI) : Response method.
The custom screen implementation is responsible for doing everything for itself that is usually taken care of by the Action framework. There is no restriction on what is actually implemented in this method, as long as a valid Response object is returned. It is this response object that is then passed back to the servlet and displayed to the user.
- Implementing the submit(screenId : String, params : Map, context : SessionContext) : boolean method.
This method is responsible for submitting the screen to the InterviewSession and returning a boolean representing whether or not the submission was successful. The screen ID is the ID of the interview screen submitted and the parameter map is the one submitted with the POST.
More information
For more information on creating a custom screen, go to:
Custom control provider
To provide a custom control provider implementation, it is necessary to implement the CustomControlProvider interface. The implementation of this interface consists of:
- Implementing the standard getInstance(args : RegisterArgs) : Plugin method.
The specific instance of RegisterArgs passed through is PlatformSessionRegisterArgs, which encapsulates the current SessionContext. In this way, plugin authors can determine whether or not they would like their custom control provider implementation to be registered on a particular session based on such data as the session's rulebase. It is in this way that multiple custom control providers may be deployed without contesting with each other for registration against a particular session (for example, have one per rulebase).
- Implementing the getControl(iCtrl : ControlInstance, parent : ControlContainer, screen : NativeScreen) : CustomControl method.
This is the method queried each time a Control object is required by the screen controller when populating the controls on a screen. If the provider can provide a custom control instance for the given Web Determinations engine control instance that supports being placed inside the given control container on the given Web Determinations platform native (non-custom) screen then this instance is to be returned. Otherwise return null. It is important to remember that this method is only called automatically if the screen on which the control is needed is a native screen, not a custom screen. If you would like to place a custom control on a custom screen, it is your responsibility to instantiate that control yourself from the custom screen's processAndRespond method, or wherever it is that you are constructing your custom screen model (if at all).
Custom controls
Custom controls are defined by implementing the CustomControl interface. This is an empty marker interface that extends from the base control interface, which defines a variety of methods that controls have to implement. There is also a CustomInputControl interface to be implemented if your custom control is intended to collect user input data that maps to at least one rulebase attribute. Ensure that your implementation matches the following requirements:
- The class name you have chosen for your custom control implementation does not conflict with any of the native controls.
- You have provided a template to render your custom control named [custom control class name].vm.
- You have implemented the getControlType() : String method to return the class name of your control.
More Information
For information on creating a custom control and for a walkthrough example, go to:
Create a Custom Control
Custom Control - BenefitCode walkthrough example