The CSForm
class includes methods for the retrieval of the form definition, loading initial data into
the form, building the form HTML, and validating and storing captured data. All such methods require that certain
database and key information (form name, for example) be specified via the set
methods provided, prior
to their invocation.
An iCM form consists primarily of Form Sections (CSFormSection
), which in turn consist primarily of Form
Items (CSFormItem
). This structure is reflected in the behaviour of the CSForm
object.
The CSForm
get
method automatically creates CSFormSection
objects for
each of the sections, and CSFormSection
get
method in turn automatically
creates CSFormItem
objects for each of the items in the form section. Calls to methods on a
CSForm
object are cascaded down through the constituent form sections and form items. For example, the
loadData
method calls the loadData
method of each of the
CSFormSection
objects, which in turn call the loadData
method of each of their
CSFormItem
objects.
All database access/connectivity is handled internally by the CSForm
class.
SAMPLE CODE :
Prepare a form for display on the website :
// Create a form object and retrieve the details from the database
CSForm f = new CSForm(myPropertyFile);
f.setFormName("Test Form");
f.get();
// Load the data from an existing CSObject so it can be updated via the form
f.setDataObject(myDataObject);
f.loadData();
// Output the HTML to display the form (create a form tag and a means of submitting the form)
String formTag = "<FORM NAME='Test_Form' ACTION='someURL'";
formTag += "METHOD='post' ONSUBMIT='return CSCheckTest_Form(this);'>";
out.println(formTag);
out.println( f.buildHTML() );
String submitButton = "<INPUT type='Submit'>";<br>
out.println(submitButton);
String formCloseTag = "</FORM>";
out.println(formCloseTag);
Process the form after it has been submitted :
// Re-create the form object
CSForm f = new CSForm(myPropertyFile);
f.setFormName("Test Form");
f.get();
// Tell the form object where to find the submitted data (JSP)
f.setCapturedData(request); // JSP only
// Tell the form object where to find the submitted data (non-JSP)
f.setCapturedData(myHashtable); // non-JSP : you must create a <code>Hashtable</code> of name-value pairs
// Load the submitted values into the form object and validate
f.loadCapturedValues();
if ( f.validate() )
{
// All OK so store the captured data in a <code>CSObject</code>
f.setDataObject(myDataObject);
f.storeData();
myDataObject.update();
}
else
{
// Validation errors so iterate over the error messages
Iterator it = f.getErrorMessageList().iterator();
while ( it.hasNext() )
{
// display the error
}
}
public class CSForm 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 |
---|
CSForm()
Deprecated.
Creates an empty
CSForm object. |
CSForm(java.lang.String strPropertyFile)
Deprecated.
Creates a new
CSForm , specifying a property file that contains all of the database connection
details. |
Modifier and Type | Method and Description |
---|---|
java.lang.String |
buildHTML()
Deprecated.
Builds the HTML to display a complete form or a section of a form, including Javascript validation, as defined
within iCM.
|
void |
cacheAll()
Deprecated.
Re-caches all forms.
|
CSForm |
clone()
Deprecated.
Creates a duplicate of this
CSForm object. |
void |
decacheAll()
Deprecated.
Empty the cache of forms.
|
void |
delete()
Deprecated.
Not currently implemented for
CSForm . |
boolean |
equals(java.lang.Object obj)
Deprecated.
Checks whether this item is equal to another item.
|
boolean |
exist()
Deprecated.
Not currently implemented for
CSForm . |
void |
get()
Deprecated.
Retrieves the details of an iCM form from the database.
|
java.util.ArrayList<CSForm> |
getCache()
Deprecated.
Return all currently cached forms.
|
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. |
java.util.ArrayList |
getErrorMessageList()
Deprecated.
Returns a list of the error messages for the form items which were flagged as invalid by the
validate method. |
int |
getFormID()
Deprecated.
Gets the unique ID of the form specified as key information.
|
java.lang.String |
getFormJavaScript()
Deprecated.
Gets the JavaScript used by the form.
|
java.lang.String |
getFormName()
Deprecated.
Gets the name of the form specified as key information.
|
boolean |
getPrivateForm()
Deprecated.
Gets whether or not this form is private.
|
boolean |
getReadOnly()
Deprecated.
Gets whether this form is to be displayed as read-only.
|
boolean |
getRenderAsXHTML()
Deprecated.
Gets whether controls on this form are to be displayed as XHTML.
|
java.lang.String |
getSectionName()
Deprecated.
Gets the name of the form section specified as key information.
|
int |
getSectionNumber()
Deprecated.
Gets the ordinal number of the form section specified as key information.
|
boolean |
getShowControls()
Deprecated.
Gets whether the items on this form are to be displayed using the appropriate input controls whilst in read-only
mode - see
setReadOnly . |
int |
hashCode()
Deprecated.
|
java.util.Iterator |
iterator()
Deprecated.
Returns an
Iterator over the CSFormSection objects belonging to this form. |
void |
loadCapturedValues()
Deprecated.
Loads captured data values from the specified
Hashtable or HttpServletRequest
object into this form's corresponding CSFormItem objects. |
void |
loadData()
Deprecated.
Loads the data from the
CSObject (s) associated with this form, into the corresponding
CSFormItem objects. |
void |
setCapturedData(java.util.Hashtable objCapturedDataHt)
Deprecated.
Sets the
Hashtable object containing the captured data for the form. |
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, or which
will be used to store new data captured via this form. |
void |
setDetailLevel(int nDetailLevel)
Deprecated.
Sets the level of detail to be handled by the
get method. |
void |
setFormID(int nFormID)
Deprecated.
Sets the unique ID of the form to be used as key information.
|
void |
setFormJavaScript(java.lang.String strJavaScript)
Deprecated.
Sets the JavaScript to be used by the form.
|
void |
setFormName(java.lang.String strFormName)
Deprecated.
Sets the name of the form to be used as key information.
|
void |
setPrivateForm(boolean bPrivate)
Deprecated.
Sets whether or not this form is private.
|
void |
setReadOnly(boolean bReadOnly)
Deprecated.
Sets whether this form is to be displayed as read-only.
|
void |
setRenderAsXHTML(boolean RenderAsXHTML)
Deprecated.
Sets whether controls on this form are to be displayed as XHTML or HTML.
|
void |
setSectionName(java.lang.String strSectionName)
Deprecated.
Sets the name of the form section to be used as key information.
|
void |
setSectionNumber(int nSectionNumber)
Deprecated.
/**
Sets the ordinal number of the section within the iCM form, to be used as key information.
|
void |
setShowControls(boolean bShowControls)
Deprecated.
Sets whether the items on this form are to be displayed using the appropriate input controls whilst in read-only
mode - this option will be ignored unless the form is being displayed in read-only mode via the
setReadOnly method. |
void |
storeData()
Deprecated.
Transfers the captured data values from this form into the
CSObject (s) associated with its constituent
CSFormItem objects. |
java.lang.String |
toString()
Deprecated.
Provides debug information on the contents of the
CSForm object, including its constituent
CSFormSection and CSFormItem objects. |
void |
update()
Deprecated.
Not currently implemented for
CSForm . |
boolean |
validate()
Deprecated.
Validates the data which has been captured using the form.
|
getID, getStatus, jsonString, serialiseWithTypes, setID, setStatus, unset
clearRecordedGatewayMessages, count, getCachingEnabled, getDatabaseVersion, getDatabaseVersion, getDebugOutput, getDetailLevel, getPreview, getPropertyFile, getPropertyFileExtension, getPropertyFilePathname, getRecordedGatewayMessages, getRecordGatewayMessages, getSendGatewayMessages, getUseCache, setDebugOutput, setPreview, setPropertyFile, setRecordGatewayMessages, setSendGatewayMessages, setUseCache
public CSForm()
CSForm
object.
Use the various set methods provided to initialise the CSForm
object prior to invoking any of its
query or form manipulation methods. The datasource information should be specified using these set
methods.
public CSForm(java.lang.String strPropertyFile)
CSForm
, specifying a property file that contains all of the database connection
details.
Use the various set methods provided to initialise the CSForm
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 form as read-only or
disabled.
bReadOnly
- true
if this is a read-only form, otherwise false
.public boolean getReadOnly()
true
if this form is read-only; otherwise returns false
.public void setShowControls(boolean bShowControls)
setReadOnly
method.
If set to true
, the buildHTML
method will display the form 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 form's controls are to be displayed, otherwise false
.public boolean getShowControls()
setReadOnly
.
true
if the form'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 as XHTML. A
false
setting will render the form as HTML.
RenderAsXHTML
- true
if this should be rendered as XHTML, otherwise false
.public boolean getRenderAsXHTML()
true
if this form is to be rendered as XHTML; otherwise returns false
(HTML).public void setFormID(int nFormID)
setFormID
followed by a call to get
will return details of the form, and its
constituent CSFormSection
and CSFormItem
objects.
nFormID
- the unique form IDpublic int getFormID()
public void setFormName(java.lang.String strFormName)
setFormName
followed by a call to get
will return details of the form, and its
constituent CSFormSection
and CSFormItem
objects.
strFormName
- the name of the form.public java.lang.String getFormName()
public void setFormJavaScript(java.lang.String strJavaScript)
The JavaScript attached to a form is output once at the start of the form's HTML. This Javascript is typically used to include AJAX libraries for use by the form controls.
strJavaScript
- the JavaScript to attach to the form.public java.lang.String getFormJavaScript()
This property is only returned from the database if the setDetailLevel
is set to
LEVEL_SUMMARY
or greater.
public void setSectionNumber(int nSectionNumber)
CSForm
object consists of only the first section on the form.
setFormName
and setSectionNumber
followed by a call to
get
will return details of the form, which will have only one constituent CSFormSection
.
This section will be the nth section on the iCM form, where n is the specified section number.
nSectionNumber
- the ordinal number of the form section within the iCM form, to be used as key information. The
CSForm
object will consist of only this section.public int getSectionNumber()
public void setSectionName(java.lang.String strSectionName)
setFormName
and setSectionName
followed by a call to get
will return
details of the form, which will have only one constituent CSFormSection
, with the specified section
name.
strSectionName
- the name of the form section, where the form is to consist of only one section.public java.lang.String getSectionName()
public java.util.Iterator iterator()
Iterator
over the CSFormSection
objects belonging to this form.
Iterator
over the list of CSFormSection
objects.public void setPrivateForm(boolean bPrivate)
Used in conjunction with setFormName
to identify the type of form to be returned by
a call to get
.
bPrivate
- true
if this form is Private, or false
if it is Public.public boolean getPrivateForm()
Used in conjunction with setFormName
to identify the type of form to be returned by
a call to get
.
true
if this form is Private, or false
if it is Public.public void setDataObject(CSObject objDataObject) throws CSException
CSObject
instance which contains the existing data to be updated using this form, or which
will be used to store new data captured via this form. The setting is of this data object is cascaded to all the
constituent form sections and form items.
A CSObject
should only be associated with this CSForm
object if all the form
sections use data from the same CSObject
. If the form sections use data from different
CSObject
s, then the different CSObject
s should be associated with the form
sections using the setDataObject
method on the individual CSFormSection
objects.
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 CSForm
object.
objDataObject
- the CSObject
object holding the data to be updated or newly captured using this form.CSNotFoundException
- if the supplied data object could not be retrievedCSException
- the base class for exceptions thrown by this method.public CSObject getDataObject()
CSObject
instance which holds the data associated with this form.
CSObject
instance holding the data to be updated or newly captured using this form.public void setCapturedData(java.util.Hashtable objCapturedDataHt)
Hashtable
object containing the captured data for the form. The setting is cascaded to
all the constituent form sections and form items. (Note for JSP : use the
setCapturedData(HttpServletRequest)
method instead.)
This Hashtable
should contain 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 CSForm
object. Any irrelevant data will simply be ignored.
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 CSForm
object.
objCapturedDataHt
- the Hashtable
object containing the name-value pairs of the captured data.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 sections and 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 CSForm
object. Any
irrelevant data will simply be ignored.
After the HttpServletRequest
object has been specified using this method, the
loadCapturedValues
method should be called to actually load the captured values
from the Hashtable
into this CSForm
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 are :
LEVEL_ID
Retrieves Form ID and Name only.
LEVEL_SUMMARY
Retrieves Form ID, Form Name and an array of Section ID, Section Name
information.
LEVEL_ALL
Retrieves the above plus the full section and 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
CSFormSection
objects for each of the
form sections making up the form, which in turn creates CSFormItem
objects for each of the form items
making up each of these sections.
Use setFormID
followed by get
to populate this CSForm
object with the details of the form with the specified ID.
Use setFormName
followed by get
to populate this CSForm
object with the details of the form with the specified name.
Use setSectionName
as well as setFormName
or
setFormID
followed by get
to populate this CSForm
object with the
details of only the section with the specified name.
Use setSectionNumber
as well as setFormName
or
setFormID
followed by get
to populate this CSForm
object with the
details of only the nth section within the form.
get
in class CSItem
CSParameterException
- if an invalid combination of key information has been supplied.CSDatabaseException
- if there are problems accessing the database.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 equals(java.lang.Object obj)
CSItem
CSItemContent
object will be compared and the objects deemed to be equal if this matches - key information specified via the
set
methods is ignored and so may be different. Note that the key data used for searching is not
tested for equality.
public boolean exist() throws CSException
CSForm
.
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
CSForm
.
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
CSForm
.
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
(s) associated with this form, into the corresponding
CSFormItem
objects.
Use to initialise the starting (default) values for the form items, with existing data from the CSObject
(s)
which have been associated with this form with the setDataObject
method.
This method can be called even if different form sections have different data objects associated with them, as the data objects will have been cascaded to the appropriate form items.
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
(s) associated with its constituent
CSFormItem
objects.
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. This method can be called even if different form sections have
different data objects associated with them, as the data objects will have been cascaded to the appropriate form
items.
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's corresponding CSFormItem
objects.
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 CSForm
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 java.lang.String buildHTML() throws CSException
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, where formname is the name of the form.
TEXTAREA control types defined within iCM form's cannot be used as required fields since the <TEXTAREA> tag is used, rather than a <CFINPUT> tag, to generate the field control.
EXAMPLE :
A form named "OrderDetails" would result in a Javascript function called "CSCheckOrderDetails".
HTML to display the form :
<FORM NAME="OrderDetails" ACTION="someURL" METHOD="post" ONSUBMIT="Javascript: return CSCheckOrderDetails(this);">
Output the string returned from the CSForm
's buildHTML()
here
<INPUT TYPE="Submit" VALUE="Submit">
</FORM>
String
containing the HTML that will display the form/form section.CSException
- if the DetailLevel is less than LEVEL_ALL
public boolean validate() throws CSValidationException
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 will be indicated by this method - it will return false if there are
errors. 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.
public void cacheAll() throws java.sql.SQLException, CSException
java.sql.SQLException
- SQLExceptionCSException
- CSExceptionpublic void decacheAll()
public java.util.ArrayList<CSForm> getCache()
getCache
in class CSDatabaseItem
public CSForm clone() throws java.lang.CloneNotSupportedException, java.lang.OutOfMemoryError
CSForm
object.
clone
in class CSDatabaseItem
CSForm
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()
CSForm
object, including its constituent
CSFormSection
and CSFormItem
objects.
Copyright © 2022 Goss Interactive Ltd. All Rights Reserved.