com.netscape.pm.model
Interface IPresentationElement

All Superinterfaces:

IPMElement

All Known Implementing Classes:

BasicCustomField

public interface IPresentationElement

extends IPMElement

Defines an object that will implement the presentation logic for a data field. The presentation component is responsible for:

• representing the field in an HTML format understandable to a browser,
• handling the data coming from an HTTP GET/POST request

The field's display methods are defined as a part of the IPresentationElement interface. These methods will be called when the field is called upon by the engine to render itself into the HTML page to be sent back to the client. When you see the textfield box on an entry point screen, the HTML textbox is generated via a call to the field's display method. Note that the field is not limited to outputting HTML tags to the page and may output arbitrary text depending upon the UI tool used to display the field.

When the user submits a request by clicking one of the action button on a form, a HTTP POST request is sent to the Process Manager engine. The remaining method defined in this interface - the update method - is responsible for translating the data coming from the browser into the data structure that the custom field normally deals with. Think of this as the layer you would write to translate string values coming from a CGI request into numerical values or whatever data format you want.

The key idea behind this component is front-end; any logic needed to communicate with the client front-end is contained here.

See Also:

IHTMLPage, IDataElement, IProcessInstance, IPMRequest

Field Summary

static int	MODE_EDIT Display mode value for editable presentation.
static int	MODE_HIDDEN Display mode value for hidden presentation.
static int	MODE_VIEW Display mode value for view-only presentation.

Method Summary

void	display(IHTMLPage html, int displayMode, java.lang.String displayFormat) Ask the presentation element to display its portion of the business document.
void	display(IProcessInstance pi, IHTMLPage html, int displayMode, java.lang.String displayFormat) Ask the presentation element to display its portion of the business document.
IDataElement	getDataElement() Get access to the data storage side of the field.
void	update(IProcessInstance pi, IPMRequest rq) Translates the HTTP POST/GET string parameters for this field into the usual data object associated with the field.

Methods inherited from interface com.netscape.pm.model.IPMElement

dumpState, getDescription, getName, getParent, getPrettyName, getProperty, isLocked, lockObject, postCreation, setParent, setProperties, toString

Field Detail

MODE_EDIT

public static final int MODE_EDIT

Display mode value for editable presentation. When passed this value for displayMode in either display method, the field should attempt to display itself in an editable format in HTML. For instance, if the field represents itself as an HTML textbox, editable mode would be a regular textbox that is able to accept user input.

See Also:

display( IHTMLPage, int, String ), display( IProcessInstance, IHTMLPage, int, String )

Since:

PAE 4.0

MODE_VIEW

public static final int MODE_VIEW

Display mode value for view-only presentation. When passed this value for displayMode in either display method, the field should attempt to display itself in a view-only format in HTML. For instance, if the field represents itself as an HTML textbox, viewable mode could be just outputting the text contained in the field, instead of the regular textbox that would be displayed in editable mode.

See Also:

display( IHTMLPage, int, String ), display( IProcessInstance, IHTMLPage, int, String )

Since:

PAE 4.0

MODE_HIDDEN

public static final int MODE_HIDDEN

Display mode value for hidden presentation. When passed this value for displayMode in either display method, the field should not attempt to display itself and should only write out hidden information, such as a hidden form tag, for client-side JavaScript functions to access.

See Also:

display( IHTMLPage, int, String ), display( IProcessInstance, IHTMLPage, int, String )

Since:

PAE 4.0

Method Detail

display

public void display(IHTMLPage html,
                    int displayMode,
                    java.lang.String displayFormat)
             throws java.lang.Exception

Ask the presentation element to display its portion of the business document. This version of the method display is only called when a client is viewing the field from an entry point form, as no process instance will have been instantiated at that point.

The display mode and display format parameters are defined at design-time by the process designer. The display mode behaves the same as it did in NPM 1.x, where the possible values where EDIT, VIEW and HIDDEN. It is up to you to alter the display of the field depending upon the display mode passed to the method. The display format was introduced in PAE 4.0; its value is completely designer-specific. One potential use could be to distinguish between a secure viewing mode and a non-secure viewing mode (for example, credit card information). In that example, the display format could contain either the value "secure" or "not secure".

In the event that your display call fails, you can throw a java.lang.Exception at any time to signal an error. An error message will be displayed to the user.

Parameters:

html - the HTML page to be returned to the user

displayMode - the mode the field should be displaying itself in; possible values are MODE_EDIT, MODE_VIEW and MODE_HIDDEN

displayFormat - additional formatting information available to the field. This value is specified from the inspector window of the field when it is placed in the form

Throws:

java.lang.Exception - if there is a problem displaying the contents of the field.

Since:

PAE 4.0

See Also:

MODE_EDIT, MODE_VIEW, MODE_HIDDEN, IHTMLPage

display

public void display(IProcessInstance pi,
                    IHTMLPage html,
                    int displayMode,
                    java.lang.String displayFormat)
             throws java.lang.Exception

Ask the presentation element to display its portion of the business document. This version of display will be called after the process instance has already been created, that is everywhere but the entry point node. The process instance will contain the data that is associated with your custom field; your implementation of this method will need to fetch the data object via the getData method of the process instance class before displaying it.

In the event that your display call fails, you can throw a java.lang.Exception at any time to signal an error. An error message will be displayed to the user.

Parameters:

pi - the current process instance

html - the HTML page to be returned to the user

displayMode - the mode the field should be displaying itself in; possible values are MODE_EDIT, MODE_VIEW and MODE_HIDDEN

displayFormat - additional formatting information available to the field. This value is specified from the inspector window of the field when it is placed in the form

Throws:

java.lang.Exception - if there is a problem displaying the contents of the field.

Since:

PAE 4.0

See Also:

MODE_EDIT, MODE_VIEW, MODE_HIDDEN, display( IHTMLPage, int, String ), IHTMLPage, IProcessInstance

update

public void update(IProcessInstance pi,
                   IPMRequest rq)
            throws java.lang.Exception

Translates the HTTP POST/GET string parameters for this field into the usual data object associated with the field.

This method is called after the user has submitted a request to the Process Manager server. Since all requests in our system take the form of an HTTP GET/POST, the purpose of the update method is to translate the form parameters included as part of the request into the usual data object associated with your custom field. To take our shopping cart field as an example, suppose the form includes values for an item ID and an item quantity. The update method will need to convert the item quantity to a numerical value and create a Item object out of the item ID. The created item data object can then be bound to the process instance via setData.

Parameters:

pi - the current process instance

rq - the current HTTP request

Throws:

java.lang.Exception - if there is a problem translating the HTTP parameters to the field's internal format.

Since:

PAE 4.0

See Also:

IProcessInstance, IPMRequest

getDataElement

public IDataElement getDataElement()

Get access to the data storage side of the field. Field designers may choose to implement their custom field in two separate components: one for the presentation logic and another for the data management logic. This method should be used to return access to the data access portion of the field. It is not necessary to implement your custom field in this manner however, one class may contain both the data management and presentation logic.

Returns:

the handle to the data element manager of the field.

Since:

PAE 4.0

See Also:

IDataElement