Hype5 Docs

Hype5 Theater 0.7.0 · Beta — by invitation

Template overrides

On this page

Every public part of Hype5 Theater's output is rendered by a registered PHP template that a theme can override. Templates receive prepared data only — they never query the database — so an override changes markup without touching visibility rules or queries. This page explains the lookup order, keys, version headers and the data each template receives.

Lookup order

For a template key, the plugin looks for the file in this order and uses the first that exists:

  1. child theme: {child-theme}/hype5-theater/{path}
  2. parent theme: {parent-theme}/hype5-theater/{path}
  3. plugin: hype5-theater/templates/{path}

The path is the key with dots replaced by slashes, plus .php: production.cast → production/cast.php, collections.productions.cards → collections/productions/cards.php.

Only registry entries marked public can be overridden. _internal/ templates and the integration shells single.php, single-block.php and collection-page.php are not override contracts. Copying a file that is not registered does nothing. Paths outside the theme folder, symbolic-link escapes and .. are rejected.

The filters hype5/theater/template/candidates and hype5/theater/template/located can choose among the existing candidates for a key, but cannot introduce another file.

How to override

  1. Copy the plugin template, for example hype5-theater/templates/production/meta.php, to {child-theme}/hype5-theater/production/meta.php.
  2. Keep the @version header and edit the markup.
  3. Check Settings → Advanced in the Hype5 app (or the System Status screen, wp-admin/admin.php?page=hype5t-status): each override is reported as Current, Review recommended (outdated) or Missing or malformed version.

Version headers

Each template declares @version X.Y.Z within its first 8 KB, followed by a line end or */. The version describes the template's data contract, not its styling. When the plugin raises the version of a template, an override with a lower version is reported as outdated: compare it with the new plugin template. A major version change (for example 1.x → 2.0.0) means the view data changed incompatibly.

Variables

A template receives two arrays and nothing else:

  • $view — prepared data for this template (below), already filtered by hype5/theater/view/{type}.
  • $display — the effective display options (see Shortcodes).

Useful helpers inside templates:

  • \Hype5\Theater\Frontend\Render::template($key, $view, $display) — render another registered template.
  • \Hype5\Theater\Frontend\Labels::get($key) — a public text (escape it).
  • \Hype5\Theater\Frontend\Appearance::root($display, $classes) — the root element attributes (class="hype5 hype5t-public …" data-hype5-style … data-hype5-meta …).

Escape every value at output. Values named html or image are prepared HTML from WordPress or the plugin and are printed as they are.

Registered public templates

Key Version View data
production.single 2.0.0 hero, sections (HTML)
production.hero 1.0.0 title, teaser, image and meta (HTML), schedule_url, archived
production.title, production.teaser 1.0.0 id, title, url, teaser, archived
production.image 1.1.0 image: id, html, url, link_label, caption, credit (name, url), lightbox
production.introduction 1.0.0 html
production.meta 1.0.0 id, component, facts (plain label ⇒ value)
production.cast 2.0.0 groups: key, title, rows
production.cast-row 1.0.0 profession, character, note, position, people (name, url, image, affiliation_name, affiliation_url)
production.gallery 2.0.0 images (as production.gallery-image), group
production.gallery-image 1.1.0 id, html, url, link_label, caption, credit, people (name, url)
production.schedule 2.0.0 groups (label ⇒ performances), archived, anchor
production.performance 1.1.0 see Performance view; 1.1.0 (Phase 5K) adds the withheld view, for which an override must output nothing
production.ticket-offers 1.0.0 the performance view: offers, active_offers, price_summary
production.important-info, production.warnings 1.0.0 items: title, text, kind (audience, technical, content)
production.accessibility 1.0.0 items: title, text, symbol
production.visitor 1.0.0 items (title, text), accessibility (HTML)
production.media 1.0.0 groups (key, title, items: title, description, url, embed), files (title, description, url, type, size, image_html)
production.partners 1.0.0 groups: type label ⇒ rows (name, url, logo, …)
production.articles 1.0.0 items (title, url, source, author, date_label, type_label, description, quote), quote_html
production.review-quote 1.0.0 item
production.links 1.0.0 items: label, url, description
person.single 2.0.0 hero, sections (HTML), elab
person.hero 1.0.0 title, image, meta (HTML), opening
person.name 1.0.0 id, title, facts
person.image 1.0.0 image (as production.image)
person.meta 1.0.0 facts
person.biography 2.0.0 html
person.gallery 2.0.0 images, group
person.current-productions, person.past-productions 1.0.0 heading, layout, groups of production cards
collections.productions, collections.people, collections.schedule 2.0.0 type, layout, groups, args, total, fields, navigation, show_count, count_label, empty_key, items_template
collections.productions.{cards,editorial,compact,list} 1.0.0 grouped production cards
collections.people.{grid,list,alphabetical} 1.0.0 grouped person cards
collections.production-card 1.0.0 id, title, url, image, teaser, genre, audience, premiere, premiere_label, next (performance view or null), credits, historical_audience, protected
collections.person-card 1.0.0 id, title, url, image, professions
collections.filters 1.0.0 fields (key, label, type, options, value, id), navigation
collections.pagination 1.0.0 navigation.links (label, url, current)
collections.empty-state 1.1.0 empty_key, args.active, navigation.reset
shared.section-header 1.1.0 title, level (2–6), meta

schedule.agenda, schedule.performance and shared.empty-state are registered but not used by the current output.

The authoritative list, including templates added by add-ons, is returned by \Hype5\Theater\Frontend\TemplateRegistry::all().

Performance view

production.performance receives:

Field Meaning
id, anchor Record ID and the HTML id for links (may be empty).
withheld true when the visitor may not see this performance. All other fields are then empty and id is 0. An override must output nothing in that case, as the plugin template does. The plugin's own lists already leave such rows out; the check matters when a theme formats rows itself.
past Whether it has started.
datetime Start in UTC, ISO 8601.
date, time Start in the performance's time zone, in the site's date and time formats.
venue, city, room Venue name and city only for a published venue.
status Label for sold out, cancelled or postponed; empty when scheduled.
events, access Event and accessibility/service labels.
replacement url and label of the replacement date, or null.
offers Prepared ticket offers: purchase (show a button), price, status_label, action_label, url, note, availability and the stored offer fields.
active_offers, price_summary Number of purchasable offers; price summary text.
production_title, production_url Added in the general schedule only.

Never build a purchase link where purchase is false.

Registering your own template 

add_filter('hype5/theater/templates', function (array $templates): array {
    $templates['production.extra'] = [
        'key' => 'production.extra',
        'path' => 'production/extra.php',
        'version' => '1.0.0',
        'public' => true,
    ];
    return $templates;
});

The file is looked up only in the theme folders and in the plugin's templates/ folder, in the order above. An add-on cannot supply a template file from its own plugin directory; a registered key whose file exists in none of these folders renders nothing. Add-ons usually render their own HTML from a section renderer, or point a layout at an existing template key.