jFormer DocumentationForm Features

Dependencies

Dependencies are a form feature that allow certain fields to be hidden or locked until certain criteria are met.

Usage

Dependency is a option that is available to every component. Any dependent component that does not have all conditions met are considered null, and do not submit data to the server, or validate. Therefore, if a component is locked and required, it will not impede form wide validation. Dependencies rely on the dependencyOptions array within the Options array, and has three keys:

  • dependentOn
  • display
  • jsFunction

Sample Usage

	$optionsArray = array(
                        'dependencyOptions' => array( 
                                'dependentOn' => componentId,
                                'display' => hide,
                                'jsFunction' => 'function() { return true }',
       	
	);

dependencyOptions Array

dependentOn

string or array | passed a string or array of strings that are ID's of components that when changed will trigger jsFunction for this dependency.

display

string | accepts on of two options:

  • hide - default | when the conditions for this component's dependency are not met, the entire component is hidden.

  • lock - when the conditions for this component's dependency are not met, the entire component is locked, the input is switched to disabled, and the class dependencyDisplayLocked is added to the component wrapper.

jsFunction

is javascript (can be jquery) or a function that runs when one of the dependentOn IDs are changed. must return true or false, if returns false then the dependency is not met and the component is either hidden or locked, depending on the display option.

Next Page: Instances

This page was last edited on April 25, 2011 at 1:48pm.

11 comments (add a comment)

T-productions on 2011-07-19 02:45:51

Do you have an example with a checkbox ?
When I check it, it displays the hidden textarea otherwise no.

Thanks

Someone on 2011-08-11 01:19:22

I think the example above is wrong:

* instead of 'display' => hide it should be 'display' => 'hide'
* instead of 'jsFunction' => 'function() { return true }' it should be 'jsFunction' => 'function checkXY() { return true }'

For the third paramter I don't have time to check if the function name is injejcted into glaobal namespace, so to be save I would for the moment use a unique value.

Someone on 2011-08-11 02:14:38

In Firebug it seems to be, that eval is used for the third parameter, and with every change in the dependent control, I get a new one in my eval sequence. May by not the best solution currently!?

Someone on 2011-08-11 02:28:06

Sorry I was wrong with my first post! Eval is used for the third Parameter ('jsFunction'), so I just use an boolean expression. The following dependency on a drop down works just fine for me:

new JFormComponentSingleLineText('id', 'Label:',
array(
'dependencyOptions' => array(
'display' => 'hide',
'dependentOn' => 'dependentId',
'jsFunction' => '$("#dependentId option:selected").val() == "whatever"'
)
)
)

Someone on 2011-08-11 02:59:57

One modification was necessary for my above example after line 4224 (last sources):

elementsToDisable.find(':input').removeAttr('disabled');

Otherwise my Element get's displayed correctly but isn't enabled.

yuri on 2011-10-02 20:06:58

I want to use the function dependencyOptions for JFormComponentSingleLineText component to display the following text box when writing a specific word such as "mother." Please help me, as I am new I have no idea if this can be done.

someone on 2011-10-03 17:42:37

Do you have an example with a SingleLineText ?
When I'm writing a specific word for example "house", it displays the hidden textarea otherwise no.

Thanks

CK on 2011-11-08 10:40:09

Here's an example of the singleLineText with a dependency as requested.

new JFormComponentSingleLineText('answerText', 'Answer Text: ', array(
'tip' => 'Type in an option for the multiple choice question. Limit 5.',
'validationOptions' => array('required'),
'dependencyOptions' => array(
'dependentOn' => 'questionType',
'display' => 'hide',
'jsFunction' => '$("#questionType").val().indexOf("multi") >= 0'
)
)
)

Note: It appears that ANONYMOUS functions e.g. function() do NOT work with the eval. You must name the function e.g functionXY() or have a boolean statement.

CK on 2011-11-09 07:20:56

Update:

Even named functions don't work quite right. It evals as a function but doesn't return the value from within a function anonymous or otherwise.

Boolean statements seem to be the ONLY way, without modifying the jFormer.js itself.

This line allows a field with instances to show up IF a drop down box in the same section has a value that contains 'multi'

<div style="width:200px;height:100px">
<pre>
$('#' $(this).attr('id') '-wrapper').parent().children().children('.jFormComponentDropDown').val().indexOf('multi') >= 0</pre></div>

CK on 2011-11-09 20:34:43

Here's how to set a dependency on an instanced object. It's hacky though, and requires modifying the jFormer.js (uncompressed is easier to modify)

Around line 4000 in the jFormComponent Class there is a function called createInstanceObject. Add this to the function (with your own code, or modify, whatever).

// Original code
createInstanceObject:function(instanceClone, options){

// Hacked this to allow our instances to actually work properly.
if(options.dependencyOptions !== null && instanceClone[0].id.indexOf('answerText') >= 0){
var cloneID = instanceClone[0].parentNode.id;
var secexists = cloneID.indexOf('-section') >= 0;

if(secexists){
var section = cloneID.substring(cloneID.indexOf('section'));
var newOptions = {dependencyOptions: {dependentOn: {0: 'questionType-' section}}};
$.extend(true, options, newOptions);
}
}

// Next line of original code
var tempOptions = $.extend(true, {}, options);


It's not perfect, somehow it needs to be reinstantiated, but when the dependentOn changes the new dependency code will trigger. You can also override the jsFunction and the method of hiding.

var newOptions = {dependencyOptions: {dependentOn: {0: 'questionType-' section}}, {display: 'hide'}. jsFunction: 'Your new Code line'};

Rafael on 2011-11-29 01:49:30

this code has error, when next page is disable, not scroll to the first enable page:

// if the next page is disabled by dependency, loop through till you find a good page.
if(self.jFormPages[self.jFormPageIdArray[self.currentJFormPageIdArrayIndex 1]].disabledByDependency){

// orginal
//for(var i = self.currentJFormPageIdArrayIndex 1; i <= self.jFormPageIdArray.length - 1; i ){
// page is enabled, set the proper index, and break out of the loop.
//if(!self.jFormPages[self.jFormPageIdArray[self.currentJFormPageIdArrayIndex i]].disabledByDependency){
//self.currentJFormPageIdArrayIndex = self.currentJFormPageIdArrayIndex i;
//break;
//}
//}

// correctly
for(var i = self.currentJFormPageIdArrayIndex 1; i <= self.jFormPageIdArray.length - 1; i ){
// page is enabled, set the proper index, and break out of the loop.
if(!self.jFormPages[self.jFormPageIdArray[i]].disabledByDependency){
self.currentJFormPageIdArrayIndex = i;
break;
}
}


} else {
self.currentJFormPageIdArrayIndex = self.currentJFormPageIdArrayIndex 1;
}