Views Reference Sift lets editors select entities to narrow an embedded View. It is for site builders who want to reuse one listing across several pages. Views Reference Field Filter reuses exposed filters, while Sift supplies contextual filter values without requiring an exposed form.
- Requirements
- Recommended modules
- Installation
- Configuration
- Migrating from the Argument setting
- API and stability
- Troubleshooting
- FAQ
- Maintainers
- Drupal 11.3 or later in the Drupal 11 series.
- PHP 8.3 or later.
- Views, which is part of Drupal core.
- Views Reference Field 2.0.0-beta14 or later in the 2.x series.
Enable Taxonomy if you plan to filter by terms.
Drupal 12 support depends on Views Reference releasing its setting discovery fix. Views Reference issue #3583101
- Views Reference Field Filter gives editors controls for a View's exposed filters.
- Inline Form Errors is a core module that shows an error next to the input and links to it from the error summary.
-
Add the GitHub repository and install Sift from your Drupal project's Composer root.
composer config repositories.viewsreference-sift vcs \ https://github.com/fourkitchens/viewsreference_sift.git composer require 'fourkitchens/viewsreference_sift:^1.0@beta' \ 'drupal/viewsreference:^2.0.0-beta14' drush en viewsreference_sift
-
Set up the field and View as described below. Sift enables its Views display extender during installation. On a site upgrading from an older beta, run
drush updbto enable the extender.
Views Reference 2.x requires beta stability until it has a stable release. The Composer constraints above allow beta versions for these two packages without changing the stability setting for the whole site.
- Add a Views Reference field to an entity bundle, such as an Article content type.
- Edit the field settings. Allow the View and display type you plan to use and enable Sift filters.
- To use another autocomplete widget, open Manage form display and edit the Views Reference field's widget settings. Choose Sift autocomplete widget, then update the widget settings and save the form display. For example, enable Tagify and select Tagify here. The choice applies to filters set to Autocomplete in Views and uses the widget's defaults.
- Edit a content item and select the View and display. Open Options and use Filter this list to select items. Choose a match mode if offered. Save the content item.
You can also enable Views Reference's Argument setting. Use it to fill other contextual filter positions. If both settings fill the same position, the Sift selection wins.
Core autocomplete is the default and is used if the configured widget is
unavailable for a filter. Compatible contributed widgets can opt in by setting
viewsreference_sift to TRUE in hook_field_widget_info_alter(). The widget
must support multiple entity references and work without a stored field.
- Edit a View display under Structure → Views. Add a contextual filter
that accepts entity IDs. Supported options include Has taxonomy term
ID with or without depth, entity reference target IDs including
references to configuration entities, bundle IDs such as content types
and taxonomy vocabularies, and numeric ID filters with an entity validator.
Other string filters using
StringArgumentneed an entity validator for an entity type with string IDs. - Enable Specify validation criteria and choose an entity validator to restrict the allowed bundles where applicable.
- Set Administrative title to label the widget. Without it, Sift uses the name of the single allowed bundle or the entity type's plural label.
- Turn on Allow multiple values if editors should select several items. All is available for multiple-value filters that use Views' many-to-one matching. Other filters use Any.
- Under When the filter value is not available, choose how Views handles an empty contextual filter. If a later filter has a Sift selection, Sift passes the exception value for Display all results for the specified field. For Provide default value, Sift uses the default when one is available. Otherwise, Views stops at the empty filter and handles it as it would without Sift.
For a string ID filter, choose an exception value that differs from every selectable ID. Views skips the filter when its argument matches the exception.
Sift shows one widget per supported and enabled filter, in display order. Selections on different filters apply together. For taxonomy filters in Any mode, enable Reduce duplicates if the View repeats rows. A positive taxonomy depth also matches child terms.
Edit a display and open Advanced → Other → Sift. Set the options for each filter, apply the changes, and save the View.
- Enable this filter shows the widget and applies the selection. On by default.
- Label replaces the default widget label. Blank by default.
- Description adds help for editors. Blank by default. The taxonomy depth filter has built-in help.
- Allowed bundles narrows the validator's list when it specifies two or more bundles. The default uses all bundles the validator allows.
- Match lets the editor choose whether each result must match at least one selected item (OR) or every selected item (AND). You can also fix the behavior on filters that support both modes.
- Allow exclusion lets editors choose Hide items that match. Hiding items always matches Any: an article tagged A and B is hidden when the editor excludes A. This option is off by default and is available for supported SQL filters on the view's base entity without a relationship, including direct entity IDs, taxonomy terms without depth, and entity reference fields.
- Widget defaults to Checkboxes for bundle filters and Autocomplete for other filters. Checkboxes shows checkboxes for multiple-value filters and radio buttons for single-value filters. Optional radio groups include Use the default when one is available, or None otherwise. You can also choose Select list. Checkboxes and Select list switch to autocomplete above 100 referenceable items.
- Maximum selections defaults to 10. Set it from 1 to 50 for a filter that accepts multiple items. The widget shows this limit even when the default is used. A single-value filter accepts one item.
- Default selection sets fixed items for a filter. Sift uses the valid defaults when the editor leaves that filter empty. A field selection overrides the default for its own filter. Defaults use the filter's Match setting, with Any when the editor usually chooses.
- Require a selection requires at least one item before saving. A valid default selection satisfies this requirement. When the editor must choose an item, the widget shows an instruction and exposes the required state to assistive technology. Off by default.
Sift applies these defaults to Views Reference embeds with Sift filters enabled, including on Views AJAX requests. Views' Provide default value handles a missing contextual argument and can use a fixed value or a value from the current page. Sift sends its selections as contextual arguments.
Sift warns when the action for an earlier empty contextual filter can prevent a later Sift selection from applying. The warning names the earlier filter and its configured action. The display summary flags enabled filters with these warnings. If an earlier filter provides a default, a note explains that the later selection applies only when the default is available at render time.
In the contextual filter, choose Provide default value and a source from the current page. For example, use the current page's taxonomy term. Leave Sift's Default selection blank and leave the field selection empty so Views supplies the value from the current page.
In the contextual filter settings, enable Override title under When
the filter value is available or a default is provided. Use
{{ arguments.<filter id> }} in the title. For example, enter
More about {{ arguments.tid }} for the tid filter. Find the ID under
Replacement patterns. Enable Include View Title in the Views
Reference field settings and select it on the field item.
Create a Page display with the same contextual filters in the same order as the embedded display. On the embedded display, set Link display to that page and enable Use more link. Set the link text to See all. Views passes the current arguments to the Page display.
Save the View and export its configuration. For a recipe, include the
exported View file in the recipe's config directory and install Sift as
part of the recipe. Keep the complete View export. This excerpt shows the
Sift settings for contextual filter tid on display embed_1.
display:
embed_1:
display_options:
display_extenders:
viewsreference_sift:
filters:
tid:
enabled: true
label: Topics
description: Choose topics to show in this listing.
bundles:
- tags
match: any
widget: checkboxes
max: 3
required: false
default_ids:
- '12'
- '34'Enable Sift filters alongside Argument in the Views Reference field settings. Configure Sift for the contextual filters on the chosen displays. With Drush 13 installed, preview the conversion from the site's root:
drush viewsreference-sift:convert-arguments \
--entity-type=node --bundle=article --field=field_listingThe command reports each item without saving. Omit any of the three filters to broaden the scan. It also reports fields that enable Argument but need Sift filters enabled.
Plain IDs such as 12+15 (Any) or 12,15 (All) can move to Sift when the
filter supports that match mode and all IDs pass validation. Tokens, invalid
IDs, unsupported or disabled filters, and positions with a saved Sift
selection stay in Argument. Converted positions use the filter's exception
value to keep remaining arguments aligned. The command removes trailing
placeholders when they can be omitted safely and clears Argument when
nothing remains.
Review the report and back up the site's database before running the same
command with --apply. Run it while edits to the scanned content are paused.
Apply saves changed items across translations,
creating a logged revision where the entity type supports it. It skips
entities with newer pending revisions so their drafts stay intact.
References pinned to older revisions continue to use those revisions.
Leave Argument enabled for fields with values the command did not convert.
These contracts are stable across the 1.x series.
- The Views Reference setting plugin ID
sift_terms. - The stored selection format described below.
- The display extender ID
viewsreference_siftand its configuration schema. A filter's optionaldefault_idskey stores a list of entity IDs as strings. The optionalallow_excludeboolean defaults tofalse. Configuration schema
A saved selection uses version 2, with filters keyed by contextual filter
ID. Each filter has a list of ids and a match value of any or all.
The optional mode is include or exclude. A missing or unknown mode uses
include. Exclusion uses any and becomes inclusion if the display no
longer allows it.
Integer IDs are stored as positive integers. String IDs are nonempty strings
of ASCII letters, digits, underscores, dots, and hyphens. Numeric-looking
string IDs such as '42' stay strings. Views Reference serializes the
containing data array on the field item. This example shows the decoded data.
data:
sift_terms:
version: 2
filters:
tid:
ids: [12, 34]
match: any
mode: exclude
type:
ids: ['article', 'page']
match: anyAll PHP classes and services are internal and may change in minor releases.
- Filter this list is missing. Check that the field enables Sift filters and that the chosen display has a supported contextual filter enabled in Sift.
- Sift is missing in the Views UI. Run
drush updbafter upgrading from an earlier beta. Open Advanced → Other on the display. - A selection is missing. Reopen the content item and check whether the entity still exists and is in an allowed bundle. Sift filters out IDs outside the allowed bundles. If all selected IDs fail the View's validation, Views uses its configured failure action. If the Sift bundle list is narrower and no IDs qualify, Sift skips the selection.
- The selection disappears while paging. Enable Use AJAX on the View display. Sift carries the current selection through AJAX paging.
Why use contextual filters? Site builders can reuse a View with different saved selections on each embed. Visitors can use exposed filters separately if the View provides them.
Does it work with Layout Builder blocks and Paragraphs? Yes. Use a Views Reference field on the block content or paragraph entity. The same setup works on other entities that have a Views Reference field.
Does Sift trust values from URLs? On normal page requests, Sift uses the selection saved on the field or the display default for an empty filter. It ignores Sift values in the query string.
On Views AJAX requests, field selections come from the browser. Sift caps the selection and checks that IDs exist and belong to allowed bundles. Visitors can change the values. Drupal core already lets visitors change contextual filter values on AJAX-enabled displays. Never use contextual filters, including Sift's, for access control.
Views Reference applies ?viewsreference[...] overrides on every request, so
visitors can turn off Sift for their own page view. Drupal core varies the
cache by URL for displays with contextual filters, so the override is confined
to requests for that URL.
Four Kitchens maintains this project. Use the issue queue for bugs and feature requests. See CONTRIBUTING.md for development and SECURITY.md for private reports.