org.universAAL.middleware.ui.rdf
Class Form

java.lang.Object
  org.universAAL.middleware.rdf.Resource
      org.universAAL.middleware.rdf.FinalizedResource
          org.universAAL.middleware.ui.rdf.FormElement
              org.universAAL.middleware.ui.rdf.Form

public class Form
extends FormElement

Forms can be used to describe dialogs in a modality- & layout-neutral way. A Form is a container of a set of FormControls that specify the structure of the dialog as it should be presented to human users. This implementation organizes the FormControls in three standard Groups:

The submits group

"buttons" that finish the whole dialog should be added to this group.

The ioControls group

all other form controls, no matter if input or output controls, or subgroups or even submits that trigger a sub-dialog should be added to this group.

The stdButton group

this group is reserved for a dialog management solution that has access to all dialogs and may be willing to add standard buttons beyond the application logic to reflect a system-wide behavior.

Forms support four dialog types:

Message

The simplest dialog type that can be used to specify a text message to be presented as a notification. No standard buttons in the above sense are allowed. The text message will be used to construct a SimpleOutput object that is added as the single child to the ioControls group. The submits group will be constructed automatically with two buttons based on the constants ACK_MESSAGE_DELET resp. ACK_MESSAGE_KEEP and LABEL_MESSAGE_DELET resp. LABEL_MESSAGE_KEEP. These two buttons can be used by a user to state either "ok, I got it, you can delete the message" or "please preserve the message for later check", respectively. Normally, applications do not need to subscribe for user decision in this regard, but if they want, then they must use the value returned by the method getDialogID() of the created form object, for subscribing to the UI bus.

System Menu

Reserved for a dialog management solution to present the system main menu. No submits group is allowed in this type of dialog.

Subdialog

A dialog related to a running dialog that must be "popped up" when the user presses a button in the originally running dialog without ending that running dialog. No standard buttons in the above sense are allowed. Applications must use instances of SubdialogTrigger for placing buttons that pop up a subdialog, instead of instances of Submit that should be used only for finishing the whole dialog. Submit instances must be added to the group returned by Form.getSubmits(), whereas SubdialogTrigger instances should be added to appropriate subgroups of the group returned by Form.getIOControls(). Subdialogs may affect the data to be used within the main dialog and hence the main dialog must be frozen until the application requests to continue with it. For this purpose, applications must call the method UICaller.resumeDialog(String,org.universAAL.middleware.rdf.Resource) of their output publisher after the subdialog finishes and they have processed its data and updated the form data of the main dialog. UI handlers may decide to render instances of SubdialogTrigger and Submit differently. Additionally, they may differentiate between events from these two types of buttons (and e.g. keep the parent dialog open until the subdialog loop is closed) or not. In any case, the middleware will re-dispatch the main dialog by calling UIHandler.handleUICall(org.universAAL.middleware.ui.UIRequest) of the output subscriber of the selected UI handler, as soon as the application requests to resume the dialog. In this way, the freezing and re-activating the main dialog is forced by the middleware even if the UI handler does not differentiate between events from instances of SubdialogTrigger and Submit.

Standard Dialog

All other forms must be constructed with this dialog type. All the three standard groups will be created automatically. Applications can get the standard groups "ioControls" and "submits" by calling the getIOControls() and getSubmits() methods respectively and construct their dialogs using these two groups as parent for their real form controls.

Author:

mtazari, Carsten Stockloew

See Also:

ftp://ftp.igd.fraunhofer.de/outgoing/mtazari/persona/dialogPackage.jpg

Field Summary

static String	ACK_MESSAGE_DELET The submission ID if a user acknowledges that a dialog of type Message can be deleted.
static String	ACK_MESSAGE_KEEP The submission ID if a user acknowledges that a dialog of type Message must be preserved for later check.
static Label	LABEL_MESSAGE_DELET The label of a button associated with ACK_MESSAGE_DELET as submission ID that is automatically added to dialogs of type Message.
static Label	LABEL_MESSAGE_KEEP The label of a button associated with ACK_MESSAGE_KEEP as submission ID that is automatically added to dialogs of type Message.
static String	MY_URI
static String	PROP_DIALOG_CREATED_BY An optional property of form objects that can be associated with a string representing the name of the component that created the form.
static String	PROP_DIALOG_CREATION_TIME The point of time in which a form object is instantiated.
static String	PROP_DIALOG_CURRENT_FOCUSED_CONTROL An optional property of form objects to indicate which form control should receive the focus when UI handlers start to present the dialog.
static String	PROP_DIALOG_DATA_ROOT The Resource containing the form data.
static String	PROP_DIALOG_TYPE The type of the dialog represented by a form object as an instance of DialogType.
static String	PROP_PARENT_DIALOG_URI Applications must set this property for those form objects representing a dialog of type Subdialog using the value returned by getDialogID() on the parent form from which the subdialog was triggered.
protected static String	PROP_ROOT_GROUP
static String	uAAL_DIALOG_NAMESPACE

