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
ACCESS_GRANTED, DOES_NOT_EXIST, EMPTY, EXISTS, SECURE_ACCESS_DENIED, SECURE_ACCESS_GRANTED, UPDATE_ACTION_INSERTED, UPDATE_ACTION_UPDATED
LEVEL_ALL, LEVEL_ALL_PLUS_RELATED, LEVEL_DETAIL, LEVEL_ID, LEVEL_SUMMARY
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. |
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.
|
equals, getID, getStatus, hashCode, jsonString, serialiseWithTypes, setID, setStatus, unset
clearRecordedGatewayMessages, count, getCache, getCachingEnabled, getDatabaseVersion, getDatabaseVersion, getDebugOutput, getDetailLevel, getPreview, getPropertyFile, getPropertyFileExtension, getPropertyFilePathname, getRecordedGatewayMessages, getRecordGatewayMessages, getSendGatewayMessages, getUseCache, setDebugOutput, setPreview, setPropertyFile, setRecordGatewayMessages, setSendGatewayMessages, setUseCache
public CSFormSection()
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.
public CSFormSection(java.lang.String strPropertyFile)
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.
strPropertyFile
- the property file that contains the connection details.public void setReadOnly(boolean bReadOnly)
If set to true
, the buildHTML
method will display the section as
read-only or disabled.
bReadOnly
- true
if this is a read-only form section, otherwise false
.public boolean getReadOnly()
true
if this form section is read-only; otherwise returns false
.public void setShowControls(boolean bShowControls)
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.
bShowControls
- true
if the section's controls are to be displayed, otherwise false
.public boolean getShowControls()
setReadOnly
.
true
if the section's controls are to be displayed, otherwise returns
false
.public void setRenderAsXHTML(boolean RenderAsXHTML)
If set to true
, the buildHTML
method will display the form section as
XHTML. A false
setting will render the section as HTML.
RenderAsXHTML
- true
if this should be rendered as XHTML, otherwise false
.public boolean getRenderAsXHTML()
true
if this form section is to be rendered as XHTML; otherwise returns
false
(HTML).public void setSectionName(java.lang.String strSectionName)
strSectionName
- the form section's name.public java.lang.String getSectionName()
public void setSectionID(java.lang.String strSectionID)
CSFormSection
object which holds the details of this form section.
strSectionID
- the form section's Object ID.public java.lang.String getSectionID()
CSFormSection
object which holds the details of this form section.
public java.util.Iterator iterator()
Iterator
over the CSFormItem
objects belonging to this form section.
Iterator
over the list of CSFormItem
objects.public void setDataObject(CSObject objDataObject)
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.
objDataObject
- the CSObject
object holding the data to be updated or newly captured using this form
section.public CSObject getDataObject()
CSObject
instance which holds the data associated with this form section.
CSObject
instance holding the data to be updated or newly captured using this form
section.public void setCapturedData(HttpServletRequest objJSPRequest)
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.
objJSPRequest
- the HttpServletRequest
object containing the captured data.public java.util.Hashtable getCapturedData()
Hashtable
object which holds the name-value pairs of captured data.
Hashtable
object holding the name-value pairs of captured data, which was specified as
key information.public void setDetailLevel(int nDetailLevel) throws CSParameterException
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.
setDetailLevel
in class CSDatabaseItem
nDetailLevel
- the detail level to be used.CSParameterException
- if an invalid detail level is specified.public void get() throws CSException
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
get
method
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.
get
in class CSItem
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.public boolean exist() throws CSException
CSFormSection
.
exist
in class CSItem
true
if this form section exists on the database.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.public void delete() throws CSException
CSFormSection
.
delete
in class CSItem
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.public void update() throws CSException
CSFormSection
.
update
in class CSItem
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.public void loadData() throws CSException
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.
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.public void storeData() throws CSException
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.
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.public void loadCapturedValues() throws CSException
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.
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.public boolean validate() throws CSValidationException
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 CSFormItem
s 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.
CSValidationException
- if unable to perform any required javascript validationpublic java.util.ArrayList getErrorMessageList()
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.
public java.lang.String buildHTML(java.lang.String formName)
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>
formName
- the name of the form to use in constructing the Javascript function name.String
containing the HTML to display the form items on this form section.public java.lang.String buildHTML(java.lang.String strFormName, java.lang.String strFormValidation)
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>
strFormName
- the name of the form to use in constructing the Javascript function name. *strFormValidation
- Existing validation to add a new Javascript block to.String
containing the HTML to display the form items on this form section.public java.lang.Object clone() throws java.lang.CloneNotSupportedException, java.lang.OutOfMemoryError
CSFormSection
object.
clone
in class CSDatabaseItem
CSFormSection
object.java.lang.CloneNotSupportedException
- if cloning is not supported/allowed.java.lang.OutOfMemoryError
- if there are any problems allocating memory.public java.lang.String toString()
CSFormSection
object, including its constituent
CSFormItem
objects.
Copyright © 2022 Goss Interactive Ltd. All Rights Reserved.