Methods

This document contains a list of Formr's public methods, grouped by functionality


Inputs

input_text()

Lets you generate a standard text input field.

  1. The first parameter contains the field’s name and is required.
  2. The second parameter optionally contains the field’s label text.
  3. The third parameter optionally contains a default value.
  4. The fourth parameter optionally contains the field’s ID.
  5. The fifth parameter optionally contains a string, which lets you add CSS, JavaScript, etc.
  6. The sixth parameter optionally utilizes Bootstrap’s .help-block block-level text.


Adding text to the second parameter will automatically create a <label> element in front of the <input> element. If you'd rather create the label yourself, leave the second parameter empty.

Example: Create a basic text input

echo $form->input_text('fname');

// will produce
<input type="text" name="fname" id="fname">

Example: Create an input with a label

echo $form->input_text('fname','First name:','John','fname','placeholder="first name:"');

// will produce
<label for="fname">First name:</label> 
<input type="text" name="fname" id="fname" value="John" placeholder="first name:">

Example: Create an input with an associative array

$data = array(
    'name'      => 'fname',
    'id'        => 'fname',
    'value'     => 'John',
    'maxlength' => '30',
    'class'     => 'input_field'
);

echo $form->input_text($data);

// will produce
<input name="fname" id="fname" value="John" maxlength="30" class="input_field" type="text">

Example: adding Bootstrap’s .help-block class

// use Bootstrap as our wrapper
$form = new Formr('bootstrap');

$data = array(
    'name'      => 'fname',
    'id'        => 'fname',
    'value'     => 'John',
    'maxlength' => '30',
    'string'    => 'class="input_field"',
    'inline'    => 'please enter your name'
);

echo $form->input_text($data);

// will produce
<div id="_fname" class="form-group">
	<input name="fname" id="fname" value="John" maxlength="30" type="text"class="form-control input_field">
	<p class="help-block">please enter your name</p>
</div>
You can also specify if you want the .help-block text to show only when there's a form error on that field by wrapping the string with square brackets [ ]

Input Arrays

Formr allows for you to create arrays with text (and file) fields, however, you must provide an unique array key for each field that exactly matches that field’s ID, otherwise Formr will not know which field to re-populate if there’s a POST error.

// the fname key in the first parameter matches the fname ID in the fourth
echo $form->input_text('names[fname]','First name','','fname');

// the mname key in the first parameter matches the mname ID in the fourth
echo $form->input_text('names[mname]','Middle name','','mname');

// the lname key in the first parameter matches the lname ID in the fourth
echo $form->input_text('names[lname]','Last name','','lname');

input_checkbox()

Lets you generate a checkbox element. The parameters are identical to input_text() except you may now utilize the seventh parameter - which is optional - and determines if a checkbox/radio should be ticked by default.

  1. The first parameter contains the field’s name and is required.
  2. The second parameter optionally contains the field’s label text.
  3. The third parameter optionally contains a default value.
  4. The fourth parameter optionally contains the field’s ID.
  5. The fifth parameter optionally contains a string, which lets you add CSS, JavaScript, etc.
  6. The sixth parameter optionally contains the field’s inline-help text.
  7. The seventh parameter optionally tells Formr if a checkbox/radio should be ticked.

Example: create a standard checkbox

echo $form->input_checkbox('agree','I Agree','agree','agreeID');

// will produce
<label for="agree">
	<input type="checkbox" name="agree" id="agreeID" value="agree">I Agree
</label>

Example: tick a checkbox on initial page load

echo $form->input_checkbox('agree','I Agree','agree','agree','','','checked');

// will produce
<label for="agree">
	<input checked="checked" type="checkbox" name="agree" id="agree" value="agree">I Agree
</label>
Notice how the <label> tag is also wrapped around the checkbox element, and the label's for attribute contains the element's ID.
Also, notice how in the seventh parameter we used the string 'checked' instead of the boolean TRUE? This is because anything in that parameter will return TRUE, even if it's an incorrect value. Therefore we must either use the string 'checked' or the string 'selected' to tell Formr we want this element selected on form load.

Example: tick a checkbox using a variable

$favorite_fruit = 'bananas';

