Field Methods Library
In the properties and methods below, obj is an abbreviation for the object name you specified when you called the qForm constructor. fieldName signifies the form field element that you want to perform the action on. Arguments in bracket ("[ ]") are optional.
- obj.fieldName.dummyContainer
- The dummyContainer property is a boolean value which specifies that the current container is simply used to hold items. A "dummy" container should have no value, and qForms will ensure that no value is returned for a dummy container.
- obj.fieldName.boundContainers
- The boundCountainers property contains an array of all containers bound to the current container. "Bound" containers are used assiociate the items in one select box to another, so that a setValue() method will correctly populate a container with the proper value in the bound container's option array.
- obj.fieldName.compare(object field)
- The compare method will compare the value of the selected form field with the value of the form field specified in the "field" argument. If the values are different, then false is returned. If the values are identical, then true is returned. The field argument is a string equal to that of another qForm field name.
- obj.fieldName.createDependencyTo(string field, [string condition])
-
The createDependencyTo method will create a relationship between the two specified fields.
When a dependency is created the specified condition is execute upon the element in the
field argument. If the condition is true, then the fieldName object becomes a required field.
You can place multiple dependencies on the same field.
The field argument is a required parameter, which specifies the field that the condition should be tested on.
The condition argument is an optional parameter, which determines the condition that's test for. If the condition statement is not provided, then element specified in the field argument is tested to see it contains a value. If it does, then the required property for fieldName is set to true. If a string is passed, then the value of the argument field is tested against the string to see if the match, if they do, then required property for fieldName is set to true. If the condition statement contains the "this" keyword, then the string is evaluated as an expression. In this case, the value of the required property for fieldName will be equal to the expression's result.
For example:
objForm.City.createDependencyTo("Address1");
objForm.State.createDependencyTo("Address1");
objForm.Zip.createDependencyTo("Address1");
objForm.Fax.createDependencyTo("FaxMe", "this.getValue() = 'yes'");This would make the "City", "State" and "Zip" fields required if there is any value in the Address1 field. Also, if the user chooses to be informed via a fax to their order shipment, it would force the "Fax" field to be required.
- obj.fieldName.format(string mask, [string type])
-
The format method allows you to define a basic format that the current field must
be in. The mask can defined in several ways. You can either use a default mask, or
create your own mask. Custom masks are created by using "X"'s to define valid data
types. Wherever an "x" is placed, a valid character type must be present. Valid data
types are defined using the optional "type" argument.
The type argument is an optional parameter that defaults to "numeric." Valid values for the "type" argument are "numeric", "alpha" and "alphanumeric". When using the "numeric" type, then a valid number (0-9) must be filled in for each "X" in the mask. When using the "alpha" type, then an alpha character (A-Za-z) must exist for each "X" in the mask. When using the "alphanumeric" type, either a valid number or alpha character (0-9A-Za-z) needs to be present for each "X" in the mask.
The mask argument can be any custom string, or one of the following predefined masks:
SSN
Makes sure that a 9-digit number in the format "xxx-xx-xxxx" is entered.Phone (or Phone1)
Makes sure that a 10-digit number in the format "(xxx) xxx-xxxx" is entered.Phone2
Makes sure that a 10-digit number in the format "xxx-xxx-xxxx" is entered.Phone3
Makes sure that a 10-digit number in the format "xxx/xxx-xxxx" is entered.Phone7
Makes sure that a 7-digit number in the format "xxx-xxxx" is entered.Zip
Makes sure either a 5 or 9-digit number is entered in either the format "xxxxx" or "xxxxx-xxxx".Zip5
Makes sure a 5-digit number is entered in the format "xxxxx".Zip9
Makes sure a 9-digit number is entered in the format "xxxxx-xxxx".
- obj.fieldName.location([string target], [string key])
-
The location method will use the JavaScript method "location" to try to redirect the user's
browser to the value of the selected form field. This was designed to work with the select
box element as a navigational tool.
The target argument is an optional parameter to specify the target object in which to attach the location method. By default the target object is "self." If you wish to redirect to another frame, then the target should be the string pointer to the JavaScript object.
The key argument is another optional parameter. The key parameter by default is equal to an empty string. If the value of the current form field element is equal to the key, then the location method will not be enacted.
- obj.fieldName.ltrim()
- The ltrim method will strip all whitespaces from the left the side of the current form field's value and update the field.
- obj.fieldName.makeContainer([string bindTo])
-
The makeContainer method will change a select box into a "container." A container is a unique
qForm's type of select box. What makes a container unique is that each item in the container
is part of its value.
When using the setValue() method on a container, a list of the original container values and any bound container objects will be searched, and if a match is found, the container will be populated with matching results.
The bindTo argument is optional and is used to bind other container objects to the current container. When two (or more) containers are bound, then when the setValue() method is called on the main container, all containers will be searched for the value, if a match is found, then that match will be added to the container's pool of objects.
- obj.fieldName.mirrorTo(string object)
-
The mirrorTo method will place a copy of the value of fieldName into the object specified
in the objectName string.
The objectName argument is required and accepts any string which is the name for a valid JavaScript object. The string is then test to see if it's a valid qForms object, if it is, it will update the value of the form specified. If it's not a qForms object, then it'll assume it's a valid JavaScript variable and assign the value of fieldName to the object specified.
- obj.fieldName.populate(object struct, [boolean reset], [boolean sort])
-
The populate method is only available for select box elements. The populate() method will
take in a structure and repopulate the options array based upon the structure passed in.
The keys in the provided structure will be equal to the options "value" and the key's value
will be equal to the options "text" value. This method will not run if the either the
isLocked() method return true.
The reset argument is an optional argument used to define whether or not the options array should be cleared before adding the structure key and values. The default value for this method is true. If set to false, then items in the structure will be appended to the selected field's options array.
The sort argument is an optional argument that can be used to specify whether or not the options array should be resorted in ascending order by the value of the options text value. The default value for the sort argument is false. Valid values are true and false.
- obj.fieldName.resetLast()
- The resetLast method will reset the selected form field element to the value stored in the lastValue property.
- obj.fieldName.rtrim()
- The rtrim method will strip all whitespaces from the right the side of the current form field's value and update the field.
- obj.fieldName.toLowerCase()
- The toLowerCase method will convert the selected form field element to lower case.
- obj.fieldName.toUpperCase()
- The toUpperCase method will convert the selected form field element to upper case.
- obj.fieldName.transferFrom(string field, [boolean sort], [string type], [boolean selectItems], [boolean reset])
-
The transferFrom method will transfer items to the specfied select box from the select
box specified in the field argument. The field argument is required and must be equal
to the name of another qForms select box field. This method will not run if the either
the isLocked() method return true.
The sort argument is an optional argument that can be used to specify whether the options in the specified select box should be resorted in ascending order by the options text value once the transfer is complete. Valid values are true and false. The default value is true.
The type argument is an optional argument that is used to specify whether only the selected items should be moved, or whether all the items should be moved. Valid values are "selected" and "all". The default value is "selected."
The selectItems argument is an optional argument used to specify whether or not the moved items should be selected by default when moved to the new box. Valid values are true and false. The default value is true.
The reset argument is an optional argument used to determine whether or not the target select box should be cleared before moving the specified options. Valid values are true and false. The default value is false.
- obj.fieldName.transferTo(string field, [boolean sort], [string type], [boolean selectItems], [boolean reset])
-
The transferTo method will transfer items from the specfied select box to the select
box specified in the field argument. The field argument is required and must be equal
to the name of another qForms select box field. This method will not run if the either
the isLocked() method return true.
The sort argument is an optional argument that can be used to specify whether the options in the field argument should be resorted in ascending order by the options text value once the transfer is complete. Valid values are true and false. The default value is true.
The type argument is an optional argument that is used to specify whether only the selected items should be moved, or whether all the items should be moved. Valid values are "selected" and "all". The default value is "selected."
The selectItems argument is an optional argument used to specify whether or not the moved items should be selected by default when moved to the new box. Valid values are true and false. The default value is true.
The reset argument is an optional argument used to determine whether or not the target select box should be cleared before moving the specified options. Valid values are true and false. The default value is false.
- obj.fieldName.trim()
- The trim method will strip all whitespaces from the both the left and right sides of the current form field's value and update the field.
