Inputfield dependencies enable you to specify the conditions under which a particular field in the page editor is shown or required.

Beyond the page editor, Inputfield dependencies may also be used with any other form based upon Inputfields. This includes ProcessWire Form Builder and configuration screens for ProcessWire modules. To use Inputfield dependencies, you must have ProcessWire 2.3.4 or greater.

Video: dependencies in action

Full-screen and switching to HD (720p) is recommended for this video.

Types of field dependencies

show-if dependencies enable you to specify a selector string of conditions that must match in order for a field to be shown.

require-if dependencies enable you to specify a selector string of conditions that must match in order for the field to be required in the form.

Where you can configure show-if dependencies

1. From any field edit screen in the ProcessWire admin.
(Setup > Fields > [edit a field] > Input > Visibility > Show field if...).

2. From any field-template context edit screen.
(Setup > Templates > [edit a template] > [click a field] > Visibility > Show field if...).

3. From the API on any Inputfield object/module:

$inputfield->showIf = "field=value";

4. From the Form Builder module.
([edit a field] > Visibility > Show field if…)

Where you can configure require-if dependencies

1. From any field edit screen in the ProcessWire admin.
(Setup > Fields > [edit a field] > Input > Required [checked] > Required if…).
Please note: the required checkbox must be checked first.

2. From any field-template context edit screen.
(Setup > Templates > [edit a template] > [click a field] > Required [checked] > Required if…).
Please note: the required checkbox must be checked first.

3. From the API on any Inputfield object/module:

$inputfield->required = 1; // must be set
$inputfield->requiredIf = "field=value";

4. From the Form Builder module.
([edit a field] > Required [checked] > Required if…)

Selector string format

The expected format for selector strings is: field=value, where "field" is the name of the field you want to check, "=" is the operator you want to use for comparison, and "value" is the value you want to compare. The "field" may be the name of any field in your form. The operator may be any one of the allowed operators (see below). The "value" may be any string or integer value (though see limitations section below). You may specify multiple conditions by separating each field=value condition with a comma, i.e.

fullname!='', items>5

Allowed operators

=   equal
!=  not equal
>   greater than
<   less than
>=  greater than or equal
<=  less than or equal
%=  contains phrase
*=  contains phrase (same as above) 

Limitations

When using selector strings with Inputfield dependencies, the format is largely the same as regular selector strings except that not as many options are yet supported.

  • Currently, the "value" may not contain commas (as they are used to separate conditions) but that is only a short term limitation.
  • While you can specify OR conditions with "|" in the field or value you cannot use OR groups.
  • The "~=" string matching operator is not supported.
  • Subfields are not yet supported, except for "count", i.e. "field_name.count".
  • Not all Inputfields will work with dependencies, though most should. We'll later update this page with a list of core Inputfields that are known not to work with dependencies.
  • Field dependency selectors may not yet query the value of a multi-language field. However, they can show/hide multi-language fields according to the value of other fields.
  • Field dependencies must be supported by the admin theme. As a result, field dependencies may not work in admin themes other than the default one included with ProcessWire. However, we expect more admin themes will support dependencies soon.

Examples

Matching a quantity of selected items

When attempting to match the value from a field containing multiple selections, you may match based on the quality of values selected by using the count subfield in your selector field. The format is "field.count=[number]", which is best demonstrated by example:

Matches if 1-2 items is selected from field "categories":

categories.count>0, categories.count<3

Matches only if no categories are selected:

categories.count=0

Matching blank or not-blank

To match a blank value, specify an empty quoted string. Quotes may be double or single quotes, it does not matter. The following example would match if the first_name field was populated and the last_name field was blank.

first_name!='', last_name=''

To match a blank (or not blank) quantity of selected items, you can also use the "count" subfield described in the previous section.

Matching a page in a page reference field

Most multiple selection fields in ProcessWire are based upon page reference fields. The values present in page reference fields are the selected page IDs. As a result, to match a specific page in a page reference field, you should match the ID. For instance, lets say that you wanted to match a "featured" category in your categories field. You'd determine the ID of the "featured" page by editing it and looking at the "id" variable in the address bar of your browser. Then you'd take that number and use it in your selector string. Lets say that the ID of the "featured" page was 1234. We would match it in the categories field like this:

categories=1234

That condition specifies that the "featured" page must be one of the selected categories. In a multiple-selection field, other categories may also be selected. If you wanted to specify that only the "featured" (id=1234) category may be selected, then you'd do this:

categories=1234, categories.count=1

Note: we will soon support specification of page references by /path/to/page/ as well.

Matching a single checkbox field

The value of a checked checkbox field is 1 and the value of an unchecked checkbox field is blank or 0. While there are many ways to query the value, we recommend simply specifying a 1 for checked and a 0 for unchecked:

checkbox=1
checkbox=0

For admin theme developers

By necessity, part of the support for inputfield dependencies lies within the admin theme. However, supporting them should be a fairly simple matter. Here's how:

1. Have your admin theme reference the inputfields.js that is in the core/default admin theme, rather than one in your own admin theme directory. That way you won't have to maintain a separate copy of this file in your admin theme:

<script type='text/javascript' src='<php echo $config->urls->root; ?>wire/templates-admin/scripts/inputfields.js'></script>

If need be, you can keep your own copy of inputfields.js in your admin theme, but I don't recommend doing that until the code in that file is considered 100% stable and not likely to change regularly. That's why it's better to just reference the one in the default admin theme.

2. Update your /site/templates-admin/styles/inputfields.css to add this (below):

.InputfieldForm .Inputfields .InputfieldColumnWidthFirstTmp, 
.InputfieldForm .Inputfields .InputfieldColumnWidthFirst.InputfieldStateHidden + .Inputfield {
  /* for support of inputfield dependencies */
  clear: both;
  margin-left: 0;
}

…OR, if it works with your admin theme, just reference the inputfields.css in /wire/templates-admin/, like you did with inputfields.js:

<link rel='stylesheet' type='text/css' href='<?php echo $config->urls->root; ?>wire/templates-admin/styles/inputfields.css' />

Comments

No comments yet. Be the first to post!

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.