echo $form->input_checkbox('bananas','','bananas','','','',$favorite_fruit);

// will produce
<input checked="checked" type="checkbox" name="bananas" id="bananas" value="bananas">

input_checkbox_inline()

Identical to input_checkbox() but adds the Bootstrap .checkbox-inline class to the label element.

Tip: If you don’t want bold label text, just add the following to your CSS.

.checkbox-inline label {
	font-weight: normal;
}

input_file()

This method is identical in all respects to the input_text() method except it sets the input type to file, allowing it to be used to upload files. Check out the Uploading Files docs for more info.

input_hidden()

Allows you to generate hidden input fields.

Example: submit a key/value pair to create a single hidden element

echo $form->input_hidden('fname','John');

// will produce
<input type="hidden" name="fname" id="fname" value="John">

Example: submit an associative array to create multiple hidden elements

$data = array(
    'name'  => 'John Doh',
    'email' => 'john@mysite.com',
    'url'   => 'http://mysite.com'
);

echo $form->input_hidden($data);

// will produce
<input type="hidden" name="name" id="name" value="John Doh">
<input type="hidden" name="email" id="email" value="john@mysite.com">
<input type="hidden" name="url" id="url" value="http://mysite.com">

input_image()

Identical to input_text() except that it creates an <input type="image"> element.

input_password()

Identical to the input_text() method except it creates a password field type.

input_radio()

Identical to input_checkbox() but produces a radio element.

input_radio_inline()

Identical to input_radio() but adds the Bootstrap .radio-inline class to the label element.

input_select()

Lets you create a standard <select>, or drop-down menu. The parameters are identical to the input_text() method, except that input_select() accepts a required eighth parameter which contains all of the options for the drop-down.

The eighth parameter contains a list of options and is required.
You may also pass an array of multiple items through the eighth parameter and Formr will create a multiple select for you.

Example: using an array to create a drop-down menu

// put our options into an array
$options = array(
    'cat'    => 'The Cat in the Hat',
    'lorax'  => 'The Lorax',
    'yertle' => 'Yertle the Turtle',
    'grinch' => 'The Grinch Who Stole Christmas',
);

// print the array
// notice that the 7th parameter is a default (selected) option
// notice that the 8th parameter is our list of options
echo $form->input_select('books', 'Books','','','','','yertle',$options);

// will produce
<label for="books">Books</label> 
<select name="books" id="books" >
	<option value="cat">The Cat in the Hat</option>
	<option value="lorax">The Lorax</option>
	<option value="yertle" selected="selected">Yertle the Turtle</option>
	<option value="grinch">The Grinch Who Stole Christmas</option>
</select>
Instead of selecting a value from our $options array we can insert a string, and if a match isn’t available in our $options array then an empty <option> will be created instead
echo $form->input_select('books', 'Books','','','','','Select a book',$options);

// will produce
<label for="books">Books</label> 
<select name="books" id="books" >
	<option value="">Select a book</option>
	<option value="cat">The Cat in the Hat</option>
	<option value="lorax">The Lorax</option>
	<option value="yertle">Yertle the Turtle</option>
	<option value="grinch">The Grinch Who Stole Christmas</option>
</select>

Example: selecting multiple options

$options = array(
    'cat'    => 'The Cat in the Hat',
    'lorax'  => 'The Lorax',
    'yertle' => 'Yertle the Turtle',
    'grinch' => 'The Grinch Who Stole Christmas',
);

$featured_books = array('cat', 'yertle');

echo $form->input_select('books', 'Books','','','','',$featured_books,$options);

// will produce
<label for="books">Books</label> 
<select name="books" multiple="multiple" id="books" >
	<option value="cat" selected="selected">The Cat in the Hat</option>
	<option value="lorax">The Lorax</option>
	<option value="yertle" selected="selected">Yertle the Turtle</option>
	<option value="grinch">The Grinch Who Stole Christmas</option>
</select>
If the array passed as $options is a multidimensional array, input_select() will produce an <optgroup> with the array key as the label.

input_select() has a little trick up its sleeve: if you pass a string as the second parameter (instead of an array) it will look for the corresponding method name in the class.formr.dropdowns.php file. For instance, if you enter “state” it will automatically produce a menu containing all 50 US states. The other two methods that are included in the class are countries, which will produce a menu containing all of the countries in the world, and provinces, which will create a menu of all Canadian provinces and territories.