Fields inherited from class org.universAAL.middleware.ui.rdf.FormElement

PROP_APPEARANCE

Fields inherited from class org.universAAL.middleware.rdf.Resource

ANON_URI_PREFIX, blockAddingTypes, isXMLLiteral, ns_delim_index, PROP_RDF_FIRST, PROP_RDF_REST, PROP_RDF_TYPE, PROP_RDFS_COMMENT, PROP_RDFS_LABEL, PROP_SERIALIZATION_FULL, PROP_SERIALIZATION_OPTIONAL, PROP_SERIALIZATION_REDUCED, PROP_SERIALIZATION_UNDEFINED, PROP_uAAL_INVOLVED_HUMAN_USER, props, RDF_EMPTY_LIST, RDF_NAMESPACE, RDFS_NAMESPACE, TYPE_RDF_LIST, TYPE_RDFS_CLASS, uAAL_NAMESPACE_PREFIX, uAAL_SERVICE_NAMESPACE, uAAL_VOCABULARY_NAMESPACE, uri

Constructor Summary

	Form(String uri) For usage by de-serializers only.
protected	Form(String uriPrefix, int numProps)

Method Summary

XMLGregorianCalendar	getCreationTime() Returns the time at which the first time the form was created by an application.
FormControl	getCurrentFocusedControl()
Resource	getData()
String	getDialogCreator()
String	getDialogID() Returns the URI of this form object as its global unique ID.
DialogType	getDialogType()
Group	getIOControls() Returns the standard group for UI controls in this form.
String	getMessageContent() Returns the text message originally set if this form was created by newMessage(String, String).
Resource	getParentDialogResource() Returns the parent dialog as an empty resource with PROP_PARENT_DIALOG_URI as its URI.
String	getParentDialogURI()
Output[]	getSharedOutputs() Returns all the Output controls contained in the ioControls group (see the above documentation of this class concerning the standard groups within forms) that are likely to be relevant for human users in order to decide what to do with this dialog.
Group	getStandardButtons() Returns the pre-defined group of standard buttons in this form.
String	getStandardButtonsDialogID() Reserved for use by a dialog management solution that has access to all dialogs and adds standard buttons beyond the application logic to reflect a system-wide behavior.
Group	getSubmits() Returns the standard group for submit buttons in this form.
String	getTitle() Returns the form title reflecting the intent of this dialog and originally set when constructing this form object.
boolean	isMessage() Answers if this form object is created by newMessage(String, String).
boolean	isStandardDialog() Answers if this form object is created by newDialog(String, Resource).
boolean	isSubdialog() Answers if this form object is created by newSubdialog(String, String).
boolean	isSystemMenu() Answers if this form object is created by newSystemMenu(String).
static Form	newDialog(String formTitle, Resource dataRoot) Constructs and returns a new form object representing an empty dialog of type Standard Dialog with proper initial configuration.
static Form	newDialog(String formTitle, String dataRootType) An alternative for newDialog(String, Resource) to be used if no specific data root is going to be specified but only the URI of its type.
static Form	newMessage(String formTitle, String message) Constructs and returns a new form object representing a Message dialog that is ready to publish within an UIRequest.
static Form	newSubdialog(String formTitle, String parentDialogURI) Constructs and returns a new form object representing an empty dialog of type Subdialog with proper initial configuration.
static Form	newSystemMenu(String formTitle)
FormControl	searchFormControl(String formControlURI) look for a FormControl within the form with the given URI.
void	setCurrentFocusedControl(FormControl fc)
void	setDialogCreator(String creator)
void	substituteData(Resource pr) Reserved for usage by the middleware.

Methods inherited from class org.universAAL.middleware.ui.rdf.FormElement

addAppearanceRecommendation, getAppearanceRecommendations

Methods inherited from class org.universAAL.middleware.rdf.FinalizedResource

addType, getLocalName, getNamespace, getProperty, getPropertyURIs, getType, getTypes, getURI, hasQualifiedName, isAnon, numberOfProperties

Methods inherited from class org.universAAL.middleware.rdf.Resource

