com.actional.ui.plugin

Interface IPluginUI

public interface IPluginUI

This interface can be implemented by plug-ins that want to provide their own custom GUI when interacting with the underlying hosting platform. It supports 3 distinct operations corresponding to the different ways a plug-in can interact with the hosting platform. Each of these operations is supported by a different method in the interface:

1. Render an HTML-based UI to prompt for the plug-in's settings on a dedicated page (supported by generatePage(com.actional.ui.plugin.IPluginUI.IGeneratePageContext))
2. Validate the form data provided by the user and persist it if the verification succeeded (supported by processPage(com.actional.ui.plugin.IPluginUI.IProcessPageContext))
3. Summarize the plug-in's current configuration settings (supported by describe(com.actional.ui.plugin.IPluginUI.IDescribeContext))

Depending on the plug-in's preferences (as specified using {provideMetadata(com.actional.ui.plugin.IPluginUI.IProvideMetadataContext)), the custom UI can be applied to either the plug-ins registration using the product's "plug-ins" page (affecting the plug-in's global settings) or the plug-ins instance UI (whose location different for each plug-in and which operates on the plug-in's instance settings).
Both the plug-in's registration and the configuration of an instance are part of a wizard invocation in the UI during the course of which multiple pages are displayed in succession. Part of this wizard involves the configuration of the plug-in's settings and this is when the HTML GUI supplied by the plug-in would be displayed instead of the generic text box that is normally shown in this case to prompt for the plug-in's settings. This custom UI may include all valid HTML form elements that are appropriate to query for the plug-in's required settings, including text fields, file input dialogs, checkboxes, radio buttons or buttons.

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	IPluginUI.IDescribeContext
static interface	IPluginUI.IGeneratePageContext
static interface	IPluginUI.IPart
static interface	IPluginUI.IProcessPageContext
static interface	IPluginUI.IProvideMetadataContext

Method Summary

Modifier and Type	Method and Description
void	describe(IPluginUI.IDescribeContext ctx) Provides a summary of the plug-in's current configuration settings.
void	generatePage(IPluginUI.IGeneratePageContext ctx) Generates the plug-in's custom HTML GUI.
void	processPage(IPluginUI.IProcessPageContext ctx) Validates and persists the form data as it is being posted back to the server.
void	provideMetadata(IPluginUI.IProvideMetadataContext ctx) Provides metadata about the plug-in prior to calling describe() or generate() that may be used by the rendering engine to enhance or customize the rendering of the plug-in's HTML GUI.

Method Detail

generatePage

void generatePage(IPluginUI.IGeneratePageContext ctx)
           throws java.lang.Exception