What this boils down to is that, class.formr.dropdowns.php basically behaves as a plugin. If you wanted to add a list of motorcycles, for instance, all you would need to do is add the array of options (motorcycles) as a method to the Dropdowns class and then enter “motorcycles” as the second parameter. Take a look at the methods in the Dropdowns class for examples.

Example: produce a list of all US states

echo $form->input_select('state', 'State:','','','','','','state');

// will produce
<label for="state">State:</label> 
<select name="state" id="state" >
	<option value="" selected="selected">Select a State...</option>
	<option value="AL">Alabama</option>
	<option value="AK">Alaska</option>
	...
	<option value="WI">Wisconsin</option>
	<option value="WY">Wyoming</option>
</select>

Example: produce a list of all countries

echo $form->input_select('country', 'Country:','','','','','','country');

// will produce
<label for="country">Country:</label> 
<select name="country" id="country" >
	<option value="" selected="selected">Select a Country...</option>
	<option value="US">United States </option>
	<option value="CA">Canada</option>
	<option value="GB">United Kingdom</option>
	<option value=" ">---------------</option>
	<option value="AF">Afghanistan </option>
	...
	<option value="ZM">Zambia</option>
	<option value="ZW">Zimbabwe</option>
</select>

Example: produce a list of all Canadian provinces

echo $form->input_select('province', 'Province:','','','','','','province');

// will produce
<label for="province">Province:</label> 
<select name="province" id="province" >
	<option value="" selected="selected">Province or Territory...</option>
	<option value="AB">Alberta</option>
	<option value="BC">British Columbia</option>
	...
	<option value="SK">Saskatchewan</option>
	<option value="YT">Yukon</option>
</select>

Saving & Sharing Drop-down Menus

Formr comes with a few drop-down menus to get you started, however, it wouldn’t be much if you couldn’t save your own for reuse and/or sharing, right? This is easy:

  1. Create a folder named my_classes and put it at formr/my_classes.
  2. Copy formr/lib/class.formr.dropdowns.php into formr/my_classes and rename it my.dropdowns.php.
  3. Rename and then modify the sample classes to create your own.

To use your classes, just enter the name of the method (as a string) - just like you would with the state or country methods. Make sure your classes have unique names!

See the Extensibility section for more info on creating your own classes.

input_textarea()

This method is identical in all respects to the input_text() method except it generates a textarea. Note: Instead of the maxlength attribute of the previous input_text() example, you will instead specify rows and cols.

input_upload()

Alias of the input_file() method.

input_upload_multiple()

Identical to input_upload() except that it adds the multiple attribute, allowing for multiple files to be uploaded with one field element. May not work in all browsers.


HTML5 Inputs

Formr supports the following HTML5 input elements.

input_color()

Identical to input_text() except that it creates an type="color" element.

input_date()

Identical to input_text() except that it creates an <input type="date"> element.

input_datetime()

Identical to input_text() except that it creates an <input type="datetime"> element.

input_datetime_local()

Identical to input_text() except that it creates an <input type="datetime_local"> element.

input_email()

Identical to input_text() except that it creates an <input type="email"> element.

input_month()

Identical to input_text() except that it creates an <input type="month"> element.

input_number()

Identical to input_text() except that it creates an <input type="number"> element.

input_range()

Identical to input_text() except that it creates an <input type="range"> element.

input_search()

Identical to input_text() except that it creates an <input type="search"> element.

input_tel()

Identical to input_text() except that it creates an <input type="tel"> element.

input_time()

Identical to input_text() except that it creates an <input type="time"> element.

input_url()

Identical to input_text() except that it creates an <input type="url"> element.

input_week()

Identical to input_text() except that it creates an <input type="week"> element.


Forms

form_open()