addMultiLangProp, asList, asList, asRDFList, changeProperty, copy, deepCopy, equals, generateAnonURI, getDefaultLang, getFilename, getMultiLangProp, getOrConstructLabel, getPropSerializationType, getResource, getResourceComment, getResourceLabel, getStaticFieldValue, hashCode, hasProperty, isAnon, isBlockingAddingTypes, isClosedCollection, isQualifiedName, isWellFormed, literal, representsQualifiedURI, serializesAsXMLLiteral, setProperty, setPropertyPath, setPropertyPath, setPropertyPathFromOffset, setResourceComment, setResourceLabel, toString, toStringRecursive, toStringRecursive, unliteral

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

uAAL_DIALOG_NAMESPACE

public static final String uAAL_DIALOG_NAMESPACE

See Also:

Constant Field Values

MY_URI

public static final String MY_URI

See Also:

Constant Field Values

ACK_MESSAGE_DELET

public static final String ACK_MESSAGE_DELET

The submission ID if a user acknowledges that a dialog of type Message can be deleted.

See Also:

Constant Field Values

ACK_MESSAGE_KEEP

public static final String ACK_MESSAGE_KEEP

The submission ID if a user acknowledges that a dialog of type Message must be preserved for later check.

See Also:

Constant Field Values

LABEL_MESSAGE_DELET

public static final Label LABEL_MESSAGE_DELET

The label of a button associated with ACK_MESSAGE_DELET as submission ID that is automatically added to dialogs of type Message.

LABEL_MESSAGE_KEEP

public static final Label LABEL_MESSAGE_KEEP

The label of a button associated with ACK_MESSAGE_KEEP as submission ID that is automatically added to dialogs of type Message.

PROP_DIALOG_CREATED_BY

public static final String PROP_DIALOG_CREATED_BY

An optional property of form objects that can be associated with a string representing the name of the component that created the form.

See Also:

Constant Field Values

PROP_DIALOG_CREATION_TIME

public static final String PROP_DIALOG_CREATION_TIME

The point of time in which a form object is instantiated. This property is set automatically with the value returned by TypeMapper.getCurrentDateTime().

See Also:

Constant Field Values

PROP_DIALOG_CURRENT_FOCUSED_CONTROL

public static final String PROP_DIALOG_CURRENT_FOCUSED_CONTROL

An optional property of form objects to indicate which form control should receive the focus when UI handlers start to present the dialog. It will be set automatically by the middleware whenever a running dialog is cut so that a seamless resumption of the dialog at a later point in time is guaranteed. UI handlers should check if this property is set. If yes, then they must simulate their logic of presenting the form until they reach the form control given as value of this property. At this point they can prompt the user for the next data entry.

See Also:

Constant Field Values

PROP_DIALOG_DATA_ROOT

public static final String PROP_DIALOG_DATA_ROOT

The Resource containing the form data. Form data can be accessed using property paths; UI handlers, however, do not need to explicitly access this data normally, because they normally deal only with data associated with form controls that can be retrieved by calling FormControl.getValue() or set by calling Input.storeUserInput(Object). Applications may create an instance of Resource and set both their hidden data and initial data associated with the form controls using Resource.setPropertyPath(String[], Object) . They can retrieve the form data from ui responses by calling UIResponse.getUserInput(String[]) . Note: initial data to be associated with form controls can be set through their constructors, as well.

See Also:

Constant Field Values

PROP_DIALOG_TYPE

public static final String PROP_DIALOG_TYPE

The type of the dialog represented by a form object as an instance of DialogType. See the above documentation of this class regarding the types of dialogs supported.

See Also:

Constant Field Values

PROP_PARENT_DIALOG_URI

public static final String PROP_PARENT_DIALOG_URI

Applications must set this property for those form objects representing a dialog of type Subdialog using the value returned by getDialogID() on the parent form from which the subdialog was triggered.

See Also:

Constant Field Values

PROP_ROOT_GROUP

protected static final String PROP_ROOT_GROUP

See Also:

Constant Field Values

Constructor Detail

Form

public Form(String uri)

For usage by de-serializers only.

Form

protected Form(String uriPrefix,
               int numProps)

Parameters:

uriPrefix -

numProps -

Method Detail

newDialog

public static Form newDialog(String formTitle,
                             Resource dataRoot)

Constructs and returns a new form object representing an empty dialog of type Standard Dialog with proper initial configuration. See also the discussion of dialog types in the above documentation of this class.

Parameters:

formTitle - The form title giving the intent of the dialog.

dataRoot - The Resource containing the form data. It can be null, if no hidden data was prepared by the application and any initial value to be associated with form controls is going to be set through their constructors. See also PROP_DIALOG_DATA_ROOT.

Returns:

A newly constructed form object representing an empty dialog of type Standard Dialog with proper initial configuration.

newDialog

