JPKCom DB
View on GitHub

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 for multilingual references (German translations are included).

Installation

  1. Download the latest release ZIP from the GitHub Releases page.
  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'.

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).
  • Updates & security: The plugin updates securely via GitHub with SHA256 checksum verification; notices appear under Dashboard → Updates and on the Plugins page.

Further reading