Opens a form with a standard <form> tag and accepts six parameters. All parameters are optional, so you can just leave it empty and the <form> tag will be created automatically with the proper attributes.

  1. The first parameter optionally contains the form’s name.
  2. The second parameter optionally contains the form’s ID.
  3. The third parameter optionally contains the form’s action.
  4. The fourth parameter optionally contains the form’s method. Default is POST.
  5. The fifth parameter optionally contains a string, which lets you add CSS, JavaScript, etc.
  6. The sixth parameter optionally contains an associative array which creates hidden fields.
If an action isn't specified, form_open() will assume you want to process the form in the current script and will add the script's filename in the form's action attribute using $_SERVER['SCRIPT_NAME'].
form_open() will optionally let you add form attributes and hidden input fields, and will always add the attribute accept-charset="utf-8", unless you change the $charset property.
A form ID will be added automatically if an ID is used when instantiating Formr, eg: $form->id="MyForm".

Example: instantiating Formr, setting an ID and opening a form

$form = new Formr();
echo $form->form_open('MyForm');

// will produce (assuming our script name is form.php)
<form action="form.php" name="MyForm" id="MyForm" method="post" accept-charset="utf-8">

Example: adding the form action manually

echo $form->form_open('','','foo.php');

// will produce
<form action="foo.php" method="post" accept-charset="utf-8">

Example: adding an action and a CSS class

echo $form->form_open('','','foo.php','','class="bar"');

// will produce
<form action="foo.php" method="post" accept-charset="utf-8" class="bar">

Example: adding hidden input fields with form_open()

Hidden fields can be added by passing an associative array to the third parameter, where the array key is the field name and the array value is the field’s value.

$hidden = array('username' => 'John', 'email' => 'johndoh@email.com');
echo $form->form_open('form.php', '', '','','',$hidden);

// will produce
<form action="form.php" name="MyForm" id="MyForm" method="post" accept-charset="utf-8">

<input type="hidden" name="username" id="username" value="John">
<input type="hidden" name="email" id="email" value="johndoh@email.com">

form_open_multipart()

This method is identical to form_open() above except that it adds a multipart/form-data attribute, which is necessary if you would like to use the form to upload files.

form_close()

Closes the form with a standard </form> element.


Processing

submit()

The submit() method checks to see if the form has been submitted or not. It does this by checking the $_SERVER['REQUEST_METHOD'] for POST.

if($form->submit()){
    // form is submitted via POST
}

value()

If you build your form with Formr instead of HTML, eg; $form->input_text('fname') all fields will automatically re-populate after form submission. However, if you prefer to build your form fields in HTML you can still re-populate the field value after a POST with the value() method.

Enter the field’s name as the function’s only parameter.

<input type="text" name="fname" value="<?php echo $form->value('fname'); ?>">

post()

The post() method processes and validates (if required) the POST form input based upon a series of chainable rules.

There are three parameters to the post() function:

  1. The first parameter is required and contains the field name: the exact name you’ve given the form field.
  2. The optional second parameter contains the human readable text for this field, which will be inserted into the error message. It can optionally contain a custom error message string that will be shown if the field is required, yet left empty when submitted.
  3. The optional third parameter contains pipe-delimited (|) validation rules for this field.
The form data is passed through the PHP trim() and strip_tags() functions for basic sanitation. If you want to allow HTML in your forms, just add allow_html as a validation rule in the post() method's validation parameter and only trim() will be applied to the input.

Example: Process the form input for the fname field and put it into a variable

// this is basically the same as strip_tags(trim($_POST['fname']))
$fname = $form->post('fname');

Example: Make sure an email address is valid using FILTER_VALIDATE_EMAIL

$form->post('email','Email','valid_email');

Example: Require password is no less than 6 characters and no more than 20

$form->post('password','Password','min_length[6]|max_length[20]');

Example: Require password_conf matches password, is no less than 6 characters and no more than 20

$form->post('password_conf','Password Confirm','matches[password]|min_length[6]|max_length[20]');

Example: Create a custom error message string

// adding a pipe (`|`) character after the human readable text will create a custom error string
$form->post('email','Email|Please enter your email address','valid_email');

get()

Identical to post() except that it processes information via the $_GET Superglobal


FastForm

The FastForm methods are quite powerful and the documentation is rather extensive, so a separate docs page has been devoted just to them.

fastform()

This method lets you quickly and easily build a form with as many fields - and field types - as you want.

fastform_multipart()

