Presentation services

Pre-release classification (0.6.x); confirmed at 1.0.

The Hype5 Stage theme calls a number of Hype5 Theater PHP services directly to build its front page, menus and restyled templates. Any theme can call the same services. This page lists every plugin service that Hype5 Stage calls (found in inc/theater.php, its single templates and its hype5-theater/ template overrides), says what each returns and whether it applies the plugin's public visibility rules, and classifies each as Stable or Internal.

• Stable — a public contract: documented behaviour that themes and add-ons may rely on. Changes go through deprecation.
• Internal — an implementation detail used by Hype5's own theme. It may change in any release. Third-party themes should use shortcodes, blocks, template overrides or the stable services instead.

Class names below are relative to the namespace Hype5\Theater.

Visibility rules referred to on this page #

"Enforces visibility" below means the service itself applies the relevant rules, so its output can be printed (escaped). "Does not enforce visibility" means the caller must not print its raw data.

Summary #

Stable services #

Display\Renderer::production_full(array $atts): string and Display\Renderer::person_full(array $atts): string #

The implementations of [hype5_production] and [hype5_person]; $atts are the shortcode attributes (id and display options). Return the full page composition as HTML, or an empty string.

Visibility: enforced. A production that is not published renders nothing unless the current user may read it; a password-protected production renders only its title and WordPress's password form until the password is entered; an unpublished reader's-language translation is never rendered for visitors (the requested production is shown instead). A person who is not published or whose profile is hidden renders nothing unless the current user may edit the person. Calling these is equivalent to do_shortcode('[hype5_production id="…"]'); other Renderer methods are the implementations of the other shortcodes and follow the same rules.

Frontend\Collections::render(string $type, array $attributes = []): string #

The productions, people or schedule collection as HTML — the same code as the collection shortcodes and blocks. Reads hype5_* URL parameters unless the attribute is set.

Visibility: enforced. Productions: published only; password-protected ones appear as cards with title, address, poster, genres, audience recommendation and premiere only. People: published, profile allowed and shown in the directory. Schedule: rows from ScheduleQuery::find() are kept only when their production is public to everyone (or, for a schedule filtered to one production, unlocked for this visitor), then formatted with ProductionSchedule::row(); withheld rows are dropped and venues are named only when published.

Frontend\Labels::get(string $key, ?string $locale = null): string #

A public text (see Labels). Plain text; escape at output. Empty string for an unknown key.

Frontend\Render::template(string $key, array $view, array $display): string #

Renders a registered template through the theme-aware resolver and the hype5/theater/render/before and after actions. Returns an empty string when the template is not found.

Visibility: not enforced — it renders exactly the view it is given. Pass only views prepared by the plugin (the $view an override received, ProductionCard::batch() items, ProductionSchedule::row() results). It does not load the plugin's stylesheets.

Frontend\Appearance::root(array $display, string $classes = ''): string #

The escaped attribute string of a Hype5 root element: class="hype5 hype5t-public {classes}" data-hype5-style="…" data-hype5-meta="…". $display must contain style_mode and meta_layout (any array from DisplayOptions does).

Frontend\TemplateRegistry::all(): array #

The template registry after the hype5/theater/templates filter: key => ['key', 'path', 'version', 'public']. Use it to compare an override's version with the plugin's.

Frontend\DisplayOptions::for_entity(int $id = 0, array $explicit = []): array #

The effective display options: $explicit, then the production's or person's own Display values ($id, or none for 0), then global Appearance, then layout defaults, then built-in defaults. Keys are the display options and layout keys; new keys may be added.

Visibility: n/a. It returns presentation settings only and reads the record's settings without checking its status.

Data\CollectionRequest::normalize(array $attributes = [], array $request = []): array #

Normalised collection arguments (see Queries). Pure; pass [] as $request to ignore the URL.

Data\ProductionQuery::find(array $args): array #

Productions for a collection: ['items' => WP_Post[], 'total', 'page', 'pages', 'args']. $args must be normalize() output plus context and a resolved order.

Visibility: partly. Only published productions are returned, but password-protected productions are included and the items are raw WP_Post objects. Do not print their content, excerpt or meta; pass the IDs to ProductionCard::batch().

Data\ProductionQuery::next(array $ids): array #

For each given production ID, its next scheduled or sold-out performance, keyed by production ID.

Visibility: partly. Productions that are not unlocked for this visitor are left out — but that admits a password-protected production for a visitor who has entered its password, which is wrong for cross-page output; pass only IDs that are public to everyone in that case (ProductionCard::batch() does). The values are raw schedule rows with internal fields (see below); never print them directly — format each with ProductionSchedule::row(). Translated production IDs are resolved to the original-language production, which owns the performances, and the result is keyed by the IDs you passed (Phase 5K).

Data\ScheduleQuery::find(array $args = []): array #

Performances matching the filters (limit, offset, production, venue, city, access, from, to, month, status, past, include_past); throws \InvalidArgumentException for invalid values.

Visibility: partly. Only performances of published productions without a password are returned, plus those of a password-protected production when the query is filtered to it and the visitor has unlocked it. Not checked: the reader's-language translation of the production, the venue's publication, and occurrence status (cancelled and postponed rows are included). The returned rows are raw database rows and contain internal fields — the internal note (notes), attendance (attendance_count), creation and change times, raw JSON columns, a legacy ticket_url, the ID of a possibly unpublished venue, raw ticket-offer rows (offers) and a raw replacement row (replacement). Raw schedule rows must never be printed directly. Format each row with ProductionSchedule::row(). The second and third parameters are internal; passing true as the second disables every publication check.

