Input dependencies (or field dependencies)

Input and field 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.

Video: dependencies in action

This is an old video and shows a much older version of ProcessWire, but still does a good job of visually demonstrating how input/field dependencies work.

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. All admin themes included with ProcessWire support them.

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

Twitter updates

  • New post: A look at two new WireMail modules for sending email, plus details on how you can configure ProcessWire to use Gmail for sending email— More
    19 July 2019
  • New post: Version 3.0.135 of ProcessWire on the dev branch focuses on some .htaccess updates, adds clarity to debug mode, and improves upon the installer— More
    5 July 2019
  • ProcessWire 3.0.133 adds a useful new Page::meta() method for a new type of page-specific persistent data storage, adds the ability for users to create their own bookmarks in Lister, and has a handy and time saving update for the asmSelect input type— More
    14 June 2019

Latest news

  • ProcessWire Weekly #271
    In the 271st issue of ProcessWire Weekly we're going to introduce two brand new WireMail modules, a new Textformatter module from BitPoet, and a brand new markup module from Chris Thomson. Read on!
    Weekly.pw / 20 July 2019
  • Two new WireMail modules and using Gmail with PW
    A look at two new WireMail modules for sending email, plus details on how you can configure ProcessWire to use Gmail for sending email.
    Blog / 19 July 2019
  • Subscribe to weekly ProcessWire news

“The end client and designer love the ease at which they can update the website. Training beyond how to log in wasn’t even necessary since ProcessWire’s default interface is straightforward.” —Jonathan Lahijani