Resources · Feature guides

Custom fields

Out of the box, every event in Site Calendar has a title, description, date, venue, organizer, and categories. That's enough for a calendar of "what's on" — but the moment you want to track a fixture's home/away status, a course's age range, a class's skill level, or any other detail specific to your kind of events, you need custom fields. Site Calendar Pro lets you define unlimited custom fields, attach them to every event, surface them on the front-end, and filter the archive by them. This guide walks through the full workflow from creation to filtering.

  • You'll need: Site Calendar Pro 1.1.2 or later active, a clear idea of what data your events have in common beyond the built-in fields
  • Estimated time: 10 minutes to set up your first field; 30 minutes to map out a complete custom-field schema for a complex use case
  • Difficulty: Beginner for simple text fields; Intermediate when combining filters and front-end display rules

What custom fields are for

The built-in event schema covers the universal essentials: when, where, who's organising, what category. But every real-world calendar has domain-specific data that doesn't fit into those boxes. A sports club tracks home or away, opposition, league, and kit colour. A yoga studio tracks skill level, props needed, and instructor. A theatre tracks age guidance, running time, and interval length. None of those map cleanly onto title, date, or venue.

Custom fields fill that gap. You define each field once (give it a label, a type, and decide whether it's public), and from then on every event has that field in its editor sidebar. Visitors see populated fields on the single-event page; categories of visitors with the right interest can filter the archive by them.

Custom fields vs. categories vs. tags. Categories control colour-coding and broad grouping (Music, Family, Sport). Tags are free-form keywords for search. Custom fields are structured per-event data — typed, optionally required, optionally filterable, optionally public-or-internal. Use categories when you'd colour the chip differently. Use tags for SEO keywords. Use custom fields for the kind of detail you'd put in a database column.

Before you start — plan your schema

Five minutes of planning saves an hour of restructuring later. Before adding fields in the admin, write down on paper:

  1. What information do all (or most) of your events share? If it's only on 1 in 20 events, it probably belongs in the description rather than a custom field.
  2. For each piece of info, what's its type? Free text, number, date, URL, yes/no checkbox, or a fixed list of options (dropdown)? The right type determines validation, display formatting, and whether filtering works cleanly.
  3. Should visitors see it on the public event page, or is it for admin-only reference? Examples of internal-only fields: cost per attendee (for budgeting), supplier contact name, last reviewed date. Examples of public fields: difficulty level, age guidance, equipment needed.
  4. Should visitors be able to filter the archive by it? Filterable fields appear as chips above the calendar (e.g. "Show me only Beginner classes"). Only fields with a small, fixed set of values make sense as filters — free-text fields don't.

Aim for 3–8 custom fields per site. Fewer and you're underusing the feature; more and the event editor sidebar gets cluttered.

Step 1 — Open the Custom Fields settings

In your WordPress admin, go to Site Calendar → Custom Fields. This screen lists every custom field you've defined, with controls to add new ones, edit existing ones, and reorder how they appear in the event editor.

[Screenshot: Site Calendar → Custom Fields admin screen showing the list of defined fields with type, public/internal status, and filterable status columns]
Each field shows its label, type, public visibility, and whether it's enabled for archive filtering.

On a fresh Pro install, this list is empty. Click Add new field to begin.

Step 2 — Define your first field

The Add Field form asks for the following:

Label

The human-readable name shown in the event editor and on the front-end. Use sentence case ("Skill level"), not snake_case. This is the only required field.

Key

The internal database key, used to store the field's value in wp_postmeta. Site Calendar auto-generates this from the label (e.g. "Skill level" becomes skill_level), but you can override it. Keep it lowercase, alphanumeric with underscores, and don't change it after events have data — renaming the key orphans the existing values.

Type

One of:

  • Text — single-line free text. Good for things like "Instructor name" or "Opposition".
  • Textarea — multi-line text. For longer free-form content like "What to bring".
  • Number — integer or decimal. Good for prices (when not using tickets), capacities, distances, or ages.
  • Date — a date picker. Useful for fields like "Booking opens" or "Application deadline" distinct from the event's own start date.
  • URL — a single URL. Renders as a clickable link on the front-end. Good for "External booking link" or "Livestream URL".
  • Checkbox — yes/no toggle. Good for "Members only" or "Family-friendly".
  • Select — a dropdown of predefined options. Good for fields with a fixed vocabulary like "Beginner / Intermediate / Advanced".

For Select fields, you'll see a second textbox to enter the options, one per line.

Show on public event page

Tick this to display the field on the single-event page front-end. Untick for admin-only fields. Public fields appear in a structured details panel near the top of the event page, alongside the date and venue.

Enable archive filter

Tick this to allow visitors to filter the events archive by this field. Only meaningful for Select, Checkbox, and (less commonly) Text/Number fields with consistent values. When enabled, the field appears as a chip in the archive toolbar — visitors click it to show only events matching the chosen value.

Help text

Optional. A one-line note shown to admin users below the field in the event editor. Use it to clarify ambiguity ("Enter the home team's strip colour, not the away kit") or to nudge consistency ("Use sentence case").

A note on the Key field. The auto-generated key is correct in almost all cases. Only override it if you're integrating with an external system that expects a specific key name (e.g. importing data from another plugin where the key is already established). Once a field has data attached, changing the key creates a new empty field rather than renaming — the old values stay in the database but no longer surface in the editor.

Step 3 — Save and check the event editor

Click Save field. The field now appears in your list. Open any existing event (or create a new one) and look at the editor sidebar — there's a new Custom fields meta box containing your field.

[Screenshot: event editor sidebar showing the new Custom fields meta box with the just-created field rendered as its appropriate input type]
Custom fields appear in their own meta box in the event editor sidebar, after the default fields.

Fill in a value, save the event, and view it on the front-end. If you ticked "Show on public event page", the field's label and value now appear in the event details panel.

Step 4 — Add more fields and reorder

Repeat Step 2 for each piece of data you mapped out in planning. Back on the Custom Fields settings screen, drag the rows to reorder — this is the order they appear in both the event editor sidebar and on the front-end. Put the fields most editors will fill in first.

Worked example — a sports club

A cricket club might end up with:

  • Home or away (Select: Home / Away) — public, filterable
  • Opposition (Text) — public, not filterable
  • League (Select: 1st XI / 2nd XI / Sunday XI / Friendly) — public, filterable
  • Kit colour (Text) — public, not filterable
  • Tea organised by (Text) — internal only

Two filterable fields (Home/Away and League) give the front-end archive useful filter chips. The opposition name surfaces publicly. The tea organiser stays in the editor as an internal reference for the fixture secretary.

Worked example — a yoga studio

  • Skill level (Select: Beginner / Intermediate / Advanced / Mixed) — public, filterable
  • Style (Select: Vinyasa / Hatha / Yin / Restorative) — public, filterable
  • Instructor (Text) — public, not filterable
  • Props needed (Textarea) — public, not filterable
  • Capacity (Number) — internal (for room booking; tickets handle public capacity)

Two clean filter axes (Skill level and Style) plus three context fields visitors find useful when deciding which class to book.

Step 5 — Filter the archive by custom field

Custom fields marked as filterable appear automatically as chips in the events archive toolbar. Visitors click a chip to see only matching events; clicking again removes the filter.

[Screenshot: events archive showing the filter chip strip above the calendar grid, with "Skill level: Beginner" actively selected and the grid filtered accordingly]
Filterable custom fields appear as toggleable chips above the calendar. Multiple chips can be active at once for AND-filtering.

Filters combine with AND logic: selecting "Skill level: Beginner" and "Style: Vinyasa" shows only events that are both Beginner skill level AND Vinyasa style. Visitors can also combine custom-field filters with the built-in category and venue filters in the same archive view.

Filter URLs for sharing or linking

When a filter is active, the URL updates to include the filter parameters (e.g. /events/?cf_skill_level=Beginner). You can link directly to a filtered view from your homepage or navigation, useful for things like "View all beginner classes" or "Show our Sunday XI fixtures only" without making the visitor click through the filter chips themselves.

Front-end display of public fields

Public custom fields render automatically on the single-event page in a structured details panel. Each field shows as a labelled row (label on the left, value on the right) styled to match the rest of the event details. Field types render appropriately:

  • Text and Textarea render as plain text. Textareas preserve line breaks.
  • Number renders as the number. No automatic currency formatting (use a Ticket if you need a priced item).
  • Date renders in the site's configured date format.
  • URL renders as a clickable link with rel="noopener".
  • Checkbox renders as Yes or No (the label only appears when value is Yes, by default — see Display rules below).
  • Select renders as the chosen option label.

Display rules — hiding empty fields

By default, custom fields with no value are hidden on the front-end rather than showing an empty row. This means you don't need to populate every field on every event; only the ones with values surface publicly. If you'd rather show an empty placeholder ("Not specified"), use the pcal_custom_field_empty_display filter in a child theme or code snippet — see the developer reference below.

Reordering on the front-end

The order on the front-end matches the order on the Custom Fields settings screen. Drag fields up the list to surface the most important ones first.

Internal-only fields and the REST API

Fields with "Show on public event page" unticked are visible to logged-in admin users in the event editor but never rendered on the front-end. As of Lite 1.1.1.14, they're also filtered out of the public REST API response — meaning even if someone crafts a request to /wp-json/pcal/v1/events/123, internal-only fields aren't included in the JSON.

This is the right default for sensitive data (cost margins, supplier contacts, internal notes) but worth knowing if you have an external integration that needs to read those fields. For authenticated integrations needing internal field access, you'll need to register your own REST route with a proper permission_callback that authenticates against your own logic. See the REST API reference (forthcoming) for the pattern.

Editing or deleting a field

On the Custom Fields settings screen, click any field row to edit its label, help text, public/filterable status, or display order. Changing these is safe and doesn't affect existing event data.

Changing a field's type after events have data is risky — a Text field's content won't migrate cleanly into a Number or Date field, and a Select field with renamed options will leave existing events with stale values that don't match any current option. If you need to change the type, the safest path is: (1) create a new field of the new type, (2) manually copy values from the old field to the new on each event, (3) delete the old field.

Deleting a field removes it from the editor immediately. The values stored against past events remain in wp_postmeta until those events are deleted — they just stop surfacing in the admin or front-end. This is intentional: it lets you re-create the field later (with the same key) and recover the data, useful if a field is deleted in error.

Bulk-editing custom field values across many events. The CSV importer accepts custom field columns using the format cf_skill_level, cf_opposition, etc. — column name is cf_ followed by the field's key. This lets you bulk-update existing events by exporting a CSV, editing the custom-field columns in your spreadsheet, and re-importing. See CSV bulk import for the full workflow.

Custom fields and recurring events

When you set up recurrence on an event with custom field values, every generated occurrence inherits the parent event's field values. If you edit the value on the parent, all future occurrences pick up the change; past occurrences keep the value they were generated with (they're now independent records once they've been published in a calendar view).

This is usually what you want — every Tuesday yoga class is Beginner Vinyasa. If you need one specific occurrence to differ (e.g. a guest instructor week), open that occurrence after it's been generated and override the field value individually. The override sticks for that one date.

Troubleshooting

"The Custom fields meta box doesn't appear in my event editor"

Three checks: (1) Confirm you're running Site Calendar Pro 1.1.2 or later — custom fields were added in 1.1.2. (2) Confirm at least one custom field is defined at Site Calendar → Custom Fields; an empty list shows no meta box. (3) Check the screen options at the top right of the event editor — the meta box may have been hidden by a previous admin user. Tick "Custom fields" in screen options to re-show it.

"My filter chips aren't appearing on the front-end"

Verify the field has "Enable archive filter" ticked, and confirm at least one event has a value in that field. Filter chips with no matching events are hidden automatically — there's no point showing a filter that returns zero results. Also check that you're viewing the events archive page (where [pro_calendar] is placed), not a single-event page.

"Custom field values aren't being saved when I update an event"

Usually a security plugin filtering the POST request. Wordfence and similar tools sometimes block requests with unfamiliar field names. Whitelist the custom field keys in your security plugin, or temporarily disable it to confirm. If saving works without the security plugin, contact the security plugin's vendor about a more granular whitelist rule.

"A field I deleted still shows up in old events"

Field values are preserved in wp_postmeta even after the field definition is deleted, so they don't surface in the editor anymore but the data persists. To fully purge, you'd need to delete the matching postmeta rows directly via SQL — back up first, and only do this if you're certain you won't want to re-create the field later. The unused data is harmless if left in place.

"Multiple-select / multi-value fields aren't supported, but I need them"

Site Calendar's custom fields are single-value by design. For multi-value data (e.g. an event tagged with multiple skill levels), use either: (a) several Checkbox fields, one per option, or (b) categories or tags, which natively support many-to-one relationships. Multi-select Select fields are on the roadmap but not in the current release.

"How do I show custom field values inside the event description body?"

Use the shortcode [pro_calendar_field key="skill_level"] anywhere in the event description or in your theme. It outputs the field's value at that exact position, with no label — useful for inline references in body copy. The shortcode takes one attribute (key) and produces the raw value only.

Developer reference

For sites that need programmatic access to custom field values, the following functions are available:

// Read a custom field value for a specific event
$value = pcal_get_custom_field( $event_id, 'skill_level' );

// Get all custom fields defined on the site
$fields = PCAL_Custom_Fields::get_all();

// Get only the publicly-visible fields
$public = PCAL_Custom_Fields::get_public();

// Filter: customise how an empty field renders on the front-end
add_filter( 'pcal_custom_field_empty_display', function( $output, $field ) {
    return 'Not specified';
}, 10, 2 );

The full REST endpoint structure for custom fields will be documented in the forthcoming REST API reference article.

What's next

Stuck designing your custom-field schema? Email support@getsitecalendar.com with a description of your events and we'll suggest a field structure. Pro licence holders get priority response.