gi.controlsite.objects

Class CSFormSection

java.lang.Object

gi.controlsite.objects.CSDatabaseItem

gi.controlsite.objects.CSItem

gi.controlsite.objects.CSFormSection

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Deprecated.

This is only used by pre-V9 forms. Class that handles the querying and manipulation of an iCM form section.

The CSFormSection class includes methods for the retrieval of the form section definition, loading initial data into the form section, building the form section HTML, and validating and storing captured data. All such methods require that certain database and key information (form section name, for example) be specified via the set methods provided, prior to their invocation.

An iCM form section consists primarily of Form Items (CSFormItem). This structure is reflected in the behaviour of the CSFormSection object.

The CSFormSection get method automatically creates CSFormItem objects for each of the form items in the form section. Calls to methods on a CSFormSection object are cascaded down through the constituent form items. For example, the loadData method calls the loadData method of each of the CSFormItem objects.

Typically, a form section belongs to a form (CSForm). It is not usually necessary to create or call methods on a CSFormSection object directly. CSFormSection objects are automatically created by the get method of the CSForm object to which the form section belongs, and calls to methods on the CSForm object are cascaded down to the constituent form sections.

Call methods on the CSFormSection object only if the section requires special treatment. For example, to associate a different data object with the form section, or to obtain the HTML for the section in order to customise its display.

All database access/connectivity is handled internally by the CSFormSection class.

public class CSFormSection
extends CSItem

See Also:

CSFormSectionContent, CSForm, CSFormSectionMultiple, CSFormItem, CSFormItemMultiple, Serialized Form

Field Summary

Fields inherited from class gi.controlsite.objects.CSItem

ACCESS_GRANTED, DOES_NOT_EXIST, EMPTY, EXISTS, SECURE_ACCESS_DENIED, SECURE_ACCESS_GRANTED, UPDATE_ACTION_INSERTED, UPDATE_ACTION_UPDATED

Fields inherited from class gi.controlsite.objects.CSDatabaseItem

LEVEL_ALL, LEVEL_ALL_PLUS_RELATED, LEVEL_DETAIL, LEVEL_ID, LEVEL_SUMMARY

Constructor Summary

Constructors

Constructor and Description
CSFormSection() Deprecated. Creates an empty CSFormSection object.
CSFormSection(java.lang.String strPropertyFile) Deprecated. Creates a new CSFormSection, specifying a property file that contains all of the database connection details.

Method Summary

Modifier and Type	Method and Description
java.lang.String	buildHTML(java.lang.String formName) Deprecated. Builds the HTML to display all the form items on this form section, including Javascript validation for these items as specified in iCM.
java.lang.String	buildHTML(java.lang.String strFormName, java.lang.String strFormValidation) Deprecated. Builds the HTML to display all the form items on this form section, including Javascript validation for these items as specified in iCM.
java.lang.Object	clone() Deprecated. Creates a duplicate of this CSFormSection object.
void	delete() Deprecated. Not currently implemented for CSFormSection.
boolean	exist() Deprecated. Not currently implemented for CSFormSection.
void	get() Deprecated. Retrieves the details of an iCM form section from the database.
java.util.Hashtable	getCapturedData() Deprecated. Gets the Hashtable object which holds the name-value pairs of captured data.
CSObject	getDataObject() Deprecated. Gets the CSObject instance which holds the data associated with this form section.
java.util.ArrayList	getErrorMessageList() Deprecated. Returns a list of the error messages for the form items belonging to this form section which were flagged as invalid by the validate method.
boolean	getReadOnly() Deprecated. Gets whether this form section is to be displayed as read-only.
boolean	getRenderAsXHTML() Deprecated. Gets whether controls on this form section are to be displayed as XHTML.
java.lang.String	getSectionID() Deprecated. Gets the Object ID of the CSFormSection object which holds the details of this form section.
java.lang.String	getSectionName() Deprecated. Gets the name of the form section.
boolean	getShowControls() Deprecated. Gets whether the items on this section are to be displayed using the appropriate input controls whilst in read-only mode - see setReadOnly.
java.util.Iterator	iterator() Deprecated. Returns an Iterator over the CSFormItem objects belonging to this form section.
void	loadCapturedValues() Deprecated. Loads captured data values from the specified Hashtable or HttpServletRequest object into this form section's corresponding CSFormItem objects.
void	loadData() Deprecated. Loads the data from the CSObject associated with this form section, into the corresponding CSFormItem objects.
void	setCapturedData(HttpServletRequest objJSPRequest) Deprecated. Sets the HttpServletRequest object containing the captured data for the form (JSP only).
void	setDataObject(CSObject objDataObject) Deprecated. Specifies the CSObject instance which contains the existing data to be updated using this form section, or which will be used to store new data captured via this form section.
void	setDetailLevel(int nDetailLevel) Deprecated. Sets the level of detail to be handled by the get method.
void	setReadOnly(boolean bReadOnly) Deprecated. Sets whether this form section is to be displayed as read-only.
void	setRenderAsXHTML(boolean RenderAsXHTML) Deprecated. Sets whether controls on this form section are to be displayed as XHTML or HTML.
void	setSectionID(java.lang.String strSectionID) Deprecated. Sets the Object ID of the CSFormSection object which holds the details of this form section.
void	setSectionName(java.lang.String strSectionName) Deprecated. Sets the name of the form section.
void	setShowControls(boolean bShowControls) Deprecated. Sets whether the items on this section are to be displayed using the appropriate input controls whilst in read-only mode - this option will be ignored unless the section is being displayed in read-only mode via the setReadOnly method.
void	storeData() Deprecated. Transfers the captured data values from this form section, into the CSObject associated with its constituent CSFormItem objects.
java.lang.String	toString() Deprecated. Provides debug information on the contents of the CSFormSection object, including its constituent CSFormItem objects.
void	update() Deprecated. Not currently implemented for CSFormSection.
boolean	validate() Deprecated. Validates the data which has been captured using the form section.