Identical to the fastform() method, except it adds enctype="multipart/form-data" to the <form> tag.

fastpost()

Use this in concert with fastpost() to create form and validation sets which you can quickly and easily plugin and reuse. This method will also return an array of the key/value pairs from the POST array, plus perform some basic validation based upon the field names.


Buttons

input_submit()

Creates the standard <input type="submit"> element.

  1. The first parameter optionally contains the button name.
  2. The second parameter optionally contains label text. If text is entered a <label> element will be created.
  3. The third parameter optionally contains the button’s value.
  4. The fourth parameter optionally contains the button’s ID.
  5. The fifth parameter optionally contains a string, which lets you add CSS, JavaScript, etc.
echo $form->input_submit()

// will produce
<input type="submit" name="submit" value="Submit" id="submit">
Sometimes you may want to put a label next to your submit button so it will line up with your other form elements. This is really easy: just add &nbsp; as your label text. A label will be added and the person viewing your page won't see it.
echo $form->input_submit('submitForm', '&nbsp;', 'Submit Form', 'buttonID', 'class="submitButton"');

// will produce
<label for="submitForm">&nbsp;</label> 
<input type="submit" name="submitForm" value="Submit Form" id="buttonID" class="submitButton">

input_reset()

Identical to input_submit() except that it creates an <input type="reset"> element

input_button()

Identical to input_submit() but creates an <button> element.


Labels

label()

Creates the standard <label> element.

  1. The first parameter contains the field name for which this label is being created and is required.
  2. The second parameter contains the label text and is required.
  3. The third parameter optionally contains an ID attribute.
  4. The fourth parameter optionally contains a string, which lets you add CSS, JavaScript, etc.

Example: Create a label for the full_name field

echo $form->label('full_name','Full name:');

// will produce
<label for="full_name">Full name:</label>

Example: Add a CSS class to our label

echo $form->label('full_name','Full name:','','class="label"'); 

// will produce
<label for="full_name" class="label">Full name:</label>

Example: Wrap our label text in a div

echo $form->label('full_name','<div id="myLabel" class="fooBar">Full name</div>','','class="label"'); 

// will produce
<label for="full_name" class="label">
	<div id="myLabel" class="fooBar">Full name</div>
</label>

label_open()

Creates the opening <label> element. This is identical to the label() method, except that it does not close the element.

label_close()

Creates the standard </label> element.

The only parameter to label_close() contains the label text. This is handy if you want to wrap a label around a checkbox or radio button and want the text to be after the element, rather than before.

echo $form->label_close('Derby');

// will produce

Derby
</label>

echo $form->label_open('bowler');
echo $form->input_checkbox('bowler','','bowler');
echo $form->label_close('Bowler');

// will produce
<label for="bowler">
    <input type="checkbox" name="bowler" id="bowler" value="bowler">Bowler
</label>

Fieldsets

fieldset_open()

Creates the standard <fieldset> element.

  1. The first parameter optionally contains the legend text.
  2. The second parameter optionally contains a string, which lets you add CSS, JavaScript, etc.
echo $form->fieldset_open('Contact information');

// will produce
<fieldset>
	<legend>Contact information</legend>
echo $form->fieldset_open('Contact information', 'id="contact"');

// will produce
<fieldset id="contact">
	<legend>Contact information</legend>

fieldset_close()

Creates the standard </fieldset> element, with an optional string as the first parameter.


Messaging

messages()

Basically, this is the method you’ll use to print your messages. You can set the HTML element in which you’d like to contain the messages in the first and second parameters, or leave them blank and they’ll be formatted automatically using Bootstrap 3’s .alert classes (if you use Bootstrap as your wrapper).

Example: Print messages to the screen

echo $form->messages();

Example: Use your own CSS HTML and classes

$form->messages('<div class="error">','</div>');
messages() will not print anything to the screen if it's empty, so there's really no reason why you shouldn't have it in your scripts as it will print out error messages if you forgot to add a property or configured something incorrectly. A good place to put it is right before your <form> or in the <header> of your pages.

error_message()

Add your own custom error messages throughout your application and it will print via the messages() method. Uses the Bootstrap .alert .alert-danger classes, which can be changed via the $controls property or by creating your own wrapper class. See the Extensibility section for more info on creating your own classes.

