Documentation

resources/ >> << forms/

javascript/

All Javascript needed for this script is placed in a single file in this directory name SimpleContactForm.js
Below you will find a description of each part of this file; this information is intended for anyone who wants to modify the script and is not needed for installation.

SimpleContactForm

All functionality is wrapped in a single class : SimpleContactForm. A new instance of this class is created for each form that is added to a page.
A new instance is automatically called by the script after any form is created. This class takes six parameters :

SimpleContactForm Properties

Property Attributes Description
form private Holds a reference to the form associated with this SimpleContactForm instance.
formData private An object with two properties :
fieldNames : An array containing the names of all fields that belong to this form.
fieldData : An array containing field validation rules for each item in the fieldNames array.
strings private An associative array containing all message strings used by this script. This array is built using the stringKeys and stringValues arrays given to this instance.

SimpleContactForm Functions

Function Attributes Description
addClass private static Adds a CSS class to an element without overriding existing classes.
  • element : A reference to an element.
  • className : The name of the class that will be added to the element.
addListener private static This utility function registers an event listener to the given element.
  • element : A reference to the element that the event listener will be registered to.
  • type : The name or type of the event, eg. 'mousedown', 'click', 'submit'
  • callback : A reference to the function that will be called when the event is triggered. The callback function can take a single argument event.
createElement private static Creates an HTML element of the specified type with the given attributes.
  • elementType : The tag type of the new element eg. 'div', 'a', 'h1'
  • attributes : A flat array of key value pairs describing the new element's attributes.
fieldGetInput private static Returns a SimpleContactForm.FieldResult object representing the field with the given name.
  • form : A reference to the form that holds the field.
  • fieldName : The name of the field look for inside of the given form.
getElementsByClass private static Returns all elements with a matching class attribute.
  • searchClass : The name of the class to filter elements by.
  • node : A reference to the element that will be searched. If no element is provided the entire document is searched.
removeClass private static Removes a CSS class from an element.
  • element : A reference to an element.
  • className : The name of the class that will be removed from the element.
removeListener private static This utility function removes an event listener from the given element.
  • element : A reference to the element that the event listener will be removed from.
  • type : The name or type of the event, eg. 'mousedown', 'click', 'submit'
  • callback : A reference to the function that is called when the event is triggered.
stopEvent private static This function cancels an events default behaviour.
  • event : A reference to the event that must be canceled.
stripHTML private static This function will strip all HTML tags from a string and compress all white space.
  • string : A string containing HTML that needs to be stripped.
trim private static Strips the whitespace from the beginning and end of a string
  • string : A string that needs to be trimmed.
validateEmail private static Performs a very simple check to validate an email's format.
This function cannot guarantee that the email exists.
  • email : A string containing the email that needs to be validated.
validateURL private static Performs a very simple check to validate a URL's format.
This function cannot guarantee that the URL exists.
  • url : A string containing the URL that needs to be validated.
SimpleContactForm private Creates a new SimpleContactForm instance.
  • formID : The HTML id of the form associated with this SimpleContactForm instance. This has to be a valid id of an HTML form element found on the web page.
  • stringKeys : All message generated by this script are stored in a string array to allow them to easily be edited in a single location (See SimpleContactForm.configuration.php for details). This would allow the script to be easily translated if needed.
    Each string is associated with a key or name; this array should contain in the correct order all string keys.
  • stringValues : This array should contain all string values in the correct order matching the stringKeys array.
    See SimpleContactForm.configuration.php for details.
  • fieldNames : This parameter should be an array of all field names as specified in the configuration (See SimpleContactForm.configuration.php for details).
  • fieldData : This should be an array of field options as specified in the configuration matching the fieldNames array.
  • fieldValidation : After a form is submitted this array is used to pass server side validation results to Javascript. The array should be in correct order matching fieldNames and fieldData. An item that is not empty or null will be marked is invaid.
getString private Returns a string from this script's string definitions.
  • name : The name of the string to return.
  • replacement : An array of replacement values. String may have placeholder values marked by <<n>> where n is any number 0, 1, 2, etc.
    See SimpleContactForm.configuration.php for details.
eventInputBlur private Called when the focus on a fields input is lost. Removes the CSS focus class and hides the validation error popup.
eventInputFocus private Called when the a fields input gains focus. Adds the CSS focus class and shows the validation error popup.
eventInputLimitAlphaNum private Called when a character is entered on a fields input and limits the range of characters allowed to only letters and numbers.
eventInputLimitNumbers private Called when a character is entered on a fields input and limits the range of characters allowed to only numbers.
eventRadioGroupSelect private Added to radio buttons. This function will remove validation errors associated with a radio group when one is selected.
eventRefreshVerificationImage private Added to the <a> tag when the form is created this function will reload the verification/captcha image. The form must have an <a> tag defined with the same id as the image element appended with '-refresh' eg. <a id="IMAGE_ID-refresh"></a>.
eventValidateForm private Called when the form is submitted. This will then call the validate function.
validate private This function is automatically called when the form is submitted. The form will only be submitted once all fields have been validated.

FieldResult

The FieldResult class wraps a fields input element. Used to transparently work with a single input (text field, text box, etc) or multiple input (radio groups etc.)

FieldResult Properties

Property Attributes Description
type public input, for a single element, or collection for a group of elements.
input public The element or elements associated with this field. This value can either be an element or an array. The type property of this field should match this.
value public This fields value, a string for a single element or an array for a collection.

FieldResult Functions

Function Attributes Description
addClass public Adds a CSS class to this result's input
  • className : The name of the class that will be added to this field's input.
addEventListeners public Adds event listeners to this result's input
  • listeners : An array of type, callback pairs to be added.
each public Calls a function for each input associated with this field
  • callback : This function takes the current element as a single parameter.
focus public Gives this field's input focus.
getInputType public Returns this inputs type (radio, checkbox etc.).
getNodeName public Returns this input's HTML nodeName.
isChecked public Returns the checked state of this input.
removeAttribute public Removes an attribute from this field's input.
  • name : param name The name of the attribute to remove.
removeClass public Removes a CSS class from this result's input.
  • className : The name of the class that will be removed from the element.
set public Updates this result instance.
  • type : The type of this result : input or collection.
    An input type means this field has only a single input element associated with it.
    The collection type means that this field has multiple inputs associated with it.
  • input : The input element, either an array of input or a single input element
  • value : TThe inputs value (either a string or an array).
setAttribute public Sets an attribute for this field's inputs.
  • name : The name of the attribute to modify.
  • value : The new value to be assigned to the attribute.

resources/ >> << forms/

SimpleContactForm