Presentation services

Presentation API 1.0 — Hype5 Theater 0.7.0 (HYPE5_THEATER_API = '1.0'). Pre-release: the classification is confirmed at Theater 1.0. Tested with Hype5 Stage 1.0.2.

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). Since 0.7.0 the details are shown only where Visibility::presentable() allows them: on the production's own page after the password, and on any other page only for a production public to everyone (or to someone who may read it — an editor previewing a draft, a member of a private production — while it carries no password); a translation whose original is unpublished shows only its title. 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 by the hype5_production URL parameter or shown on that production's own page, unlocked for this visitor (a production attribute on another page is cross-page output, 0.7.0) — then formatted with ProductionSchedule::row(); withheld rows are dropped and venues are named only when published. The count uses the same rule as the rows (0.7.0).

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(). The next order and the city filter use only productions public to everyone (0.7.0), so a protected production is neither placed among dated ones nor matched by city.

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

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

Visibility: partly. On the production's own page, productions that are not unlocked for this visitor are left out — the version you pass decides which password applies (0.7.0). Anywhere else (0.7.0) only productions public to everyone get a row, so a visitor's entered password never adds a date to another page. 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 productions public to everyone are returned (since 0.7.0 also checking the reader's-language version on multilingual sites), plus those of a password-protected production when the query is filtered to it and the visitor has unlocked the version named by scope (default: production, so the rows of a protected production depend on the cookie on any page; pass 'scope' => 0 for cross-page output, or print rows only through row(), which withholds them there). Not checked: 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, int $scope = 0): 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 ($scope, 0.7.0: the production version a production-scoped reader shows the row on; when it is a version of the row's production, that version's password decides. Without $scope, on the production's own page the version shown there decides; anywhere else the row is withheld unless the production is public to everyone) (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.

Visibility service (Stable since 0.7.0) #

Hype5 Stage 1.0.2 calls the plugin's visibility rules directly, so that its own cross-page output follows exactly the rules described at the top of this page. From Theater 0.7.0 (presentation API 1.0) these methods are Stable: a public contract that themes and add-ons may rely on; changes go through deprecation. Check defined('HYPE5_THEATER_API') && version_compare(HYPE5_THEATER_API, '1.0', '>=') before relying on the 0.7.0 additions.

Data\Visibility::listed(int $productionId): bool #

Public to everyone: the production is published without a password, in the original language and in the version shown in the reader's language — and, since 0.7.0, the version whose ID is passed too. Use it for every output on a page that is not the production's own page, also after a visitor has entered a password.

Data\Visibility::own_page(int $productionId): bool (0.7.0) #

True on the production's own single page: the queried production is this production, or this production is the queried production's original-language version or its version in the reader's language (the versions whose password governs the page). Another language version shown on that page — a shortcode for a third language — is cross-page output. False in REST requests, feeds, archives and the administration; true for the page's /embed/ view and its own comment feed (both singular). Use it instead of comparing Identity::canonical() values.

Data\Visibility::presentable(int $productionId): bool (0.7.0) #

True when the production's details (sections, credits, dates, offers, teaser) may be shown at this point of the current request: on its own page, while it is unlocked and readable for this visitor; anywhere else, while it is public to everyone (or the user may read it — an editor previewing a draft, a member of a private production — and it carries no password; the result depends on who is logged in, never on a password cookie). Plugin renderers use it; a theme that prints production details itself should too.

Data\Visibility::identity_only(int $productionId): bool (0.7.0) #

True while this visitor may see only the production's identity on its own page: a password is still required, or the production or its original-language version is unpublished and the visitor may not read it.

Data\Visibility::unlocked(int $productionId): bool and Data\Visibility::password_required(int $productionId): bool #

Unlocked for this visitor: the original-language production is published, the version asked for is readable (published, or the user may read it — 0.7.0), and WordPress does not require a password from this visitor. The first version in the production's chain that carries a password decides — the version asked for, else the original, else the reader's-language version. Use them only on the production's own page.

Data\Visibility::has_password(int $productionId): bool #

True when any version in the production's chain carries a password — that is, when the page's output can depend on the visitor's password cookie. The version asked for always counts; the original and the reader's-language version count only while published, or for a logged-in user who may read them — so to visitors the password of an unpublished original neither protects a published translation nor shows that it exists (0.7.0; such a translation shows only its identity to them). Since 0.7.0 the plugin itself sends no-cache headers for such production pages (and for requests a hype5_production parameter scopes to them); Hype5 Stage 1.0.2 does the same, which is harmless.

Data\Identity::canonical(int $postId): int #

Internal. The original-language post of a production. Hype5 Stage uses it to recognise a production's own page across its language versions.

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).
6. Before printing production details yourself, ask Visibility::presentable(), and check HYPE5_THEATER_API (1.0 or later) before relying on the services added in Theater 0.7.0.

Supported combinations #