# 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.

Source: https://www.jpkc.com/db/en/guides/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:

- WordPress **6.9+** and PHP **8.3+**
- [Advanced Custom Fields Pro](https://www.advancedcustomfields.com/) (v6.0+)
- [ACF Quick Edit Fields](https://wordpress.org/plugins/acf-quickedit-fields/) (for inline editing)

Optional: [WPML](https://wpml.org/) for multilingual references (German translations are included).

### Installation

1. Download the latest release ZIP from the [GitHub Releases page](https://github.com/JPKCom/jpkcom-acf-references/releases).
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:

```bash
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):

```text
[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:

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

Taxonomies can be rendered separately:

```text
[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

- Source code on GitHub: <https://github.com/JPKCom/jpkcom-acf-references>
- API documentation (PHPDoc): <https://jpkcom.github.io/jpkcom-acf-references/docs/>
- Requirements: [ACF Pro](https://www.advancedcustomfields.com/), [ACF Quick Edit Fields](https://wordpress.org/plugins/acf-quickedit-fields/)
- [This project's changelog](https://www.jpkc.com/db/en/changelog/jpkcom-acf-references/)