#Form Forker jQuery plugin for handling conditional form fields based on user input. Demo
##Getting Started Incude jquery.former-forker.js and a copy of jQuery on your page. Initialize the plugin on your form like so:
$('#branching-form').forkable();
##Branching Your Form
Any form fields that should act as 'forks' in the road on your form must have a name
attribute. For example:
<input type="text" name="person_age" placeholder="Age" />
The dependent children of this input (form fields that should be shown/hidden based on the value of person_age
) need two data attributes: data-parent-branch
and data-show-on-value
.
<div class="field hidden" data-parent-branch="person_age" data-show-on-value="5">
<input type="text" name="favorite_cartoon" placeholder="What's your favorite cartoon?" />
</div>
The data-parent-branch
attribute should match the name
of the fork it corresponds to. The data-show-on-value
attribute will let you specify the conditions that must be met in order to display this form field.
##Declaring Conditions
To determine whether or not a child form field should be shown, you must specify the condition to be met by putting a data-show-on-value
attribute on your form field.
###String Conditions A simple string conditional would look like so:
<div class="field hidden" data-parent-branch="favorite_candy" data-show-on-value="chocolate">
<input type="text" name="which_chocolate_bar" placeholder="Which chocolate bar?" />
</div>
In this example, the child field will only show if the value of its parent input, favorite_candy
equals chocolate. If we wanted to show this field when the value was chocolate or skittles, we could change our data-show-on-value
attribute to: data-show-on-value="chocolate,skittles"
. You can add as many string comparators as you want, separated by a comma.
###Arithmetic Conditions Setting an arithmetic condition works the same as a string condition, but there is special syntax for declaring the type of operation you want to perform:
data-show-on-value="5" // user input must equal 5
data-show-on-value="!5" // user input must not equal 5
data-show-on-value="5,7,9" // user input must equal 5 or 7 or 9
data-show-on-value="!5,!7,!9" // user input must not equal 5 or 7 or 9
data-show-on-value="gt-5" // user input must be greater than 5
data-show-on-value="lt-5" // user input must be less than 5
data-show-on-value="gte-5" // user input must be greater than or equal to 5
data-show-on-value="lte-5" // user input must be less than or equal to 5
data-show-on-value="5..10" // user input must be between 5 and 10, inclusive
You can also add an && or || operator to your conditions like so:
data-show-on-value="gte-3_and_lte-7" // essentially the same as 3..7
data-show-on-value="gt-7_or_lt-3"
##Branching Methods
The default branching methods are integerEval
and stringEval
. By default, if the user input is a string that can successfully be parsed into an integer (i.e. "5"), the branching will perform an integerEval
. If the result of the user input can not be parsed into an integer, the form will branch on a stringEval
. If, for some reason, you don't want this behavior, you can override which branching method is used by adding a data-branching-fn: <branchingmethodname>
attribute to your form field element.
###Creating a Custom Branching Method
If you'd like to override the default branching methods with your own, you can pass in a branchingMethods
object when calling forkable().
$('#branching-form').forkable({
branchingMethods: {
"customEval": function(childBranches, userEnteredValue) {
// do custom evaluation here
}
}
});
Add a data-branching-fn
attribute to your form field element, and set it equal to the name of your custom branching method.