$form->error_message('This is bad, and you should feel bad!');

info_message()

Identical to error_message() except uses the Bootstrap .alert-info classs.

success_message()

Identical to error_message() except uses the Bootstrap .alert-success classs.

warning_message()

Identical to error_message() except uses the Bootstrap .alert-warning class.

in_errors()

Use this to see if a field is in the $errors array

Example: Check if the email field is in the $errors array

if($form->in_errors('email')) {
    // do something here...
}

in_errors_if()

If the defined field is in the $errors array, return a string

echo $form->in_errors_if('name','please enter your name');

in_errors_else()

If the defined field is in the $errors array return a string, else return another string

echo $form->in_errors_else('name','please enter your name','you entered your name');

errors()

Use this method to see if the $errors array is empty.

if($form->errors()) {
    echo 'there were errors';
} else {
    echo 'no errors!';
}

add_to_errors()

Manually add a field’s key to the $errors array.

$form->add_to_errors('name');
This is different from the error_messages() method in that this method adds to the $errors array via array_push(), whereas error_message() just prints an error message string without adding it to the $errors array.

Misc. Methods

send_email()

Sends a very basic HTML or plain-text email using PHP’s mail() function. Optionally loops though the contents of the $_POST array and prints the key / value pair in the email.

  1. The first parameter is the recipient’s email address and is required.
  2. The second parameter is the email subject and is required.
  3. The third parameter contains the message body and is required.
  4. The fourth parameter is optional and contains a ‘from’ email address.
  5. The optional fifth parameter is binary; set to TRUE if you’d like to send the email in HTML.

Example: Send a Plain-Text Email

$to      = 'recipient@email.com';
$subject = 'Ahoy, Matey!';
$message = 'Welcome to our website!...';

$form->send_email($to, $subject, $message);

Example: Send an HTML Email with a Return Address

$to      = 'recipient@email.com';
$from    = 'me@domain.com';
$subject = 'Ahoy, Matey!';
$message = 'Welcome to our website!...';

$form->send_email($to, $subject, $message, $from, TRUE);

Example: Automatically Format and Send the POST Contents as HTML

By setting the message parameter to ‘POST’, Formr will loop through the PHP $_POST array and automatically clean and print the field name and value.

$to      = 'recipient@email.com';
$from    = 'me@domain.com';
$subject = 'Ahoy, Matey!';

$form->send_email($to, $subject, 'POST', $from, TRUE);

Produces something like

first_name: Jack
last_name: Black

Example: Formatting Fields with Underscores for Prettier Emails

If you want prettier emails while looping through the $_POST array, name your input fields with capital letters and underscores, and then prepend each name with an underscore. Prepending a field with an underscore tells Formr to replace all underscores with spaces, making for an easier to read email!

$form->input_text('_First_Name','First Name');
$form->input_text('_Last_Name','Last Name');

And the email will look like this…

First Name: Jack
Last Name: Black

printr()

Incredibly handy! Formr’s shortcut for print_r(), which automatically formats (in <pre> tags) and prints the contents of an array, which massively speeds up testing.

Prints the contents of an array

$form->printr($_POST);
$form->printr($_GET);
$form->printr($data);
$form->printr('POST');	// lazy alias...
$form->printr('GET');	// lazy alias...

slug()

Only allows letters, numbers and underscores in a string. If any character other than a letter, number or underscore is encountered it will be converted to an underscore.

Example: Slug the string ‘P Sherman 42’

$username = $form->slug('P Sherman 42');
// produces
'P_Sherman_42'

heading()

This is useful if you have a form that is more along the lines of a test, or questionnaire and you want to really call out the field when there’s an error in the form. Basically, you enter the field name in the first parameter and the string in the second, and if there’s an error the string will be enclosed in tags.

<h3><?php echo $form->heading('question1','How many inches in a foot?'); ?></h3>

// will produce upon page load
<h3>How many inches in a foot?</h3>

// will produce upon form error
<h3><span class="error">How many inches in a foot?</span></h3>

form_info()

Prints out the settings of your form. Try it!

$form->form_info();