Skill level: Beginner–Advanced
Time to complete: 10–20 minutes
Prerequisites: A directory registered in CPTListing with fields configured
What You’ll Learn
- What the default detail page shows and how it’s structured
- How to use the Template Layout Builder to arrange fields in columns
- How to set column widths and choose between 2 and 3 columns
- How to place the post content (body text) into a column
- How to set a per-directory max width for the detail page
- How to configure action buttons for email and URL fields
- How file attachment download buttons work on the detail page
- How featured images are controlled
- What happens when records are deleted (redirect URL)
- How advanced users can override card and single-item templates
- How to customise styling with CSS variables
The Default Detail Page
Every record in a Friendly CPT Listing directory automatically gets its own URL and detail page. You don’t need to create a template or configure anything for the basic version to work.
The default detail page:
- Uses your theme’s
get_header()andget_footer()— it looks like the rest of your site - Shows the record title as the page heading
- Shows the featured image (if the directory’s Featured Image setting is
templateorboth) - Displays all fields marked Template in the Fields tab, in the order they’re arranged there
- Shows the post content (the main editor content) below the fields, if any exists
- Renders email and URL fields as action buttons at the bottom (if configured — see below)
- Renders file attachment fields as download buttons (see below)
- Includes a “← Back to All [Plural Label]” link at the top to return to the listing
How Fields Are Displayed
On the detail page, each Template field is shown as a label-value pair:
Job Title: Senior Designer
Department: Creative
Email: jane@example.com
Special field types get special treatment:
- Email fields render as
mailto:links (protected against spam scrapers) - URL fields render as clickable links that open in a new tab
- Textarea fields are displayed in their own full-width section, with the field label as a sub-heading — useful for bio or description fields
- File Upload fields do not appear in the label-value list — they are rendered separately as download buttons (see below)
Template Layout Builder
The Template Layout Builder lets you organise detail page fields into columns using a drag-and-drop interface. Instead of a single vertical list of label-value pairs, you can present information side by side — for example, putting contact details in a left column and location details on the right.
To access it, go to Tools → Friendly CPT Listing, click Fields for your directory, and scroll down past the field table. The layout builder appears at the bottom of the Fields tab.
Choosing 2 or 3 Columns
At the top of the builder, select how many columns the detail page should use:
- 2 Columns — fields appear in a Left and Right column (the default)
- 3 Columns — fields appear in a Left, Middle, and Right column
Switching from 3 back to 2 columns automatically moves any fields in the Middle column back to the unassigned pool.
The Layout Pool and Column Zones
The Pool (shown as a dashed box above the columns) holds fields that are marked Template but not yet assigned to a column. When you first enable columns, all your Template fields start in the pool.
Drag a field chip from the pool into a column zone to place it there. Drag it back to the pool to unassign it. You can also drag between column zones directly.
Note: Fields must be marked Template in the field table above before they appear in the pool. The Content field (the post’s main body text) always appears in the pool regardless — see below.
If a field is in the pool (not assigned to any column), it falls back to appearing in the standard stacked layout below the column grid.
Per-Column Widths
Each column has a Width dropdown:
| Option | What it means |
|---|---|
| 1 part (narrow) | The column takes up 1 share of the available space |
| 2 parts | The column takes up 2 shares — twice as wide as a 1-part column |
| 3 parts (wide) | The column takes up 3 shares — three times as wide as a 1-part column |
The widths are proportional to each other. Think of the total width being divided into parts, and each column claiming its share:
- Two columns both set to 1 part: equal 50/50 split
- Left = 1 part, Right = 2 parts: the right column is twice as wide (33% / 66%)
- Three columns 1 part / 2 parts / 1 part: the middle column is twice as wide as the outer columns (25% / 50% / 25%)
- Three columns all set to 1 part: equal thirds
There’s no fixed total — the proportions are relative. Adding more parts to one column makes the others narrower in comparison. You can combine any mix of 1, 2, and 3 parts across your columns.
The Content Field
Content is a special built-in field representing the post’s main body text (what you write in the WordPress block editor or classic editor). It always appears in the layout pool and can be dragged into any column.
When placed in a column, the post content is rendered with full WordPress formatting (blocks, headings, images, etc.) — exactly as the_content() would output it.
If Content is not placed in any column, the post body is shown in its own full-width “About” section below the columns, as it was before the layout builder was added. This preserves backward compatibility — existing directories that don’t use the layout builder continue to work as before.
Content can also be shown on listing cards (as a short excerpt). Tick On Card for the Content row in the field table to enable this.
Saving the Layout
Click Save Layout at the bottom of the builder section. This is separate from the Save button that saves the On Card / Filter / Template checkboxes above — make sure to click the right button after making changes in the builder.
Detail Page Max Width
By default the detail page content area is constrained to 800px wide, which works well for text-heavy directories. You can change this per-directory from the Setup tab.
Go to Tools → Friendly CPT Listings → [your directory] → Setup and find the Detail Page Max Width field. Enter any valid CSS width value:
| Value | Effect |
|---|---|
800px | Default — 800 pixels wide |
1200px | Wider, good for 3-column layouts |
100% | Full width of the parent container |
none | No limit — the content stretches to fill whatever space the theme provides |
Leave blank to use the default 800px.
Tip for 3-column layouts: If you’re using 3 columns with wide content, consider setting the max width to 1200px or 100% so the columns have enough room to breathe.
File Download Buttons
If a record has any fields with type File Upload (set via Friendly CSV Importer’s upload data type, or the generic _cpt_upload from the Allow File Upload setting), and those fields are marked Template in the Fields tab, they appear as download buttons at the bottom of the detail page.
Each button:
- Is labelled with the field’s label (e.g., “Contract PDF”, “Attachment”)
- Links directly to the file in the WordPress Media Library
- Uses the HTML
downloadattribute to prompt the browser to download rather than navigate - Opens in a new tab as a fallback for browsers that handle certain file types natively
If the field has no attachment stored for a record, nothing is shown — the download section only appears when at least one file is present.
To show a file download button on the detail page:
- Ensure the field has type File Upload (set in Friendly CSV Importer → Manage Fields, or via the Allow File Upload setting)
- In the CPTListing Fields tab for your directory, tick Template for that field
To show a download link on listing cards: Tick On Card for the field instead (or as well). The link renders inline inside the card with the field label as its text. See the Fields and Filters KB for more.
Action Buttons
Action buttons are a way to make email and URL fields more prominent — instead of appearing inline in the field list, they’re displayed as large buttons at the bottom of the detail page.
This is controlled by the Action Type setting in the Setup tab (Tools → Friendly CPT Listings → Settings for your CPT).
| Action Type | Result |
|---|---|
| none | Email and URL fields show as inline links in the field list — no buttons |
| Email fields become a button (“Send Email”) at the bottom of the page | |
| url | URL fields become a button (“Visit Website”) at the bottom of the page |
| both | Both email and URL fields get buttons |
For a members directory where you want each profile to have a clear “Get in Touch” call to action, set Action Type to email. For a business directory where a “Visit Website” button is the main action, use url.
Note: A field only becomes an action button if it is also marked Template in the Fields tab. If it’s not marked Template, it won’t appear on the detail page at all.
Featured Image
The Featured Image setting in the Setup tab controls where the post’s featured image (if one is set) appears:
| Option | Where the image shows |
|---|---|
| none | Image is not shown anywhere |
| card | Image appears on listing cards only (180px tall, object-fit: cover) |
| template | Image appears on the detail page only (full width, responsive) |
| both | Image appears on both cards and the detail page |
Featured images are optional at the post level — if a record doesn’t have a featured image set, nothing is shown in its place.
The Back Link
At the top of every detail page, a back link reads:
← Back to All Members
The plural label (“Members” in this example) is pulled from the Setup tab. If you change the plural label there, the back link updates across all detail pages automatically.
The back link points to the first page of your listing — it doesn’t restore filter state or the visitor’s scroll position. For most use cases this is fine; visitors typically navigate back using the browser back button if they want to return to their filtered view.
Redirect URL for Removed Entries
When a post is deleted from WordPress, its URL becomes a 404. If visitors have bookmarked a detail page, or if other sites have linked to it, those links break.
The Redirect URL for Removed Entries field in the Setup tab lets you specify where deleted-entry URLs should redirect. Enter a full URL, such as:
https://yoursite.com/members/
When a post is deleted, Friendly CPT Listing registers a 301 redirect from the old URL to this destination. Visitors and search engines are sent to the specified URL instead of hitting a 404.
Leave this blank if you prefer the default 404 behaviour.
Advanced: Overriding Templates
The default templates work well for most cases. If you need custom markup — different field layout, additional data pulled in, custom HTML structure — you can override both the card template and the single-item template from your theme, without editing the plugin files.
Template overrides survive plugin updates. The plugin always checks your theme folder first.
Card Template Override
The card is the item displayed in the listing grid. To override it:
- Create a folder in your active theme called
directorypress/ - Copy the default template from the plugin:
wp-content/plugins/cptlisting/templates/shortcode/item-card.php - Place your copy at:
your-theme/cptlisting/item-card.php - Edit the file in your theme folder
Available PHP variables in the card template:
| Variable | Type | Contents |
|---|---|---|
$post_id | int | The WordPress post ID for this record |
$display_fields | array | The fields marked “On Card”, in display order |
$fields_by_key | array | All field definitions indexed by key |
$cpt_config | array | The full directory configuration (labels, settings, etc.) |
Single-Item Template Override
The single-item template renders the full detail page. You have two options:
Option 1 — Post-type-specific template (highest priority):
Create a file in your theme root named after your post type:
your-theme/single-{post_type_slug}.php
For example, if your post type slug is members:
your-theme/single-members.php
This follows the standard WordPress template hierarchy and gives you full control.
Option 2 — Shared single-item override (works for all CPTListing directories):
your-theme/cptlisting/single-item.php
Copy the default from:
wp-content/plugins/cptlisting/templates/single/single-item.php
This override applies to all directories registered with CPTListing, so it’s best used when you want a consistent custom structure across all your directories.
Template hierarchy (checked in this order):
your-theme/single-{post_type}.phpyour-theme/cptlisting/single-item.php- Plugin default template
Advanced: CSS Customisation
Friendly CPT Listing’s frontend stylesheet uses CSS custom properties (variables), which makes styling overrides clean and straightforward. You can change colours, spacing, and layout by redefining any of these variables in your theme’s stylesheet — no need to touch the plugin’s CSS files.
Add your overrides to your theme’s style.css or a custom CSS block:
:root {
/* Card appearance */
--cptl-card-bg: #ffffff;
--cptl-card-border: 1px solid #e0e0e0;
--cptl-card-radius: 6px;
--cptl-card-shadow-hover: 0 4px 12px rgba(0,0,0,0.12);
/* Button appearance */
--cptl-btn-bg: #0073aa;
--cptl-btn-color: #ffffff;
--cptl-btn-radius: 4px;
}
Inspect the listing or detail page in your browser’s developer tools to see all available custom properties.
CSS Hooks on the Detail Page
Every element on the detail page carries a BEM class and, where relevant, additional attributes and modifier classes you can target precisely.
Column positions — each column has a positional modifier class:
/* Style the left column differently from the right */
.cptl-single__col--left { background: #f9f9f9; padding: 16px; }
.cptl-single__col--right { padding: 16px; }
/* Middle column (3-column layouts only) */
.cptl-single__col--middle { border-left: 2px solid #eee; border-right: 2px solid #eee; }
Per-field targeting — every field row has a data-field attribute (the field key) and a data-type attribute (the field type):
/* Highlight a specific field by its key */
[data-field="membership_type"] .cptl-single__meta-label { color: #c07000; font-weight: 700; }
[data-field="membership_type"] .cptl-single__meta-value { background: #fff8e6; padding: 2px 6px; border-radius: 3px; }
/* Style all fields of a particular type */
[data-type="email"] .cptl-single__meta-value { font-family: monospace; }
Full class reference for the detail page:
| Element | Class / Attribute |
|---|---|
| Page wrapper | .cptl-single |
| Inner container | .cptl-single__container |
| Header | .cptl-single__header |
| Title (h1) | .cptl-single__title |
| Featured image wrapper | .cptl-single__featured-image |
| Featured image (img) | .cptl-single__featured-img |
| Column grid wrapper | .cptl-single__2col |
| Left column | .cptl-single__col .cptl-single__col--left |
| Middle column (3-col) | .cptl-single__col .cptl-single__col--middle |
| Right column | .cptl-single__col .cptl-single__col--right |
| Each field row | .cptl-single__meta-item + data-field="{key}" + data-type="{type}" |
| Field label | .cptl-single__meta-label |
| Field value | .cptl-single__meta-value |
| Overflow fields (no column) | .cptl-single__meta |
| Textarea section wrapper | .cptl-single__section |
| Content / textarea body | .cptl-single__content |
| Action buttons wrapper | .cptl-single__actions |
| Action button (link) | .cptl-action-btn |
| Downloads wrapper | .cptl-single__downloads |
| Download button (link) | .cptl-single__download-btn |
| Back link wrapper | .cptl-single__back |
Troubleshooting
Detail pages return a 404
- Flush your rewrite rules. Go to Settings → Permalinks and click Save, or use the Flush Rewrite Rules button on the Directory Settings page.
- This is the most common cause — it’s needed after registering any new native CPT.
Template override isn’t loading
- The folder must be named exactly
cptlisting(all lowercase, no spaces). - The file must be in your active theme, not a parent theme. If you’re using a child theme, put the overrides in the child theme folder.
- Verify the filename matches exactly:
item-card.phporsingle-item.php.
Action buttons aren’t appearing on the detail page
- Check the Action Type setting in the Setup tab — it must be set to something other than
none. - Verify the email or URL field is marked Template in the Fields tab — buttons only appear for Template fields.
- Confirm the field actually has a value in that record.
Fields are appearing in the wrong order on the detail page
- The order in the Fields tab controls the display order on the detail page. Drag to reorder and save.
The column layout isn’t appearing — fields still display in a single list
- Fields must be dragged into a column zone in the layout builder, then Save Layout must be clicked. If no fields are assigned to any column, the single-list fallback is used.
- Make sure the field is marked Template in the field table — only Template fields appear in the layout pool (except Content, which is always available in the pool).
The Content field isn’t appearing in the layout builder pool
- Content (post_content) always appears in the pool — it doesn’t require the Template checkbox. If you don’t see it, try refreshing the Fields tab page.
- If the Content field is in the pool but not being rendered on the detail page, check that the record actually has content in the WordPress editor.
The detail page looks very wide after removing the max-width
- Set a specific value in the Detail Page Max Width field in the Setup tab (e.g.
1200px) rather than leaving it blank or setting it tonone. This gives you control without depending on theme CSS to constrain the width.
The featured image isn’t showing
- Check that Featured Image in the Setup tab is set to
templateorboth. - Check that the individual post actually has a featured image set (edit the post in the WordPress admin and look for the Featured Image panel).
File download buttons aren’t appearing
- Confirm the field has type File Upload in Friendly CSV Importer’s Manage Fields screen (or is the
_cpt_uploadfield from the Allow File Upload setting). - Confirm the field is ticked as Template in Friendly CPT Listing’s Fields tab for this directory.
- Confirm the record actually has an attachment — if no file was uploaded or imported for this record, nothing shows.
- If using Friendly CSV Importer’s import to populate files, verify the CSV column was mapped as data type File Upload and the import log shows no errors for that column.
Next Steps
- Getting Started: Register a Directory and Place the Shortcode — if you’re setting up from scratch
- Fields and Filters: Configuring What Shows Where — control which fields appear on cards, in filters, and on the detail page