Data\ScheduleQuery::count(array $args = []): int #

The number of rows find() would match without limit, with the same predicates. Safe to print.

Data\Performances::display_date(array $row, string $format = 'j F Y · H:i'): string #

Formats a row's starts_at_utc in the row's own time zone with wp_date() and the given PHP date format. Uses only starts_at_utc and timezone. It does no visibility check; it only formats the date of a row the caller already has.

Frontend\ProductionSchedule::row(array $row, array $display, bool $registerAnchor = true): array #

Turns a raw schedule row into the prepared production.performance view (see Template overrides) and applies the hype5/theater/view/performance filter. Pass false as $registerAnchor when the row is not part of a schedule on the page.

Visibility: enforced. If the row's production is not unlocked for this visitor, the result is a withheld view (withheld => true, id 0, every other field empty); callers and templates must output nothing for it. For cross-page output (lists on other pages), additionally keep only rows whose production is public to everyone, as Collections::render() does: a visitor who has entered a password would otherwise see that production's dates on pages that may be cached for everyone. Otherwise internal fields are dropped, the venue is named only when published, names are in the reader's language, replacement links point only to the same production or a public one, and offers[].purchase is true only where a purchase link may be shown.

Frontend\ProductionCard::batch(array $ids, array $display): array #

Prepared production cards keyed by ID, as used by collections.production-card: id, title, url, image, teaser, genre, audience, premiere, premiere_label, next, credits (empty), historical_audience, protected.

Visibility: enforced. IDs that are not productions, or not published (unless the current user may read them), are dropped. A production that is not public to everyone — password-protected, or with a password-protected reader's-language version — gets a locked card with only title, address, poster, genres, audience recommendation and premiere: no teaser, next performance or audience figure, even after the password was entered. next is a prepared performance view. Translated IDs get next through their original-language production (Phase 5K).

Internal services #

Frontend\ProductionView::component(string $part, int $id, array $display): array #

Prepared data for one production component (title, teaser, introduction, image, cast, gallery, warnings, important_info, accessibility, visitor, partners, articles, review_quote, links, media), used internally by the renderer.

Visibility: enforced for the production itself. When the production is locked for this visitor — a password is still required (the first version with a password decides: the production, else its original, else its reader's-language version), or the production or its original is unpublished and the visitor may not read it — title returns the title, address and an empty teaser, image returns the poster (as WordPress shows them for a protected post), and every other part returns an empty array. Otherwise the data is returned as the production page uses it; for cast, unpublished person profiles are dropped and links to hidden profiles are omitted. The returned arrays are internal view shapes, not a documented contract. (Hype5 Stage calls it for the cast strip on its front page and in the production hero.)

Use instead: [hype5_production_cast id="…"] or Renderer::production_cast(); a production.cast / production.cast-row template override; the hype5/theater/view/production filter (component production.cast) to add or change fields; or GET /hype5-theater/v1/productions/{id}/credits for data.

Data\Performances::get(int $id): ?array #

One raw performance row by ID, without offers.

Visibility: not enforced at all — any production status, password-protected productions, internal note and attendance included. Hype5 Stage uses it inside its hype5/theater/view/performance filter only to compute date parts for a view the plugin has already prepared; the row is never printed.

Use instead: ScheduleQuery::find() (filtered by production or venue) followed by ProductionSchedule::row(), and Performances::display_date() for custom date formats.

Frontend\CollectionRouting::type(): string #

'productions', 'people' or 'schedule' when the current request is a built-in collection address, otherwise ''.

Use instead: is_post_type_archive('hype5t_production'), is_post_type_archive('hype5t_person') and get_query_var('hype5_collection') === 'schedule'.

Frontend\CollectionRouting::target(string $type): string #

The URL of the published collection page chosen in Appearance for productions, people or schedule, or '' (also '' while that page is being viewed).

Use instead: link to the built-in addresses — get_post_type_archive_link('hype5t_production'), get_post_type_archive_link('hype5t_person'), home_url('/?hype5_collection=schedule'). The plugin redirects them to the chosen page.

Hooks and constants used by Hype5 Stage #

Stage also reads the stored section settings directly (_hype5t_display post meta and hype5t_appearance, keys disabled_sections / {type}_disabled_sections). These storage formats are internal. No stable service reports whether a section is enabled; render sections through the plugin ([hype5_production], Renderer::production_full()), which applies the settings, or observe them with the hype5/theater/production/section/before action.

Rules for theme authors #

1. Prefer shortcodes, blocks and template overrides. They apply every visibility rule.
2. Never print a raw schedule row or a WP_Post from a query service. Format performances with ProductionSchedule::row() and productions with ProductionCard::batch(), and skip views with withheld.
3. In a production.performance override, output nothing when $view['withheld'] is set.
4. Do not build purchase links yourself; use offers[].purchase.
5. Wrap direct calls so that a missing plugin or a changed internal service cannot break the theme (Hype5 Stage checks HYPE5_THEATER_VERSION and catches exceptions).