Methods inherited from class gi.controlsite.objects.CSItem

equals, getID, getStatus, hashCode, jsonString, serialiseWithTypes, setID, setStatus, unset

Methods inherited from class gi.controlsite.objects.CSDatabaseItem

clearRecordedGatewayMessages, count, getCache, getCachingEnabled, getDatabaseVersion, getDatabaseVersion, getDebugOutput, getDetailLevel, getPreview, getPropertyFile, getPropertyFileExtension, getPropertyFilePathname, getRecordedGatewayMessages, getRecordGatewayMessages, getSendGatewayMessages, getUseCache, setDebugOutput, setPreview, setPropertyFile, setRecordGatewayMessages, setSendGatewayMessages, setUseCache

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

CSFormSection

public CSFormSection()

Deprecated.

Creates an empty CSFormSection object.

It is not usually necessary to create a CSFormSection object directly. CSFormSection objects are automatically created by the get method of the CSForm object to which the form section belongs.

Use the various set methods provided to initialise the CSFormSection object prior to invoking any of its query or form manipulation methods. The datasource information should be specified using these set methods.

CSFormSection

public CSFormSection(java.lang.String strPropertyFile)

Deprecated.

Creates a new CSFormSection, specifying a property file that contains all of the database connection details.

Use the various set methods provided to initialise the CSFormSection object prior to invoking any of its query manipulation methods.

Parameters:

strPropertyFile - the property file that contains the connection details.

Method Detail

setReadOnly

public void setReadOnly(boolean bReadOnly)

Deprecated.

Sets whether this form section is to be displayed as read-only.

If set to true, the buildHTML method will display the section as read-only or disabled.

Parameters:

bReadOnly - true if this is a read-only form section, otherwise false.

getReadOnly

public boolean getReadOnly()

Deprecated.

Gets whether this form section is to be displayed as read-only.

Returns:

returns true if this form section is read-only; otherwise returns false.

setShowControls

public void setShowControls(boolean bShowControls)

Deprecated.

Sets whether the items on this section are to be displayed using the appropriate input controls whilst in read-only mode - this option will be ignored unless the section is being displayed in read-only mode via the setReadOnly method.

If set to true, the buildHTML method will display the section with all the relevant input controls disabled or set to read-only. If set to false, the form labels and current values will be displayed as simple text.

Parameters:

bShowControls - true if the section's controls are to be displayed, otherwise false.

getShowControls

public boolean getShowControls()

Deprecated.

Gets whether the items on this section are to be displayed using the appropriate input controls whilst in read-only mode - see setReadOnly.

Returns:

returns true if the section's controls are to be displayed, otherwise returns false.

setRenderAsXHTML

public void setRenderAsXHTML(boolean RenderAsXHTML)

Deprecated.

