• Basic Usage
  • Qualifiers
  • Options
  • Examples
  • Advanced

A jQuery plugin to facilitate the handling of form field dependencies.
$( subject ).dependsOn( dependencySet, [options] );

Basic Usage


  1. Include jQuery

    Add jQuery to your header.

    Make sure the path is set to the location where you have jQuery saved.
    <script type="text/javascript" src="jquery/jquery-1.7.2.min.js"></script>
  2. Include dependsOn

    Add dependsOn to your header after jQuery.

    Make sure the path is set to the location where you have dependsOn saved.
    <script type="text/javascript" src="dependsOn-1.0.0.min.js"></script>
  3. Add form components

    In this example the input field "myText" will be enabled when the checkbox "myCheck" is checked.

    <form id="myForm">
    	<label for="myCheck">Check Me</label>
    	<input type="checkbox" id="myCheck">
    
    	<label for="myText">Input</label>
    	<input type="text" id="myText" value="">
    </form>
  4. Activate plugin

    Use jQuery selectors to active the plugin.

    $('#myText').WPOnion_dependsOn({
    	// The selector for the depenency
    	'#myCheck': {
    		// The dependency qualifiers
    		enabled: true,
    		checked: true
    	}
    });

Qualifiers


Qualifier Description Type
enabled If true, then dependency must not have the "disabled" attribute. Boolean
checked If true, then dependency must not have the "checked" attribute. Used for checkboxes and radio buttons. Boolean
values Dependency value must equal one of the provided values. Array
not Dependency value must not equal any of the provided values. Array
match Dependency value must match the regular expression. RegEx
notMatch Dependency value must not match the regular expression. RegEx
contains One of the provided values must be contained in an array of dependency values. Used for select fields with the "multiple" attribute. Array
email If true, dependency value must match an email address. Boolean
url If true, Dependency value must match an URL. Boolean
range Dependency value must be within the given range Array
Custom Custom function which return true or false. Function

Options


Property Default Description Type
disable true Add "disabled" attribute to the subject's form field. Boolean
readonly false Add "readonly" attribute to the subject's form field. Boolean
hide true Hide the subject on disable and reveal the subject on enable. Boolean
duration 200 The time in milliseconds for the fade transition. Used only if hide is set to true. Number
onEnable Empty Function The callback function to execute when the subject has been enabled. Function
onDisable Empty Function The callback function to execute when the subject has been disabled. Function
valueOnEnable n/a The value to set the subject to when enabled. String
valueOnDisable n/a The value to set the subject to when disabled. String
checkOnEnable n/a If true, "checked" attribute will be added to subject when enabled. If false, "checked" attribute will be removed from subject when enabled. For checkboxes and radio buttons. Boolean
checkOnDisable n/a If true, "checked" attribute will be added to subject when disabled. If false, "checked" attribute will be removed from subject when disabled. For checkboxes and radio buttons. Boolean
valueTarget n/a jQuery selector for the object to you want to target for editing the value. Use if you want to alter the value of something other than the subject. String
toggleClass n/a The class you wish to be appended to the subject when enabled. The class will be removed when the subject is disabled. String

Examples

  1. Checked

    Text field will be enabled and revealed when the checkbox is checked.

    Hide HTML

    <form id="basicTest">
    	<label>
    		<input type="checkbox"> Check me
    	</label>
    
    	<input type="text" class="subject">
    </form>

    Hide Javascript

    $('#basicTest .subject').WPOnion_dependsOn({
    	'#basicTest input[type="checkbox"]': {
    		checked: true
    	}
    });
  2. Values

    Submit button will be enabled and revealed when the text field value is either "yes" or "true".


    Hide HTML

    <form id="valuesTest">
    	<label>Do you wish to continue?</label>
    	<input type="text">
    
    	<input type="submit" class="subject">
    </form>

    Hide Javascript

    $('#valuesTest .subject').WPOnion_dependsOn({
    	'#valuesTest input[type="text"]': {
    		values: ['yes', 'true']
    	}
    });
  3. Numerical Range

    Submit button will be enabled and revealed when the text field value is within the range of 2 and 10, with a step value of 2


    Hide HTML

    <form id="numberRangeTest">
    	<label>Enter a multiple of 2 between 2 and 10</label>
    	<input type="text">
    
    	<input type="submit" class="subject">
    </form>

    Hide Javascript

    $('#numberRangeTest .subject').WPOnion_dependsOn({
    	'#numberRangeTest input[type="text"]': {
    		range: [2, 10, 2]
    	}
    });
  4. Alpha Range

    Submit button will be enabled and revealed when the text field value is between "a" and "c"


    Hide HTML

    <form id="alphaRangeTest">
    	<label>Enter a letter between "a" and "c"</label>
    	<input type="text">
    
    	<input type="submit" class="subject">
    </form>

    Hide Javascript

    $('#alphaRangeTest .subject').WPOnion_dependsOn({
    	'#alphaRangeTest input[type="text"]': {
    		range: ['a', 'c']
    	}
    });
  5. Multiple Dependencies

    Submit button will be enabled and revealed when the checkbox is check and the text field value is an email address.

    Hide HTML

    <form id="emailTest">
    	<label>
    		Send me emails <input type="checkbox">
    	</label>
    
    	<label>
    		Email <input type="text" class="email">
    	</label>
    
    	<input type="submit" class="subject">
    </form>

    Hide Javascript

    $('#emailTest .subject').WPOnion_dependsOn({
    	'#emailTest input[type="checkbox"]': {
    		checked: true
    	},
    	'#emailTest .email': {
    		email: true
    	}
    });
  6. Affecting the value

    Change the text field value when the select menu changes.

    Hide HTML

    <form id="affectValueTest">
    	<label>
    		Enable? <select>
    			<option value="yes">Yes</option>
    			<option value="no">No</option>
    		</select>
    	</label>
    
    	<input type="text" class="subject">
    </form>

    Hide Javascript

    $('#affectValueTest .subject').WPOnion_dependsOn({
    	'#affectValueTest select': {
    		values: ['yes']
    	}
    }, {
    	valueOnEnable: 'Hello, world!',
    	valueOnDisable: 'Goodbye, cruel world...',
    	hide: false
    });
  7. Handling Multiple Values

    Button will be enabled when the proper two animals are selected. (hint: They have four legs)


    Hide HTML

    <form id="multipleValuesTest">
    	<label>I'm thinking of two animals, what are they?</label>
    	<select multiple>
    		<option value="dog">Dog</option>
    		<option value="fish">Fish</option>
    		<option value="cat">Cat</option>
    		<option value="horse">Spider</option>
    	</select>
    	<br>
    
    	<input type="submit" class="subject">
    </form>

    Hide Javascript

    $('#multipleValuesTest .subject').WPOnion_dependsOn({
    	'#multipleValuesTest select': {
    		values: [['dog', 'cat']]
    	}
    }, {
    	valueOnEnable: 'Correct!',
    	valueOnDisable: 'Incorrect',
    	hide: false
    });

