Recipe: Team / Staff Directory

Turn a single CSV file or Google Sheet into a live, searchable staff directory with circular avatar thumbnails. TableCrafter auto-detects image URLs in any cell and renders them as zoomable photos, so a directory needs no custom code, just one [tablecrafter] shortcode.

What you'll build

A people directory rendered from a spreadsheet where one column holds a photo URL. The finished table shows an avatar thumbnail per person, a global search box, per-column filters (e.g. by Department or Status), and clickable email links, all from a few CSV columns. Because TableCrafter reads the sheet live, HR can update the directory by editing a Google Sheet, no WordPress login required.

Step 1 — Prepare the spreadsheet

Create a sheet (or CSV) with one row per person. Add a column whose cells contain full image URLs ending in a supported extension. The server-side renderer accepts .jpg, .jpeg, .png, .gif, .webp, and .bmp (SVG is intentionally rejected for security). A realistic layout:

# team.csv
Photo,Name,Role,Department,Email,Status,Join Date
https://cdn.example.com/staff/sconnor.jpg,Sarah Connor,Project Manager,Operations,sarah@example.com,Active,2023-01-15
https://cdn.example.com/staff/jsmith.png,John Smith,Lead Developer,Engineering,john@example.com,Active,2022-11-20
https://cdn.example.com/staff/echen.jpg,Emily Chen,UX Designer,Design,emily@example.com,On Leave,2023-03-10
https://cdn.example.com/staff/mbrown.webp,Michael Brown,DevOps Engineer,Engineering,mike@example.com,Active,2023-05-01

Several columns get smart formatting for free once TableCrafter recognizes their values:

Step 2 — Publish the data source

TableCrafter fetches the data over HTTP, so the file needs a public URL. Two common options:

• CSV file: upload team.csv to your Media Library or any host. Any URL ending in .csv is parsed as CSV automatically.
• Google Sheet: use File → Share → Publish to web → CSV, or a link of the form https://docs.google.com/spreadsheets/d/<SHEET_ID>/.... TableCrafter detects the docs.google.com/spreadsheets/d/ pattern and routes it through the CSV parser.

Step 3 — Add the directory shortcode

Drop this into any page or post. It is a complete, working example using only real attributes:

[tablecrafter source="https://cdn.example.com/team.csv"
             include="Photo,Name,Role,Department,Email,Status"
             search="true"
             filters="true"
             sort="Name:asc"
             per_page="25"]

What each attribute does here:

• include pins both which columns appear and their order — Photo is listed first so the avatar leads each row.
• search renders a global search box across all visible columns.
• filters auto-generates per-column filter controls (Department and Status become handy dropdowns).
• sort="Name:asc" orders the directory alphabetically on first load.
• per_page="25" turns on pagination once you exceed 25 people.

Attribute reference

These are the shortcode attributes most relevant to a directory. Names are case-sensitive and match the column headers in your sheet.

Step 4 — Style the avatars

Every auto-detected photo is wrapped in <img class="tc-cell-image">. The bundled stylesheet already gives these thumbnails a small footprint, rounded corners, and a hover-to-zoom effect, so a directory looks polished out of the box:

/* shipped defaults for .tc-cell-image */
.tc-cell-image {
  max-height: 50px;
  border-radius: 4px;
  cursor: zoom-in;        /* hover scales the avatar up */
}

To make the photos perfectly circular like classic profile avatars, add this to your theme's Additional CSS (target your own container id if you set one):

.tablecrafter-container .tc-cell-image {
  width: 48px;
  height: 48px;
  object-fit: cover;
  border-radius: 50%;
}

Variations

• Hide internal columns: keep an ID or Salary column in the sheet but drop it from view with exclude="ID,Salary".
• Department sub-directories: publish one page per team and reuse the same source; let visitors narrow down with the auto-generated Department filter (no extra attribute needed since filters defaults to true).
• Downloadable roster: add export="true" to let staff download the directory. The export handler produces a genuine CSV, a real OOXML .xlsx workbook, and a valid PDF — not files merely renamed.
• Larger orgs: raise per_page (e.g. per_page="50") to page through hundreds of employees while keeping the page light.

How the image detection works

Understanding the rule helps you avoid surprises. On first render TableCrafter builds the table server-side, and for each cell it checks, in order: is this a boolean, an image URL, an email, an ISO date, or a plain URL? A value passes the image test when it ends in a supported raster extension (or is a data:image/...;base64 string). Matching values become a lazy-loaded <img>; everything else falls through to the next check and is finally HTML-escaped. The frontend script applies the same logic during live updates, additionally requiring an http/https prefix before it will render a remote image.

Troubleshooting

To experiment first, the bundled sample at WP Admin → TableCrafter ships an "Employee List (CSV)" demo you can point a shortcode at before wiring up your own sheet.

Next steps

Add download buttons to your roster with export-data.html, or learn the full source-URL rules for live spreadsheets in google-sheets-source.html.