JPKCom DB
View on GitHub (opens in a new tab)

JPKCom ACF References — Guide & Tips

Reference gallery with filtering built on ACF Pro — installation, custom post types, shortcodes, layouts and practical tips with JPKCom ACF References.

JPKCom ACF References is a reference gallery system with filtering built on Advanced Custom Fields Pro. It ships three custom post types (References, Locations, Customers), image galleries with a lightbox, client-side filtering, multiple layouts and shortcodes — aimed at portfolios, case studies and project showcases.

Guide

Requirements

Required:

Optional: WPML (opens in a new tab) for multilingual references (German translations are included).

Installation

  1. Download the latest release ZIP from the GitHub Releases page (opens in a new tab).
  2. In your admin panel: Plugins → Add New → Upload Plugin, choose the ZIP, Install Now, then Activate.
  3. Make sure ACF Pro and ACF Quick Edit Fields are active.

Alternatively upload via FTP to /wp-content/plugins/, or clone it for development:

cd /path/to/wordpress/wp-content/plugins/
git clone https://github.com/JPKCom/jpkcom-acf-references.git

On multisite the plugin is network-compatible (Network Admin → Plugins → Network Activate).

Getting started

After activation you'll see References, Locations and Customers menu items. Recommended flow:

  1. Create a location under Locations → Add New.
  2. Create a customer under Customers → Add New.
  3. Create a reference under References → Add New, fill the ACF fields (type, location, customer, gallery) and assign the taxonomies on the right.
  4. Add images to the ACF gallery field and publish — the reference appears in the archive at /references/.

Displaying references

Via shortcode (all attributes optional):

[jpkcom_acf_references_list type="1,5" customer="6,8" location="1,3,7,11" limit="10" sort="DSC" layout="cards" title="References"]

customer and location expect post IDs (visible in the admin URL, post=123). With interactive filter dropdowns:

[jpkcom_acf_references_list show_filters="true" show_filter="0,1,2" reset_button="true" layout="cards"]

Taxonomies can be rendered separately:

[jpkcom_acf_references_types id="3,7,21"]
[jpkcom_acf_references_filter_1 id="1,5"]
[jpkcom_acf_references_filter_2 id="2,8"]

Alternatively visit the archive at /references/ directly, or build custom output with WP_Query and post_type => 'reference'.

References as data: the Abilities API

Since version 1.2.0 the plugin registers three read-only abilities. The Abilities API is a WordPress core registry of machine-readable capabilities — AI assistants, MCP clients and REST automation read your references as structured data through it instead of scraping the page:

Ability What it answers
jpkcom-acf-references/list-filters which reference types, customers, locations and taxonomy terms exist on this site
jpkcom-acf-references/query-references a filtered, paginated list of references
jpkcom-acf-references/get-reference one reference in full

They live under /wp-json/wp-abilities/v1/; because they only read, they answer on GET. A logged-in user with the read capability is required — that includes subscribers.

Two points shape the behaviour:

  • Only references your own listing shows come back — by exactly the same rule [jpkcom_acf_references_list] applies. The short description and the image gallery are returned only for a reference whose page a visitor could actually open: one that redirects to an external URL and one whose expiry date has passed both have no public detail page. For those, these fields are withheld and the reason is stated in the answer.
  • Filtering by a value that does not exist on this site returns no references and names the value under unknown, rather than quietly returning everything. A filter that is partly recognisable still narrows by the part that was.

To switch it off entirely, in wp-config.php:

define( 'JPKCOM_ACFREFERENCES_ABILITIES', false );

jpkcom_acf_references_ability_capability raises the capability required; jpkcom_acf_references_ability_meta controls how the abilities are exposed (REST route, MCP visibility, annotations).

Tips & Tricks

  • Pick one of three layouts: layout="list" (default, compact), layout="cards" (grid with 16:9 images, hover zoom) or layout="images" (full-bleed overlay cards in 4:3). All respect prefers-reduced-motion.
  • Filter interactively without reloads: With show_filters="true" you expose a dropdown per taxonomy. Within a filter the logic is OR, between filters it is AND; a "Reset all filters" button clears selections. Filtering runs purely client-side in vanilla JS (no AJAX, no jQuery). The dropdowns require Bootstrap 5 JavaScript to be loaded.
  • Use the shortcode generator: Under References → Shortcodes you build shortcodes through a form with a live preview and copy-to-clipboard.
  • Image gallery with lightbox: A reference's ACF gallery field automatically renders a thumbnail grid with a lightbox modal on the single page (prev/next, arrow keys, Escape, image counter).
  • Disable/redirect the archive: Under References → Options you can disable the /references/ archive and redirect it via HTTP 307; single pages stay accessible.
  • Override templates (priority order): child theme (your-child-theme/jpkcom-acf-references/), parent theme (your-theme/jpkcom-acf-references/) or MU-plugin (mu-plugins/jpkcom-acf-references-overrides/templates/).
  • Extend paths programmatically: The filters jpkcom_acf_references_template_paths and jpkcom_acfreferences_file_paths let you prepend your own directories; jpkcom_acf_references_final_template allows overriding the final template dynamically.
  • Render ACF fields with Bootstrap 5 markup: jpkcom_render_acf_fields() outputs all ACF fields of a post; fetch template parts with jpkcom_acf_references_get_template_part( 'partials/reference/customer' ).
  • Multilingual with WPML: Via wpml-config.xml, references, locations, customers and taxonomies are translatable; fields carry appropriate strategies (translate/copy/copy-once). Update to version 1.1.0 if you run multilingual: before that, the shortcode filters returned nothing in every secondary language. A shortcode carries the default-language term ID, but it was searched for in translations whose meta holds the translated ID. Since 1.1.0 the three taxonomy filters use tax_query instead of a meta_query with LIKE over the serialised ACF values — which is also considerably faster, because a leading wildcard cannot use an index.
  • Non-numeric filter values: type, filter_1 and filter_2 expect term IDs. Since 1.1.0 anything else produces no filter rather than one that matches nothing — so a typo returns the unfiltered list instead of an empty page.
  • Updates & security: The plugin updates securely via GitHub with SHA256 checksum verification; notices appear under Dashboard → Updates and on the Plugins page.

Further reading