Sets whether controls on this form section are to be displayed as XHTML or HTML.

If set to true, the buildHTML method will display the form section as XHTML. A false setting will render the section as HTML.

Parameters:

RenderAsXHTML - true if this should be rendered as XHTML, otherwise false.

getRenderAsXHTML

public boolean getRenderAsXHTML()

Deprecated.

Gets whether controls on this form section are to be displayed as XHTML.

Returns:

returns true if this form section is to be rendered as XHTML; otherwise returns false (HTML).

setSectionName

public void setSectionName(java.lang.String strSectionName)

Deprecated.

Sets the name of the form section.

Parameters:

strSectionName - the form section's name.

getSectionName

public java.lang.String getSectionName()

Deprecated.

Gets the name of the form section.

Returns:

The form section's name.

setSectionID

public void setSectionID(java.lang.String strSectionID)

Deprecated.

Sets the Object ID of the CSFormSection object which holds the details of this form section.

Parameters:

strSectionID - the form section's Object ID.

getSectionID

public java.lang.String getSectionID()

Deprecated.

Gets the Object ID of the CSFormSection object which holds the details of this form section.

Returns:

The form section's Object ID.

iterator

public java.util.Iterator iterator()

Deprecated.

Returns an Iterator over the CSFormItem objects belonging to this form section.

Returns:

Iterator over the list of CSFormItem objects.

setDataObject

public void setDataObject(CSObject objDataObject)

Deprecated.

Specifies the CSObject instance which contains the existing data to be updated using this form section, or which will be used to store new data captured via this form section. The setting is cascaded to all the constituent form items.

Note that the data object will be automatically set by a call to the setDataObject method has been called of the CSForm object to which this form section belongs, or when this CSFormSection object is created by the get method of the CSForm. It is only necessary to call the method on this CSFormSection object if it does not use data from the same CSObject as the other sections on the form.

If the form is being used to update data held on an existing CSObject, then after the CSObject has been specified using this method, the loadData method should be called to actually load the data from the CSObject into this CSFormSection object.

Parameters:

objDataObject - the CSObject object holding the data to be updated or newly captured using this form section.

getDataObject

public CSObject getDataObject()

Deprecated.

Gets the CSObject instance which holds the data associated with this form section.

Returns:

The CSObject instance holding the data to be updated or newly captured using this form section.

setCapturedData

public void setCapturedData(HttpServletRequest objJSPRequest)

Deprecated.

Sets the HttpServletRequest object containing the captured data for the form (JSP only). The setting is cascaded to all the constituent form items.

This HttpServletRequest should contain the data submitted via the HTML form. It does not matter if the HttpServletRequest contains data which is irrelevant to this CSFormSection object. Any irrelevant data will simply be ignored.

Note that the captured data hashtable will be automatically set by a call to the setDataObject method of the CSForm object to which this form section belongs. It should not normally be necessary to call the method on this CSFormSection object directly.

After the Hashtable object has been specified using this method, the loadCapturedValues method should be called to actually load the captured values from the Hashtable into this CSFormSection object.

Parameters:

objJSPRequest - the HttpServletRequest object containing the captured data.

getCapturedData

public java.util.Hashtable getCapturedData()

Deprecated.

Gets the Hashtable object which holds the name-value pairs of captured data.

Returns:

The Hashtable object holding the name-value pairs of captured data, which was specified as key information.

setDetailLevel

public void setDetailLevel(int nDetailLevel)
                    throws CSParameterException

Deprecated.

Sets the level of detail to be handled by the get method. Default is LEVEL_ALL.

Valid detail levels for a form section are :

• LEVEL_ID Retrieves Section ID and Name only.

.

• LEVEL_ALL Retrieves the above plus the full Form Item information.

.

Overrides:

setDetailLevel in class CSDatabaseItem

Parameters:

nDetailLevel - the detail level to be used.

Throws:

CSParameterException - if an invalid detail level is specified.

get

public void get()
         throws CSException

Deprecated.

Retrieves the details of an iCM form section from the database. Creates CSFormItem objects for each of the form items making up this form section.

It is not usually necessary to call this method directly on a CSFormSection object. The details of CSFormSection objects are automatically retrieved by the get method of the CSForm object to which the form section belongs. This CSForm getmethod also provides a convenient way of creating a form which consists of only one form section, specified either by name or ordinal number.