Advanced Usage

  1. Multiple Dependencies with the or method.

    $( subject ).dependsOn( dependencySet, [options] ).or( dependencySet );
    Adds an additional dependency set to check against. They can also be chained together for three or more dependency sets.

    Example

    "Add Another" button will be enabled when extra cheese is checked, or an extra topping is selected.

    Hide HTML

    <form id="orTest">
    	<label>Would you like to add anything to your pizza?</label>
    	<label>
    		Extra Cheese <input type="checkbox" name="xtraCheese">
    	</label>
    
    	<label>
    		Extra Topping <select class="span2">
    			<option value="select">Select one...</option>
    			<option value="pepperoni">Pepperoni</option>
    			<option value="sasage">Sausage</option>
    			<option value="olives">Olives</option>
    			<option value="onion">Onion</option>
    			<option value="Bell Pepper">Bell Pepper</option>
    		</select>
    	</label>
    
    	<input type="button" class="subject" value="Add Another">
    	<input type="submit" value="Continue">
    </form>

    Hide Javascript

    $('#orTest .subject').WPOnion_dependsOn({
    	'#orTest input[name="xtraCheese"]': {
    		checked: true
    	}
    }, {
    	hide: false
    }).or({
    	'#orTest select': {
    		not: ['select']
    	}
    });
  2. Custom Qualifiers

    You can easily add your own qualifiers for extended functionality. To use a custom qualifier, add your own property to the qualifiers and assign it to function. The function will be passed the value of the dependency and must return a boolean (true|false) value in order to function properly. There is no limit to the amount of custom qualifiers you can have.

    Example

    The text field will be enabled when the checkbox is checked and "Click me" is clicked.

    Click me

    Hide HTML

    <form id="customQualifierTest">
    	<label>
    		<input type="checkbox"> Check me
    	</label>
    
    	<a href="#" class="clickMe">Click me</a>
    	<br>
    
    	<input type="text" class="subject">
    </form>

    Hide Javascript

    var isClicked = false;
    
    var customQualifierTest = $('#customQualifierTest .subject').WPOnion_dependsOn({
    	'#customQualifierTest input[type="checkbox"]': {
    		checked: true,
    		// Custom qualifier returns the value of the global variable `isClicked`.
    		clicked: function( val ) {
    			return isClicked;
    		}
    	}
    }, {
    	hide: false
    });
    
    $('#customQualifierTest .clickMe').toggle(function() {
    	isClicked = true;
    	// Force dependencies to be checked.
    	customQualifierTest.check();
    	return false;
    }, function() {
    	isClicked = false;
    	// Force dependencies to be checked.
    	customQualifierTest.check();
    	return false;
    });
  3. Enable and Disable Callbacks

    You can specify callbacks for enable and disable using the onEnable and onDisable options.

    Example

    When the text field is enabled by checking the checkbox, a dialog will appear.

    Hide HTML

    <form id="callbackTest">
    	<label>
    		<input type="checkbox"> Check me
    	</label>
    
    	<input type="text" class="subject">
    </form>

    Hide Javascript

    $('#callbackTest .subject').WPOnion_dependsOn({
    	'#callbackTest input[type="checkbox"]': {
    		checked: true
    	}
    }, {
    	onEnable: function(e, $subject) {
    		window.alert('Hello, world!');
    	}
    });
  4. Value Target

    If you wish to change the value of a form field other than the subject you would use the valueTarget option in conjunction with the valueOnEnable and/or valueOnDisable options. This is useful if the subject is not a form field itself.

    Example

    When "Married" or "Widowed" are selected, the salutaion field will be changed to "Mrs.".

    Hide HTML

    <form id="valueTargetTest">
    	<label>
    		Married?
    		<select>
    			<option value="married">Married</option>
    			<option value="divorced">Divorced</option>
    			<option value="single">Single</option>
    			<option value="widowed">Widowed</option>
    		</select>
    	</label>
    
    	<div class="subject">
    		<input type="text" class="salutation">
    		<input type="text" cvalue="Doe">
    	</div>
    </form>

    Hide Javascript

    $('#valueTargetTest .subject').WPOnion_dependsOn({
    	'#valueTargetTest select': {
    		values: ['married', 'widowed']
    	}
    }, {
    	valueTarget: '#valueTargetTest .salutation',
    	valueOnEnable: 'Mrs.',
    	valueOnDisable: '',
    	hide: false
    });