seahorse-1.2.js | |
About Seahorse | |
Introduction | Seahorse is an open source JavaScript library created for simplify the use of forms, particularly the form validation. |
License | This library is licensed under the LGPL Version 3 license. |
Validation behaviors | One of the main features of this library are the functions to assign validation behaviors to the inputs. |
Validation options | The validation options are parameters that restrict the values, or the format, that the data of an input can have to be considered valid. |
Response options | The response options are parameters that determines the courses of actions when an user enter a valid or invalid input. |
Functions | |
Validation behaviors | |
text() | Gives to an element a text input behavior. |
alphabetical() | Gives to an element an alphabetical input behavior. |
alphanumeric() | Gives to an element an alphanumeric input behavior. |
numeric() | Gives to an element a numeric input behavior. |
number() | Gives to an element a float input behavior. |
integer() | Gives to an element an integer input behavior. |
date() | Gives to an element a date input behavior. |
time() | Gives to an element a time input behavior. |
ipAddress() | Gives to an element an IP address input behavior. |
email() | Gives to an element an e-mail address input behavior. |
http() | Gives to an element a HTTP address input behavior. |
ftp() | Gives to an element a FTP address input behavior. |
form() | Gives to an element a form behavior. |
removeBehavior() | Removes, from a element, any behavior asigned by a function of the Seahorse’s library. |
Validation functions | |
isNumber() | Checks if a string represents a number. |
isInteger() | Checks if a string represents an integer. |
isNumeric() | Checks if a string contains only numbers. |
isAlphabetical() | Checks if a string contains only alphabetical characters (including accents and another not Ascii characters). |
isAlphanumeric() | Checks if a string contains only alphanumeric characters. |
isAlphabeticalAscii() | Checks if a string contains only alphabetical ASCII characters. |
isAlphanumericAscii() | Checks if a string contains only alphanumeric ASCII characters. |
isAsciiText() | Checks if a string contains only ASCII characters. |
isIPv4() | Checks if a string represents an IP version 4 address. |
isIPv6() | Checks if a string represents an IP version 6 address. |
isEmail() | Checks if a string represents an e-mail address. |
isHttp() | Checks if a string represents a HTTP address. |
isFtp() | Checks if a string represents a FTP address. |
isMonth() | Checks if a string represents a month. |
isDay() | Checks if a string represents a day of a particular month. |
isDate() | Checks if string represents a date. |
isTime() | Checks if string represents an instant of time. |
isDateFormat() | Checks if string is a valid date format. |
isTimeFormat() | Checks if string is a valid time format. |
validateForm() | Checks if all the elements of a form have valid values. |
passFilter() | Acording to the value of ‘contains’, checks if all the characters of ‘cad’ are contained in ‘filter’ or if neither of the characters are contained. |
Parsing functions | |
parseNumber() | Parses a string and returns an number. |
parseInteger() | Parses a string and returns a integer. |
parseIPv4() | Parses a string that represents an IPv4 address and returns a array with four numbers. |
parseIPv6() | Parses a string that represents an IPv6 address and returns a array with eight hexadecimal numbers. |
parseDate() | Receives a string representing a date and transforms it according to the format passed as parameter. |
parseTime() | Receives a string representing an instant of time and transforms it according to the format passed as parameter. |
filterString() | Returns all the characters of ‘cad’ that are contained, or that aren’t contained, in ‘filter’. |
Others | |
compareDate() | Compare two strings that represents dates. |
compareTime() | Compare two strings that represents times. |
serialize() | Encode the elements of a form as a string. |
Seahorse is an open source JavaScript library created for simplify the use of forms, particularly the form validation.
It provides functions to validate, parse and serialize data and to add real-time validation to inputs.
Seahorse can be used alone or it can be used with jQuery, using the plugin designed for that purpose.
One of the main features of this library are the functions to assign validation behaviors to the inputs.
An input with a validation behavior can avoid the input of invalid characters or perform diferent actions (like add a CSS class to a element or invoke a JavaScript function) when a user inserts valid or invalid data.
The validation behaviors functions receives as parameter the id of the element to be validated, a JSON element with the validation options and a JSON element with the response options.
The validation options are parameters that restrict the values, or the format, that the data of an input can have to be considered valid.
The variables that can be defined in the JSON element of validation options are
notEmpty | A boolean indicating if the field can be left in blank. |
minLength | The minimum length of a text input (by default, 0). |
maxLength | The maximun length of a text input (by default, infinity). |
minValue | The minimum value of a input (by default, minus infinity for numbers and null for dates and times). |
maxValue | The maximun value of a input (by default, infinity for numbers and null for dates and times). |
format | The format of a input (by default ‘yyyy-mm-dd’ for dates and ‘hh:mm:ss’ for times). |
autofill | A boolean indicating if the incomplete fields of dates or times must be completed with the actual date or time. |
version | The version of an IP address input (by default, 4). |
requiredCharacters | A string or a array of unicode values representing the group of characters that a text input must have to be considered valid. |
forbiddenCharacters | A string or a array of unicode values representing the group of characters that a text input must not have to be considered valid. |
allowedCharacters | A string or a array of unicode values representing the group of characters that a text input can have and be considered valid, no matter the restrictions of his type. |
asciiCharacters | A boolean indicating if a text input must have only ASCII characters (by default ‘false’). |
decimalCharacter | The character used as decimal character in a numeric input (by default ‘.’). |
groupingCharacter | The character used as grouping character in a numeric input (by default ‘,’). |
aditionalValidation | A user’s defined function that test if a field has a valid value. This function is called only if the field has been validated by the standard Seahorse’s validation function. |
This variables are optionals and they are not used by all the functions, each function uses only a few variables, for example, for restrict the lenght, text() uses minLength and maxLength while number() uses minValue and maxValue.
The response options are parameters that determines the courses of actions when an user enter a valid or invalid input.
The variables that can be defined in the JSON element of response options are
errorClass | The class added to the input if the data entered is invalid. |
okClass | The class added to the input if the data entered is valid. |
targetErrorClass | The class added to a given element if the data entered is invalid. |
targetOkClass | The class added to a given element if the data entered is valid. |
targetId | The id of the element to which add the classes ‘targetErrorClass’ or ‘targetOkClass’. |
hiddenElementId | The id of the element to hide or show, depending if the data entered is valid or invalid. |
callbackFunction | A function to invoke after that the input was validated. The function must receive two parameters: ‘element’ (the object that represents the input) and ‘valid’ (a boolean indicating if the data entered is valid or not). |
forbidEntrance | A boolean indicating if the entrance of invalid characters must be forbidden (by default, ‘true’). |
autoparse | A boolean indicating if the data in the fields must be parsed in order to eliminate unnecessary characters. |
errorMessage | A message explaining why the value of the input is invalid. |
This variables are optionals and can be specified for all the validation functions.
Validation behaviors | |
text() | Gives to an element a text input behavior. |
alphabetical() | Gives to an element an alphabetical input behavior. |
alphanumeric() | Gives to an element an alphanumeric input behavior. |
numeric() | Gives to an element a numeric input behavior. |
number() | Gives to an element a float input behavior. |
integer() | Gives to an element an integer input behavior. |
date() | Gives to an element a date input behavior. |
time() | Gives to an element a time input behavior. |
ipAddress() | Gives to an element an IP address input behavior. |
email() | Gives to an element an e-mail address input behavior. |
http() | Gives to an element a HTTP address input behavior. |
ftp() | Gives to an element a FTP address input behavior. |
form() | Gives to an element a form behavior. |
removeBehavior() | Removes, from a element, any behavior asigned by a function of the Seahorse’s library. |
Validation functions | |
isNumber() | Checks if a string represents a number. |
isInteger() | Checks if a string represents an integer. |
isNumeric() | Checks if a string contains only numbers. |
isAlphabetical() | Checks if a string contains only alphabetical characters (including accents and another not Ascii characters). |
isAlphanumeric() | Checks if a string contains only alphanumeric characters. |
isAlphabeticalAscii() | Checks if a string contains only alphabetical ASCII characters. |
isAlphanumericAscii() | Checks if a string contains only alphanumeric ASCII characters. |
isAsciiText() | Checks if a string contains only ASCII characters. |
isIPv4() | Checks if a string represents an IP version 4 address. |
isIPv6() | Checks if a string represents an IP version 6 address. |
isEmail() | Checks if a string represents an e-mail address. |
isHttp() | Checks if a string represents a HTTP address. |
isFtp() | Checks if a string represents a FTP address. |
isMonth() | Checks if a string represents a month. |
isDay() | Checks if a string represents a day of a particular month. |
isDate() | Checks if string represents a date. |
isTime() | Checks if string represents an instant of time. |
isDateFormat() | Checks if string is a valid date format. |
isTimeFormat() | Checks if string is a valid time format. |
validateForm() | Checks if all the elements of a form have valid values. |
passFilter() | Acording to the value of ‘contains’, checks if all the characters of ‘cad’ are contained in ‘filter’ or if neither of the characters are contained. |
Parsing functions | |
parseNumber() | Parses a string and returns an number. |
parseInteger() | Parses a string and returns a integer. |
parseIPv4() | Parses a string that represents an IPv4 address and returns a array with four numbers. |
parseIPv6() | Parses a string that represents an IPv6 address and returns a array with eight hexadecimal numbers. |
parseDate() | Receives a string representing a date and transforms it according to the format passed as parameter. |
parseTime() | Receives a string representing an instant of time and transforms it according to the format passed as parameter. |
filterString() | Returns all the characters of ‘cad’ that are contained, or that aren’t contained, in ‘filter’. |
Others | |
compareDate() | Compare two strings that represents dates. |
compareTime() | Compare two strings that represents times. |
serialize() | Encode the elements of a form as a string. |
text : function( element, validationOptions, responseOptions )
Gives to an element a text input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minLength, maxLength, asciiCharacters, allowedCharacters, requiredCharacters and forbiddenCharacters). |
responseOptions | A JSON element with the response options. |
alphabetical : function( element, validationOptions, responseOptions )
Gives to an element an alphabetical input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minLength, maxLength, asciiCharacters, allowedCharacters, requiredCharacters and forbiddenCharacters). |
responseOptions | A JSON element with the response options. |
alphanumeric : function( element, validationOptions, responseOptions )
Gives to an element an alphanumeric input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minLength, maxLength, asciiCharacters, allowedCharacters, requiredCharacters and forbiddenCharacters). |
responseOptions | A JSON element with the response options. |
numeric : function( element, validationOptions, responseOptions )
Gives to an element a numeric input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minLength, maxLength, asciiCharacters, allowedCharacters, requiredCharacters and forbiddenCharacters). |
responseOptions | A JSON element with the response options. |
number : function( element, validationOptions, responseOptions )
Gives to an element a float input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minValue, maxValue, groupingCharacter and decimalCharacter). |
responseOptions | A JSON element with the response options. |
integer : function( element, validationOptions, responseOptions )
Gives to an element an integer input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minValue, maxValue and groupingCharacter). |
responseOptions | A JSON element with the response options. |
date : function( element, validationOptions, responseOptions )
Gives to an element a date input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minValue, maxValue, autofill and format). |
responseOptions | A JSON element with the response options. |
time : function( element, validationOptions, responseOptions )
Gives to an element a time input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation, minValue, maxValue, autofill and format). |
responseOptions | A JSON element with the response options. |
ipAddress : function( element, validationOptions, responseOptions )
Gives to an element an IP address input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty, aditionalValidation and version). |
responseOptions | A JSON element with the response options. |
email : function( element, validationOptions, responseOptions )
Gives to an element an e-mail address input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty and aditionalValidation). |
responseOptions | A JSON element with the response options. |
http : function( element, validationOptions, responseOptions )
Gives to an element a HTTP address input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty and aditionalValidation). |
responseOptions | A JSON element with the response options. |
ftp : function( element, validationOptions, responseOptions )
Gives to an element a FTP address input behavior.
element | The element id or the element object. |
validationOptions | A JSON element with the validation options (notEmpty and aditionalValidation). |
responseOptions | A JSON element with the response options. |
form : function( form, responseFunction, errorMessage )
Gives to an element a form behavior.
That means that it modifies the submit method of the form in order to validate all the inputs before submit.
The ‘responseFunction’ parameter is the function called when the form is submited but one or more inputs, of the form, has invalid values. This function must receive two parameters: a string with the error messages of the form and the inputs and an array with all the input elements that have invalid values.
form | The form id or the form object. |
responseFunction | The function called if one of more inputs of the form are invalid. |
errorMessage | The message to be displayed if one of more inputs of the form are invalid. |
isMonth : function( mes )
Checks if a string represents a month. This function considers that a month is a number that must be between 1 and 12 (while the class Date considers a month like a number between 0 and 11).
mes | A string. |
true if the string represents a month and false in the opposite case.
isDay : function( dia, mes, anio )
Checks if a string represents a day of a particular month. This function considers that a month is a number that must be between 1 and 12 (while the class Date considers a month like a number between 0 and 11).
dia | A string that represents a day. |
mes | A string that represents a month. |
anio | A string that represents a year. |
true if ‘dia’ represents a day of the month ‘mes’ and false in the opposite case or if ‘mes’ it’s not a month.
isDate : function( cad, format, fill )
Checks if string represents a date.
cad | A string that represents a date. |
format | A string that represents a date format. |
fill | A boolean that indicates if the empty fields have to be completed with the actual date. |
true if the string represents a date and false in the oposite case.
isTime : function( cad, format, fill )
Checks if string represents an instant of time.
cad | A string that represents an instant of time. |
format | A string that represents a time format. |
fill | A boolean that indicates if the empty fields have to be completed with the actual time. |
true if the string represents an instant of time and false in the oposite case.
passFilter : function( cad, filter, contains )
Acording to the value of ‘contains’, checks if all the characters of ‘cad’ are contained in ‘filter’ or if neither of the characters are contained.
cad | A string to filter. |
filter | A string used as filter. |
contains | A boolean indicating the mode of operation. |
true if all the characters of ‘cad’ are contained in ‘filter’ and false in the oposite case. true if neither of the characters of ‘cad’ are contained in ‘filter’ and false in the oposite case.
parseDate : function( cad, format, fill )
Receives a string representing a date and transforms it according to the format passed as parameter.
cad | A string that represents a date. |
format | A string that represents a valid date format. |
fill | A boolean that indicates if the empty fields have to be completed with the actual date. |
A formated string that represents a date if ‘cad’ represents a date and ‘format’ is a valid date format or null in the oposite case.
parseTime : function( cad, format, fill )
Receives a string representing an instant of time and transforms it according to the format passed as parameter.
cad | A string that represents an instant of time. |
format | A string that represents a valid time format. |
fill | A boolean that indicates if the empty fields have to be completed with the actual time. |
A formated string that represents an instant of time if ‘cad’ represents an instant of time and ‘format’ is a valid time format or null in the oposite case.
filterString : function( cad, filter, contains )
Returns all the characters of ‘cad’ that are contained, or that aren’t contained, in ‘filter’.
cad | A string to filter. |
filter | A string used as filter. |
contains | A boolean indicating the mode of operation. |
All the characters of ‘cad’ that are contained in ‘filter’, if ‘contains’ is equal to true. All the characters of ‘cad’ that aren’t contained in ‘filter’, if ‘contains’ is equal to false.
compareDate : function( date1, date2, dateFormat )
Compare two strings that represents dates.
date1 | The first date. |
date2 | The second date. |
dateFormat | The date format of the two dates. |
A negative number if date1 < date2, a positive number if date1 > date2, zero if date1 = date2 or null in case of error.
compareTime : function( time1, time2, timeFormat )
Compare two strings that represents times.
time1 | The first time. |
time2 | The second time. |
timeFormat | The date format of the two times. |
A negative number if time1 < time2, a positive number if time1 > time2, zero if time1 = time2 or null in case of error.
Gives to an element a text input behavior.
text : function( element, validationOptions, responseOptions )
Gives to an element an alphabetical input behavior.
alphabetical : function( element, validationOptions, responseOptions )
Gives to an element an alphanumeric input behavior.
alphanumeric : function( element, validationOptions, responseOptions )
Gives to an element a numeric input behavior.
numeric : function( element, validationOptions, responseOptions )
Gives to an element a float input behavior.
number : function( element, validationOptions, responseOptions )
Gives to an element an integer input behavior.
integer : function( element, validationOptions, responseOptions )
Gives to an element a date input behavior.
date : function( element, validationOptions, responseOptions )
Gives to an element a time input behavior.
time : function( element, validationOptions, responseOptions )
Gives to an element an IP address input behavior.
ipAddress : function( element, validationOptions, responseOptions )
Gives to an element an e-mail address input behavior.
email : function( element, validationOptions, responseOptions )
Gives to an element a HTTP address input behavior.
http : function( element, validationOptions, responseOptions )
Gives to an element a FTP address input behavior.
ftp : function( element, validationOptions, responseOptions )
Gives to an element a form behavior.
form : function( form, responseFunction, errorMessage )
Removes, from a element, any behavior asigned by a function of the Seahorse’s library.
removeBehavior : function( element )
Checks if a string represents a number.
isNumber : function( cad, ds, gs )
Checks if a string represents an integer.
isInteger : function( cad, gs )
Checks if a string contains only numbers.
isNumeric : function( cad )
Checks if a string contains only alphabetical characters (including accents and another not Ascii characters).
isAlphabetical : function( cad )
Checks if a string contains only alphanumeric characters.
isAlphanumeric : function( cad )
Checks if a string contains only alphabetical ASCII characters.
isAlphabeticalAscii : function( cad )
Checks if a string contains only alphanumeric ASCII characters.
isAlphanumericAscii : function( cad )
Checks if a string contains only ASCII characters.
isAsciiText : function( cad )
Checks if a string represents an IP version 4 address.
isIPv4 : function( ip )
Checks if a string represents an IP version 6 address.
isIPv6 : function( ip )
Checks if a string represents an e-mail address.
isEmail : function( )
Checks if a string represents a HTTP address.
isHttp : function( http )
Checks if a string represents a FTP address.
isFtp : function( ftp )
Checks if a string represents a month.
isMonth : function( mes )
Checks if a string represents a day of a particular month.
isDay : function( dia, mes, anio )
Checks if string represents a date.
isDate : function( cad, format, fill )
Checks if string represents an instant of time.
isTime : function( cad, format, fill )
Checks if string is a valid date format.
isDateFormat : function( format )
Checks if string is a valid time format.
isTimeFormat : function( format )
Checks if all the elements of a form have valid values.
validateForm : function( idForm )
Acording to the value of ‘contains’, checks if all the characters of ‘cad’ are contained in ‘filter’ or if neither of the characters are contained.
passFilter : function( cad, filter, contains )
Parses a string and returns an number.
parseNumber : function( cad, ds, gs )
Parses a string and returns a integer.
parseInteger : function( cad, gs )
Parses a string that represents an IPv4 address and returns a array with four numbers.
parseIPv4 : function( ip )
Parses a string that represents an IPv6 address and returns a array with eight hexadecimal numbers.
parseIPv6 : function( ip )
Receives a string representing a date and transforms it according to the format passed as parameter.
parseDate : function( cad, format, fill )
Receives a string representing an instant of time and transforms it according to the format passed as parameter.
parseTime : function( cad, format, fill )
Returns all the characters of ‘cad’ that are contained, or that aren’t contained, in ‘filter’.
filterString : function( cad, filter, contains )
Compare two strings that represents dates.
compareDate : function( date1, date2, dateFormat )
Compare two strings that represents times.
compareTime : function( time1, time2, timeFormat )
Encode the elements of a form as a string.
serialize : function( form, notation )