public static Form newDialog(String formTitle,
                             String dataRootType)

An alternative for newDialog(String, Resource) to be used if no specific data root is going to be specified but only the URI of its type.

newMessage

public static Form newMessage(String formTitle,
                              String message)

Constructs and returns a new form object representing a Message dialog that is ready to publish within an UIRequest. See also the discussion of dialog types in the above documentation of this class.

Parameters:

formTitle - The form title giving the intent of the dialog.

message - The text of the message.

Returns:

A newly constructed form object representing a Message dialog that is ready to publish within an UIRequest.

newSubdialog

public static Form newSubdialog(String formTitle,
                                String parentDialogURI)

Constructs and returns a new form object representing an empty dialog of type Subdialog with proper initial configuration. See also the discussion of dialog types in the above documentation of this class. To set hidden form data, you must first get the data root using getData() and then add your data calling its method Resource.setPropertyPath(String[], Object) .

Parameters:

formTitle - The form title giving the intent of the dialog.

parentDialogURI - The ID of the parent dialog. See also PROP_PARENT_DIALOG_URI.

Returns:

A newly constructed form object representing an empty dialog of type Subdialog with proper initial configuration.

newSystemMenu

public static Form newSystemMenu(String formTitle)

getCreationTime

public XMLGregorianCalendar getCreationTime()

Returns the time at which the first time the form was created by an application.

See Also:

PROP_DIALOG_CREATION_TIME

getCurrentFocusedControl

public FormControl getCurrentFocusedControl()

See Also:

PROP_DIALOG_CURRENT_FOCUSED_CONTROL

getData

public Resource getData()

See Also:

PROP_DIALOG_DATA_ROOT

getDialogCreator

public String getDialogCreator()

See Also:

PROP_DIALOG_CREATED_BY

getDialogID

public String getDialogID()

Returns the URI of this form object as its global unique ID.

getDialogType

public DialogType getDialogType()

See Also:

PROP_DIALOG_TYPE

getIOControls

public Group getIOControls()

Returns the standard group for UI controls in this form. See also the above documentation of this class concerning the standard groups within forms.

getMessageContent

public String getMessageContent()

Returns the text message originally set if this form was created by newMessage(String, String). Otherwise, it returns null.

getParentDialogResource

public Resource getParentDialogResource()

Returns the parent dialog as an empty resource with PROP_PARENT_DIALOG_URI as its URI.

getParentDialogURI

public String getParentDialogURI()

See Also:

PROP_PARENT_DIALOG_URI

getSharedOutputs

public Output[] getSharedOutputs()

Returns all the Output controls contained in the ioControls group (see the above documentation of this class concerning the standard groups within forms) that are likely to be relevant for human users in order to decide what to do with this dialog. The assumption is that there may be other Output controls specific to certain submissions possible within this dialog, which will be ignored by this method as they do not represent shared info.

getStandardButtons

public Group getStandardButtons()

Returns the pre-defined group of standard buttons in this form. See also the above documentation of this class concerning the standard groups within forms.

getStandardButtonsDialogID

public String getStandardButtonsDialogID()

Reserved for use by a dialog management solution that has access to all dialogs and adds standard buttons beyond the application logic to reflect a system-wide behavior.

getSubmits

public Group getSubmits()

Returns the standard group for submit buttons in this form. See also the above documentation of this class concerning the standard groups within forms.

getTitle

public String getTitle()

Returns the form title reflecting the intent of this dialog and originally set when constructing this form object.

isStandardDialog

public boolean isStandardDialog()

Answers if this form object is created by newDialog(String, Resource).

See Also:

PROP_DIALOG_TYPE

isMessage

public boolean isMessage()

Answers if this form object is created by newMessage(String, String).

See Also:

PROP_DIALOG_TYPE

isSubdialog

public boolean isSubdialog()

Answers if this form object is created by newSubdialog(String, String).

See Also:

PROP_DIALOG_TYPE

isSystemMenu

public boolean isSystemMenu()

Answers if this form object is created by newSystemMenu(String).

See Also:

PROP_DIALOG_TYPE

setCurrentFocusedControl

public void setCurrentFocusedControl(FormControl fc)

See Also:

PROP_DIALOG_CURRENT_FOCUSED_CONTROL

setDialogCreator

public void setDialogCreator(String creator)

See Also:

PROP_DIALOG_CREATED_BY

substituteData

public void substituteData(Resource pr)

Reserved for usage by the middleware.

searchFormControl

public FormControl searchFormControl(String formControlURI)

look for a FormControl within the form with the given URI.

Parameters:

formControlURI -

Returns:

the FormControl or null if not found.