Use setSectionName or setSectionID followed by get to populate this CSFormSection object with the details of the section with the specified ID/name.

Overrides:

get in class CSItem

Throws:

CSDatabaseException - if there are problems accessing the database.

CSParameterException - if any of the required key information is missing/incorrect.

CSNotFoundException - if the specified item cannot be found on the database.

CSSecurityException - if security has been breached.

CSException - the base class for exceptions thrown by this method.

exist

public boolean exist()
              throws CSException

Deprecated.

Not currently implemented for CSFormSection.

Overrides:

exist in class CSItem

Returns:

true if this form section exists on the database.

Throws:

CSParameterException - if an invalid combination of key information has been supplied.

CSDatabaseException - if there are problems accessing the database.

CSException - the base class for exceptions thrown by this method.

delete

public void delete()
            throws CSException

Deprecated.

Not currently implemented for CSFormSection.

Overrides:

delete in class CSItem

Throws:

CSParameterException - if an invalid combination of key information has been supplied.

CSDatabaseException - if there are problems accessing the database.

CSNotFoundException - if one of the specified attributes cannot be found on the database.

CSException - the base class for exceptions thrown by this method.

update

public void update()
            throws CSException

Deprecated.

Not currently implemented for CSFormSection.

Overrides:

update in class CSItem

Throws:

CSParameterException - if an invalid combination of key information has been supplied.

CSDatabaseException - if there are problems accessing the database.

CSNotFoundException - if one of the specified attributes cannot be found on the database.

CSException - the base class for exceptions thrown by this method.

loadData

public void loadData()
              throws CSException

Deprecated.

Loads the data from the CSObject associated with this form section, into the corresponding CSFormItem objects.

Use to initialise the starting (default) values for the form items making up this form section with existing data from the CSObject which has been associated with this form section with the setDataObject method.

It is not usually necessary to call this method directly on a CSFormSection object. Data is automatically loaded into the form section from its associated data object by the loadData method of the CSForm object to which the form section belongs, even if not all the form sections on the form have the same associated data object.

Throws:

CSDatabaseException - if there are problems accessing the database.

CSParameterException - if the supplied key information is invalid. For example, if the object holding the data is not a CSObject of the expected type.

CSNotFoundException - if the form cannot be found on the database.

CSSecurityException - if there is a security violation.

CSException - the base class for exceptions thrown by this method.

storeData

public void storeData()
               throws CSException

Deprecated.

Transfers the captured data values from this form section, into the CSObject associated with its constituent CSFormItem objects.

It is not usually necessary to call this method directly on a CSFormSection object. Data is automatically transferred from the form section into its associated data object by the storeData method of the CSForm object to which the form section belongs, even if not all the form sections on the form have the same associated data object.

Use the loadCapturedValues method to insert captured values into the form, and use the setDataObject method to specify the CSObject(s) which is to receive the captured values, before calling this method.

Throws:

CSDatabaseException - if there are problems accessing the database.

CSParameterException - if the supplied key information is invalid. For example, if the object holding the data is not a CSObject of the expected type.

CSNotFoundException - if the form cannot be found on the database.

CSSecurityException - if there is a security violation.

CSException - the base class for exceptions thrown by this method.

loadCapturedValues

public void loadCapturedValues()
                        throws CSException

Deprecated.

Loads captured data values from the specified Hashtable or HttpServletRequest object into this form section's corresponding CSFormItem objects.

It is not usually necessary to call this method directly on a CSFormSection object. Captured data is automatically loaded into the form section from the Hashtable of name-value pairs by the loadCapturedValues method of the CSForm object to which the form section belongs.

Before calling this method, use the setCapturedData method to specify the Hashtable containing the name-value pairs of the data submitted via the HTML form. It does not matter if the Hashtable contains data which is irrelevant to this CSFormSection object. Any irrelevant data will simply be ignored.

Throws:

CSDatabaseException - if there are problems accessing the database.

CSParameterException - if the supplied key information is invalid.

CSNotFoundException - if the form cannot be found on the database.

CSSecurityException - if there is a security violation.

CSException - the base class for exceptions thrown by this method.

validate

public boolean validate()
                 throws CSValidationException

Deprecated.

Validates the data which has been captured using the form section.

It is not usually necessary to call this method directly on a CSFormSection object. The data in a form section is automatically validated by the validate method of the CSForm object to which the form section belongs.

