Hype5 Docs

Hype5 Theater 0.7.0 · Beta — by invitation

Extension guidelines

Hype5 Theater is designed to be extended without being modified. Follow these rules and your add-on, theme or integration will keep working as the plugin evolves.

On this page

Choose the right interface

You want to… Use Avoid
Show Hype5 content in a page or template Shortcodes, blocks, Display\Renderer::production_full() / person_full(), Frontend\Collections::render() Your own queries on Hype5 meta and tables
Change markup A template override in your theme Output buffering and string replacement
Add data to a template The hype5/theater/view/{type} filter Editing plugin templates in place
Add a section, layout or option-list entry The add-on interfaces Changing stored Appearance options
Change a public text The label API and per-language overrides Translating the plugin's English source strings for wording changes
Read data from another system The public REST routes The private /hype5-theater/v1/app/* routes
React to changes WordPress's own hooks (save_post, edited_term, …) The Hype5 app's save actions alone — they fire only for saves made in the app

Rules

  1. Do not modify the plugin. Everything here is possible from your own plugin or theme. Edits to the plugin's files are lost on update.
  2. Prefer stable and public interfaces. Use interfaces marked Stable or documented as Public. If you must use an Internal service, wrap the call and fall back gracefully. See Architecture overview.
  3. Never bypass visibility. 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 marked withheld. See Presentation services.
  4. Never build purchase links yourself. Use the prepared offers[].purchase value.
  5. Escape at output. Values in a view are prepared for output, but escape every value you add. Values named html or image are prepared HTML and are printed as they are. Labels are plain text: escape them.
  6. Do not read or write storage formats directly. Post meta, options and custom tables are internal and may change. If you store your own data, use your own keys and prefix.
  7. Keep your values on rows through the documented mechanism. Extra keys on repeatable rows are kept by the editors; never rely on a client sending them, and never rebuild a stored row without its extra keys. See Add-ons → Saved row data.
  8. Filters must return their first argument (or a value of the same type). Where the plugin expects an array, another type is ignored.
  9. Respect capabilities. Check the plugin's capabilities before offering actions on Hype5 content. See Roles and capabilities.
  10. Guard against the plugin being inactive. Check defined('HYPE5_THEATER_VERSION') and compare versions — or, for the presentation services, HYPE5_THEATER_API (Theater 0.7.0 and later) — before calling plugin classes, and catch exceptions around direct calls.

Feature checks 

if ( defined( 'HYPE5_THEATER_VERSION' ) && version_compare( HYPE5_THEATER_VERSION, '0.7.0', '>=' ) ) {
    try {
        echo \Hype5\Theater\Display\Renderer::production_full( [ 'id' => $production_id ] );
    } catch ( \Throwable $e ) {
        // Fall back to your own output.
    }
}

// The presentation contract (Stable services, view shapes, hooks), since Theater 0.7.0:
if ( defined( 'HYPE5_THEATER_API' ) && version_compare( HYPE5_THEATER_API, '1.0', '>=' ) ) {
    $show_details = \Hype5\Theater\Data\Visibility::presentable( $production_id );
}

What Hype5 Theater does not provide

Ticket sales, seating, maps and geocoding are not part of the plugin, and presentation hooks do not change queries, visibility rules or stored data. An add-on that integrates such a service owns that functionality and its data.

Test against new versions

  • Read the changelogs and the compatibility policy.
  • Check System Status for outdated template overrides after every update.
  • Test with WPML or Polylang if your users run multilingual sites: shared data lives on the original-language post.
  • Test password-protected and unpublished productions: your output must not reveal their dates, offers or credits.