"Field" Objects 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. Properties obj.fieldName._queue.dependencies The dependencies property is an array containing all of the dependency events that need to be processed. Dependencies are used to create a relationship between fields. (For example: objForm.LastName.createDependencyTo("FirstName") says that the field LastName is only required if the field FirstName is populated with a value.) obj.fieldName._queue.validation The validation property is an array containing all of the validation events that need to be processed during the onBlur event if the validate property is set to true. The validation queue is generated automatically when the validate-style method is called. obj.fieldName.container The container property is special property for use with select box elements. If the container property is set to true then all items in the select box are consider part of the value—not just the selected items, which is the default behavior for a form field. If set to false then the select box is treated like a normal select box and only the selected items are used to determine the value. The default value is false. obj.fieldName.defaultValue The defaultValue property is default value of the selected form field element. obj.fieldName.description The description property holds a description for the current field. By default the description is equal to the lower case value of the field name. The description property can be set any time after the qForms object has been initialized. This property is used to describe the current form field for when the user has to be notified about an error. obj.fieldName.name The name property is name of the current form field element. obj.fieldName.lastValue The lastValue property contains the previous value of the current form field element. If the value has never been changed, then it will be equal to the defaultValue property. obj.fieldName.locked The locked property is used to prevent a form field from being edited. Valid values are true or false. When set to true, the elements is locked and cannot be edited. When set to false, then the field is not locked. obj.fieldName.obj The obj property contains a pointer to the physical form field element. This can be used if you ever need to access unsupported methods or properties of the form field element. obj.fieldName.path The path property is a string representing the path to the current form field element. (For example: document.frmExample.Name) obj.fieldName.pointer The pointer property is a string containing the qFormAPI pointer. obj.fieldName.qForm The qForm property is a pointer to the qForm that the current Field object current belongs too. obj.fieldName.required The required property defines whether or not a field is required in order for the form to be submitted. obj.fieldName.requiredMessage This allows you to override the default message that's presented when a field is required (normally: "The " + obj.fieldName.description + " field is required.") NOTE: To insert quotes in the string, you must use the string \\\". This will properly escape the quote for use in the string; otherwise a JS error may occur. Example: obj.fieldName.requiredMessage = "This is a \\\"required\\\" message with quotes."; This would display as: This is a "required" message with quotes. obj.fieldName.type The type property defines the selected field element's type. obj.fieldName.validate The validate property defines whether or not a field should be validate when the focus is removed from the form field element. This property is only used when the validation methods are initialized, so this is a runtime only property. Once the validation method has been initialized, the value of this property is no longer referenced. Methods obj.fieldName.addEvent(string event, string command, [boolean append]) The addEvent method will dynamically attach the specified command to the requested field event. The event argument is the name of the event to attach the command to. This is a required parameter. The command argument is JavaScript code to attach to the event. The append argument is an optional argument that accepts either the value true or false. If true, then the command will be attached to the end of any existing instructions already in the specified event. If false, then the event will be attached in front of any other instructions. The default value is true. obj.fieldName.allowFocus() The allowFocus method is run each time a form field receives focus. This method handles several things. If the style on the form field has been changed due to a validation error, the style change is undone. It also check to see if the field is locked, if so, then an error message is displayed and focus is removed from the form field. If the field receives focus, then the obj.fieldName.onFocus() method is invoke, along with any other commands attached to the event handler. obj.fieldName.blur() The blur method will put the remove focus from the selected form field element. obj.fieldName.checkIfLocked([boolean showMsg]) The checkIfLocked method is called each time a form field receives focus. If the field is locked, then by default a message is displayed to the user and focus is removed from the form field. If parameter showMsg is optional and when set to true a message alerting the user to the fact that field is disabled will appear and the focus will be removed from the form field. If set to false, then no message will be displayed and false will be returned if the field is locked and true will be returned if the field is unlocked. The default value is true. obj.fieldName.checkForErrors() The checkForErrors method is called each time a form field loses focus. If the field's validate property is set to true, then any validation methods queued will be executed. The first error that occurs will be thrown to the screen and the focus will be returned to the form element. If no errors occur then onBlur event will continue normally. obj.fieldName.click() The click method will call the field's onclick event. obj.fieldName.disabled([boolean status]) The disabled method will disable the selected form element. This will prevent the user from being able to change the value of the element. If the browser supports the HTML 4 "disabled" property, then the field is set to disabled, otherwise the custom qForm "locked" property is used. This provides for a cross browser compatible method of disabling a form field. The status arguement is an optional argument which allows you to specify whether the field should be disabled (true) or enabled (false.) By default, if no argument is given the status of the form field's disabled status is toggled. obj.fieldName.focus() The focus method will put the focus on the selected form field element. obj.fieldName.getValue() The getValue method will return the current value for the selected form field element. The getValue method will return the current value of any form field element. If the selected element can have multiple items selected or checked, then multiple values will be comma delimited—just as they would appear when submitted to the server. obj.fieldName.isDisabled() The isDisabled method returns true if the current field's "disabled" property or if the form's "disabled" property is set to true, otherwise the method returns false. obj.fieldName.isLocked() The isLocked method returns true if the current field's "locked" property or if the form's "locked" property is set to true, otherwise the method returns false. obj.fieldName.onFocus() The onFocus method is run each time the obj.fieldName.allowFocus() method is true. You can attach your own function to this event which will be processed each time a field receives focus. obj.fieldName.onSetValue() The onSetValue method is run each time the obj.fieldName.setValue() method is run. Use this function to define a custom function to run for a specific field when the setValue method is run. obj.fieldName.reset() The reset method will reset the value of the current form field to its default value. obj.fieldName.select() The select method will select the text in a text or textarea form field. obj.fieldName.setValue(string value, [boolean reset], [boolean doEvents]) The setValue method will set the selected form field's value equal to that of the "value" argument. If you wish to completely wipe any value from the selected form field, pass the value null. The setValue method will also trigger the onChange event for the form field if the value was changed. The setValue method works for any form field element. NOTE: The setValue() simply configures each form field so that when the information is sent back to the server, the value the server sees is equal to "value" argument. For example, if you have series of checkboxes that share the same name attribute, then qForms will compare the value attribute of each input tag and set the "checked" property of the field to true if the value is the list of values passed to the setValue() method. If the optional argument "reset" is set to true, then the current value will be erased, and the value of the field will be replaced with the provided value. If set to false, then the provided value will be appended to the current value. This works only on form elements that can have multiple options selected or checked. The default value is true. If the optional argument "doEvents" is set to true, then after the value for the field is updated, the field's "onblur" and "onchange" event handlers will be executed. If set to false the event will not be executed. The default value is true. obj.fieldName.throwError(string error) The throwError method is used to generated a validation error when the form is submitted. If the error parameter is a valid string, then that message will be added to the obj._queue.error array, which is displayed if any errors occurred when the obj.validate() was called. obj.fieldName.triggerEvent(string event) The triggerEvent method is used to trigger one of the form fields event. The string argument is required and should be equal a valid event for the field. obj.fieldName.validateExp(string expression, [string error], [string command]) The validateExp method is used to create simple expression validation. You can use the validateExp() method easily verify that a particular field is equal to a certain value, or to make sure that a field contains at least X number of characters. The validateExp() behaves just like all "validate" style validation methods. The expression argument is a required parameter and is the expression used to determine whether or not to throw an error. An expression is any valid string that when evaluated returns true or false. If the expression returns true an error will be thrown. For example, the expression "this.getValue().length > 4" when evaluate would return true if the value of the field was greater then 4 and false if was less then or equal to 4. The error argument is the message to be displayed should the expression return true. By default a generic message is displayed that tells you what field the error occurred in. The command argument is an optional parameter used to specify a command to append to the validation method when it is called. This can be used to call another function or to simply set the value of a variable. [< Back] [Index] [Next >]