Use the loadCapturedValues method to load the captured values into the corresponding CSFormItems before calling this method.

Any form items which are found to be invalid are flagged. The error messages for the invalid items can then be obtained using the getErrorMessageList method.

Returns:

Returns true if all form items are valid; otherwise returns false.

Throws:

CSValidationException - if unable to perform any required javascript validation

getErrorMessageList

public java.util.ArrayList getErrorMessageList()

Deprecated.

Returns a list of the error messages for the form items belonging to this form section which were flagged as invalid by the validate method.

It is not usually necessary to call this method directly on a CSFormSection object. The error messages for this form section are included in the list of error messages returned by the getErrorMessageList method of the CSForm object to which the form section belongs.

Returns:

A list of String objects, each of which is the error message for an invalid data item.

buildHTML

public java.lang.String buildHTML(java.lang.String formName)

Deprecated.

Builds the HTML to display all the form items on this form section, including Javascript validation for these items as specified in iCM.

It is not usually necessary to call this method directly on a CSFormSection object. The HTML to display the form items on this form section is automatically produced by the buildHTML method of the CSForm object to which the form section belongs.

IMPORTANT :

The HTML returned MUST be output from within <FORM></FORM> tags, and a means of submitting the form (such as a Submit button) must be provided, as well as a means of executing the generated Javascript validation (such as the "onSubmit" attribute in the <FORM> tag).

The Javascript function to validate the form is generated using the naming convention CSCheckformname_sectionname, where formname is the name of the form and sectionname is the name of the section. It has one required parameter, which is the HTML form object.

EXAMPLE :

A section called "DeliveryAddress" on a form named "OrderDetails" would result in a Javascript function called "CSCheckOrderDetails_DeliveryAddressCSConstants.EMPTY.

HTML to display the form :

<FORM NAME="OrderDetails" ACTION="someURL" METHOD="post" ONSUBMIT="Javascript: return CSCheckOrderDetails_DeliveryAddress(this);">

Output the string returned from the CSFormSection's buildHTML() here

<INPUT TYPE="Submit" VALUE="Submit">

</FORM>

Parameters:

formName - the name of the form to use in constructing the Javascript function name.

Returns:

A String containing the HTML to display the form items on this form section.

buildHTML

public java.lang.String buildHTML(java.lang.String strFormName,
                                  java.lang.String strFormValidation)

Deprecated.

Builds the HTML to display all the form items on this form section, including Javascript validation for these items as specified in iCM.

It is not usually necessary to call this method directly on a CSFormSection object. The HTML to display the form items on this form section is automatically produced by the buildHTML method of the CSForm object to which the form section belongs.

IMPORTANT :

The HTML returned MUST be output from within <FORM></FORM> tags, and a means of submitting the form (such as a Submit button) must be provided, as well as a means of executing the generated Javascript validation (such as the "onSubmit" attribute in the <FORM> tag).

The Javascript function to validate the form is generated using the naming convention CSCheckformname_sectionname, where formname is the name of the form and sectionname is the name of the section. It has one required parameter, which is the HTML form object.

EXAMPLE :

A section called "DeliveryAddress" on a form named "OrderDetails" would result in a Javascript function called "CSCheckOrderDetails_DeliveryAddressCSConstants.EMPTY.

HTML to display the form :

<FORM NAME="OrderDetails" ACTION="someURL" METHOD="post" ONSUBMIT="Javascript: return CSCheckOrderDetails_DeliveryAddress(this);">

Output the string returned from the CSFormSection's buildHTML() here

<INPUT TYPE="Submit" VALUE="Submit">

</FORM>

Parameters:

strFormName - the name of the form to use in constructing the Javascript function name. *

strFormValidation - Existing validation to add a new Javascript block to.

Returns:

A String containing the HTML to display the form items on this form section.

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException,
                              java.lang.OutOfMemoryError

Deprecated.

Creates a duplicate of this CSFormSection object.

Overrides:

clone in class CSDatabaseItem

Returns:

The duplicate CSFormSection object.

Throws:

java.lang.CloneNotSupportedException - if cloning is not supported/allowed.

java.lang.OutOfMemoryError - if there are any problems allocating memory.

toString

public java.lang.String toString()

Deprecated.

Provides debug information on the contents of the CSFormSection object, including its constituent CSFormItem objects.

Overrides:

toString in class CSItem

Returns:

The String containing the user-friendly output.