jFormer Documentation → Basic Fields →
Single Line Text
JFormComponentSingeLineText(String id, String label[, Array optionArray])
The Single Line Text field is a one line input field that accepts text. This form field is best used for short answer, free form questions such as, "What is your favorite animal?"
Almost all forms have a single line text component, so we put a lot of effort in making this component type as robust as possible.
Usage
Constructor
new JFormComponentSingleLineText(String id, String label[, Array optionArray])
Sample Usage
Create a simple single line text component with a tooltip:
$singleLineText = new JFormComponentSingleLineText('id', 'Label:', array(
'tip' => 'This is a tooltip on a single line text component.
',
));
Value Returned
String
CSS Class
.jFormComponentSingleLineText
Single Line Text Options
These options are specific to the JFormComponentSingleLineText object.
false
disabled
boolean | either true or false, which determines whether or not the input field is disabled. A disabled input element is unusable and un-clickable.
null
emptyValue
string | will be displayed in the input field until the user focus on it. If the user leaves the field empty and tabs away, the empty value will display again. Empty values are not passed to the server for processing.
false
enterSubmits
boolean| determines whether or not pressing the enter key while focused on the input field will submit the entire form.
null
initialValue
string | Receives a string which is set as the value of the input field when the form is created.
null
mask
string | Receives a mask string which forces users to enter input in a formatted way. This is very useful for things like phone numbers, dates, and social security numbers. A mask is defined by a format made up of mask literals and mask definitions. Any character not in the definitions list below is considered a mask literal. Mask literals will be automatically entered for the user as they type and will not be able to be removed by the user. The following mask definitions are predefined:
- a - Represents an alpha character (A-Z,a-z)
- 9 - Represents a numeric character (0-9)
- * - Represents an alphanumeric character (A-Z,a-z,0-9)
- Phone: '(999) 999-999'
- Date: '99/99/9999'
- SSN: '999-99-9999'
For more information, see the Masked Input Plugin page by digitalBush.
new JFormComponentSingleLineText('id', 'Label:', array(
'mask' => '(999) 999-999',
));
maxLength
null
integer | Receives a positive integer, which specifies the maximum length (in characters) of an input field.
readOnly
false
boolean | determines whether or not the input field is read only. A read only input element cannot be modified. However, a user can tab to it, highlight it, and copy the text from it.
sublabel
null
HTML string | Receives a string or HTML string which will appear directly beneath the input field. Sublabels are often used to give a short piece of additional information to the user indicating what they should enter.
type
'text'
string | Receives a string used to specify the type input field to display. If type is set to 'password', the user will see asterisks instead of characters when they type.
- 'text' - Characters are displayed as they are typed
- 'password' - Characters are masked as they are typed
width
null
Receives a string, like '20px' or '6em', which is set as the CSS width value on the input element. Alternatively, you may pass any of the following strings and they will translate to CSS em values.
- 'shortest' - 2em
- 'short' - 6em
- 'mediumShort' - 9em
- 'medium' - 12em
- 'mediumLong' - 15em
- 'long' - 18em
- 'longest' - 24em
Component Options
These options are common to all components.
null
description
HTML | a description for the component, shows underneath the component inside a DIV with the class jFormComponenpescription.
null
instanceOptions
Array, [max(int), addButtonText(string), removeButtonText(text)] | see instanceOptions page for more information.
null
dependencyOptions
Array, [dependentOn(string), display(string), jsFunction(Javascript)[, animationOptions(array)]] | see dependencyOptions page for more information.
null
tip
HTML | a tooltip that displays whenever the component has focus. Gives any extra help or explanation a form user might need.
null
validationOptions
Array | an of validations specific to the component, see the specific component for its validations.
false
showErrorTipOnce
Boolean | this option makes the error tip only show up on the first focus on the component if it does not pass validation.
false
enterSubmits
Boolean | if true pressing enter while this component has focus submits the form, or advances to the next page.
null
style
CSS | set the style attribute for the component wrapper div.
null
initialValue
String | preset the value of the component upon form loading.
Options Examples
- Demo
- View Source
Single Line Text Validation Options
| Name | Error Message and Description |
| alpha |
"Must only contain letters." Numbers, white space, and special characters are not allowed. |
| alphaDecimal |
"Must only contain letters, numbers, or periods." White space and special characters are not allowed. |
| alphaNumeric |
"Must only contain letters or numbers." White space and special characters are not allowed. |
| blank |
"Must be blank." |
| canadianPostal |
"Must be a valid Canadian postal code." |
| date |
"Must be a date in the mm/dd/yyyy format." |
| dateTime |
"Must be a date in the mm/dd/yyyy hh:mm:ss tt format. ss and tt are optional." |
| decimal |
"Must be a number without any commas. Decimal is optional." |
| decimalNegative |
"Must be a negative number without any commas. Decimal is optional." |
| decimalPositive |
"Must be a positive number without any commas. Decimal is optional." |
| decimalZeroNegative |
"Must be zero or a negative number without any commas. Decimal is optional." |
| decimalZeroPositive |
"Must be zero or a positive number without any commas. Decimal is optional." |
|
"Must be a valid e-mail address." |
|
| integer |
"Must be a whole number." |
| integerNegative |
"Must be a negative whole number." |
| integerPositive |
"Must be a positive whole number." |
| integerZeroNegative |
"Must be zero or a negative whole number." |
| integerZeroPositive |
"Must be zero or a positive whole number." |
| isbn |
"Must be a valid ISBN and consist of either ten or thirteen characters." |
| length |
"Must be exactly x characters long. Current value is y characters."
'validationOptions' => array('length' => 5)
|
| matches |
"Does not match." The 'matches' validation traditionally receives the HTML ID (without the #) of the particular field that you wish to match a value against.
'validationOptions' => array('matches' => 'password'),
In some cases, you may wish to use 'matches' in a setting where there can be more than one instance of a section that contains both the original field and the field you want to match against. In this case, 'matches' must be assigned to an associate array that contains two keys. The first key, 'matches' receives an HTML ID (without the #) of the particular field that you wish to match a value against. The second key, 'sectionInstances' receives a boolean indicating whether or not the value you want to match against is a member of a section that can have more than one instance. For example:
'validationOptions' => array(
'matches' => array(
'matches' => 'password',
'sectionInstances' => true
)
),
|
| maxLength |
"Must be less than x characters long. Current value is y characters."
'validationOptions' => array('maxLength' => 10),
|
| maxFloat |
"Must be numeric and cannot have more than x decimal place(s)."
'validationOptions' => array('maxFloat' => 2),
|
| minLength |
"Must be at least x characters long. Current value is y characters."
'validationOptions' => array('minLength' => 10),
|
| money |
"Must be a valid dollar value." |
| moneyNegative |
"Must be a valid negative dollar value." |
| moneyPositive |
"Must be a valid positive dollar value." |
| moneyZeroNegative |
"Must be zero or a valid negative dollar value." |
| moneyZeroPositive |
"Must be zero or a valid positive dollar value." |
| password |
"Must be between 4 and 32 characters." |
| phone |
"Must be a 10 digit phone number." |
| postalZip |
"Must be a valid United States zip code, Canadian postal code, or United Kingdom postal code." |
| required |
"Required." Makes the component required, the entered value may not be white space or empty. |
| serverSide |
"There was an error during server side validation: errorThrown" The server side validation option performs a client side server side check using AJAX. This is useful for making sure usernames are available before the user submits an entire registration form. Here's an example structure of the validation option:
'validationOptions' => array(
'serverSide' => array(
'url' => 'http://www.domain.com/checkuser.php',
'task' => 'checkUsernameAvailability',
),
),
The 'url' key is the location of the resource containing the value checking logic. The 'task' key is a POST key sent that may be used to assist with the value checking logic. Everytime a user changes the field that has a server side validation, an AJAX request will be sent to the specified URL with two POST keys, 'task' and 'value'. 'value' will be what the user has entered in the single line text field. Also, while a client side server side check is in process, the component will receive the class 'jFormComponentServerSideCheck'. The error message is custom set by the server's response. The server must output a JSON response in this format in order to be processed successfully:
{
"status": "failure",
"response": ["There was a problem with server side validation."]
}
"status" must be set to either "failure" (validation failed) or "success" (validation passed). "response" must be an array with one or more error message strings. These will appear in the error list if validation fails. This validation will at minimum be performed two times, once when the user enters the field intially, and again when the server processes the entire form. The second check is performed with a server side web scrape using the cURL PHP library. |
| ssn |
"Must be a valid United States social security number." |
| teenager |
"Must be at least 13 years old." |
| time |
"Must be a time in the hh:mm:ss tt format. ss and tt are optional." |
| ukPostal |
"Must be a valid United Kingdom postal code." |
| url |
"Must be a valid Internet address." |
| username |
"Must use 4 to 32 characters and start with a letter." |
| zip |
"Must be a valid United States zip code." |
Validation Examples
- Demo
- View Source
Next Page: Text Area
This page was last edited on April 25, 2011 at 10:51am.
12 comments (add a comment)
First, thanks for making this framework.
Is there a way to set validation options like 'alphaNumeric space' so any special chars are excluded to prevent sql injection.
shawn a on 2012-01-19 13:27:55
length validation doesn't work. It throws invalid object errors.
'length' is a reserved name and the js is not using safe object names.
Probably should all be _length etc.
quick fix for length validation type, changed function and validation to 'thelength'
'length' : function(options) {
var errorMessageArray = ['Must be exactly ' options.length ' characters long. Current value is ' options.value.length ' characters.'];
return options.value == '' || options.value.length == options.length ? 'success' : errorMessageArray;
},
'thelength' : function(options) {
var errorMessageArray = ['Must be exactly ' options.thelength ' characters long. Current value is ' options.value.length ' characters.'];
return options.value == '' || options.value.length == options.thelength ? 'success' : errorMessageArray;
},
shawn a on 2012-01-19 13:42:49
isbn js validation is bugged
here is a fixed js function
'isbn': function(options) {
//Match an ISBN
var errorMessageArray = ['Must be a valid ISBN and consist of either ten or thirteen characters.'];
var success = false;
//For ISBN-10
if(options.value.match(/^(?=.{13}$)\d{1,5}([\- ])\d{1,7}\1\d{1,6}\1(\d|X)$/)) {
success = true;
}
if(options.value.match(/^\d{9}(\d|X)$/)) {
success = true;
}
//For ISBN-13
if(options.value.match(/^(?=.{17}$)\d{3}([\- ])\d{1,5}\1\d{1,7}\1\d{1,6}\1(\d|X)$/)) {
success = true;
}
if(options.value.match(/^\d{3}[\- ]\d{9}(\d|X)$/)) {
success = true;
}
//ISBN-13 without starting delimiter (Not a valid ISBN but less strict validation was requested)
if(options.value.match(/^\d{12}(\d|X)$/)) {
success = true;
}
return success ? 'success' : errorMessageArray;
},
shawn a on 2012-01-19 13:49:39
Sorry that last line above should have been.
return options.value == '' || success ? 'success' : errorMessageArray;
shawn a on 2012-01-20 06:20:20
Im not going to post any more full fixes, but the following are also bugged in the JS, and i imagine in the server side validations also.
teenager - both js functions, errors are, msg is a string not array, vars do not have var scope declarations and lines are comma terminated not semi colon.
postalzip - missing options argument at "this.ukPostal(options)"
decimalZeroNegative - isDecimal evaluation is wrong
Casual User on 2012-01-27 15:22:41
Is there a way to get multiple fields on one line other than using the Name form?
Would be nice to see ACTUAL PHP file. I am not able to display the 'initialValue' of a single line text field. That's all I have on the form. After nearly 25 minutes trying to figure out why the initialValue is not being displayed, I am still clueless.
If a single line text component id is set as "title", the "initialValue" will be ignored!
Example:
new JFormComponentSingleLineText('title', 'Title:', array('initialValue' => 'Star Wars',))
In the above example, nothing will be displayed in the text field. However, if you change the ID of the field from 'title' to anything else, it works.
Guillaumehug on 2012-02-04 06:12:43
Hello,
how can we edit the error messages ??
I don't know for example how to change the default message for 'required'.
Thansk !!
HI,
Great Framework, however when I use the serverSide validation option, I have an error during submission processing.
Error : "Class Network does not exist...."
error at line 3995 (jformer.php).
jformer.php calls a "getUrlContent" function from the class "Network". I don't know if I need to install a PHP extension or something else... It seems to be related to cURL and php5-curl is installed on my server.
can Someone help me ?
Thnak you.
phillip on 2012-05-02 13:12:21
I'm also having trouble with serverSide validation...
If my serverSide validation script returns "failure" with an error response, jFormer processes the error correctly.
But if the script returns "success", jFormer handles it ok on the field validation, but hangs during form submission. It gives the "processing..." message and never ends.
I've tried just hardcoding the serverSide scription to
echo json_encode(array(
"status" => "success",
));
and get the same result - field validation OK, but form submission hangs.
Has ANYONE gotten serverSide validation to work? I'd hate to have to start over just because I cant get this piece to work, but it's critical for my project.
Thank you
@philip and @davy since the class Network is missing you have to create your own Network class, which will get file contents from the requested url. I created my own Network class used curl to get content and it's working :)