Generates the plug-in's custom HTML GUI. This method is called at the time when the user needs to enter the plug-in's configuration settings. If multiple pages were defined using {provideMetadata(com.actional.ui.plugin.IPluginUI.IProvideMetadataContext) then this method would be called once for each visible page.
Use IPluginUI.IGeneratePageContext.generateUrl(String, String[], Object[]) if the plug-in's UI should include hyperlinks that point to one of the configuration pages of the plug-in or a button that should trigger a custom action that will be handled by the plug-in itself.
Use IPluginUI.IGeneratePageContext.setState(Serializable) and IPluginUI.IGeneratePageContext.getState() to set and retrieve a state across multiple invocations of {generatePage(com.actional.ui.plugin.IPluginUI.IGeneratePageContext) and {processPage(com.actional.ui.plugin.IPluginUI.IProcessPageContext)} in order to share] volatile (session) data that should not be stored as part of the plug-in's setting and that may be safely discarded once the plug-in configuration has been either completed or canceled.

Parameters:

ctx - The IPluginUI.IGeneratePageContext for this method

Throws:

java.lang.Exception

processPage

void processPage(IPluginUI.IProcessPageContext ctx)
          throws java.lang.Exception

Validates and persists the form data as it is being posted back to the server. The plug-in must then extract the value of its settings (using IPluginUI.IProcessPageContext.getStringParameter(String) or IPluginUI.IProcessPageContext.getPart(String)) and store them in the host application configuration database using (IPluginUI.IProcessPageContext.getSettings() and IRWSettings.setSetting(String, java.io.Serializable)).
IPluginUI.IProcessPageContext.addMessage(Message) should be used to propagate any validation errors to the user which will cause the hosting platform to propagate the error message to the user in a standard fashion and stay on the same page such that the user can re-enter the data if the user did click the Next or Finnish button. Messages are ignored when the user clicks the Previous button. Alternatively, messages with non-error severities can be used to display status messages in the hosting platform's UI while permitting it to resume its regular UI flow, e.g. to propagate non-critical warning messages.
For plug-in GUIs involving multiple pages, this method will be called once for each visible page whenever the user navigates to a different page (using the hosting platform's navigation buttons to step through the configuration wizard). In this case, the ID of the current page is available through IPluginUI.IProcessPageContext.getCurrentPageId().
For more complex GUIs involving multiple pages that are to be displayed in a non-sequential order (e.g. to loop through certain pages multiple times until a condition is met or to perform a custom action and to stay on the same page to display the results), IPluginUI.IProcessPageContext.setPageToDisplay(String) may be used to explicitly set the page that the hosting platform should display next. (Otherwise, the hosting platform will fall back to its default behavior which is to navigate through all defined pages in the order they were defined.)
Use IPluginUI.IGeneratePageContext.setState(Serializable) and IPluginUI.IGeneratePageContext.getState() to set and retrieve a state across multiple invocations of {generatePage(com.actional.ui.plugin.IPluginUI.IGeneratePageContext) and {processPage(com.actional.ui.plugin.IPluginUI.IProcessPageContext)} in order to share volatile (session) data that should not be stored as part of the plug-in's setting and that may be safely discarded once the plug-in configuration has been either completed or canceled.

Parameters:

ctx - The IPluginUI.IProcessPageContext for this method

Throws:

java.lang.Exception

describe

void describe(IPluginUI.IDescribeContext ctx)
       throws java.lang.Exception

Provides a summary of the plug-in's current configuration settings. This method will be called either when viewing the details page of a registered IPluginUI-capable plug-in (for plug-in registrations) or the details page of the underlying object that utilizes a plug-in instance at least for part of its configuration.
The settings summary will be displayed as part of a single page along with other configuration items not specified through the plug-in, thus the settings should be presented as one or more sections that can be included on the details page displayed by the hosting platform.
Use IPluginUI.IDescribeContext.generateUrl(String, String[], Object[]) if the plug-in's UI should include hyperlinks that point to one of the configuration pages of the plug-in or a button that should trigger a custom action that will be handled by the plug-in itself.

Parameters:

ctx - The IPluginUI.IDescribeContext for this method

Throws:

java.lang.Exception

provideMetadata

void provideMetadata(IPluginUI.IProvideMetadataContext ctx)
              throws java.lang.Exception

Provides metadata about the plug-in prior to calling describe() or generate() that may be used by the rendering engine to enhance or customize the rendering of the plug-in's HTML GUI.
Use IPluginUI.IProvideMetadataContext.setRequiresSettings(boolean) to indicate whether a UI should be shown at all under the current context (registration phase or instance configuration).
Use IPluginUI.IProvideMetadataContext.addPage(String, String) to define a list of configuration pages that should be shown when configuring this plug-in (under the current context). By default, the hosting platform will render a UI page for each of these pages (using generatePage(com.actional.ui.plugin.IPluginUI.IGeneratePageContext)) in the order the pages are defined although this behavior can be overridden during the processing of the form data (through processPage(com.actional.ui.plugin.IPluginUI.IProcessPageContext)).

Parameters:

ctx - The IPluginUI.IProvideMetadataContext for this method

Throws:

java.lang.Exception