Hype5 Docs

Theme integration

Any theme can show Hype5 Theater content. Choose the lightest level of integration that gives you the result you want; each level keeps the plugin's visibility rules intact.

On this page

Levels of integration

Level What you do Good for
1. Nothing Activate the plugin. Its pages render with its own templates inside your theme's header and footer. Any theme, quickly.
2. Settings Turn on clean single templates, choose a style mode (Hype5, Hybrid, Minimal) and set colours in the Appearance studio. Matching your theme without code.
3. Tokens and CSS Set --hype5-* design tokens and scoped styles in your theme. Brand colours, radii, spacing and type.
4. Template overrides Copy plugin templates into your-theme/hype5-theater/ and change the markup. Structural changes to cards, heroes, casts, schedules.
5. Full integration Call presentation services for your own home page, menus or landing pages; add data with view filters. A dedicated theatre theme — see Hype5 Stage.

Level 2: settings

  • Clean single templates (Settings → Content) render productions, people and venues with the plugin's own single template instead of your theme's single-post layout. A theme that wants to keep its own single templates — while still printing the plugin's composition — returns true from hype5t_use_theme_single_template:
add_filter( 'hype5t_use_theme_single_template', '__return_true' );
  • Style mode: Hype5 (full styling), Hybrid (inherits more of the theme's typography and colour) or Minimal (functional layout and focus styles only).

Level 3: tokens and CSS

Hype5 output is wrapped in a .hype5 root. Tokens are output with zero specificity, so a theme can set any of them:

.hype5 {
  --hype5-primary: #713e68;
  --hype5-border: #d8ced6;
  --hype5-radius-md: 4px;
}

Scope component styles to .hype5 and use the stable component classes. See CSS and design tokens.

Level 4: template overrides

  1. Copy a public template, for example hype5-theater/templates/production/meta.php, to your-theme/hype5-theater/production/meta.php (a child theme wins over its parent).
  2. Keep the @version header and edit the markup. Templates receive only $view and $display.
  3. After each plugin update, check System Status: overrides are reported as Current, Review recommended (outdated) or Missing or malformed version. A major version change means the view data changed incompatibly.
  4. In a production.performance override, output nothing when $view['withheld'] is set.

See Template overrides for the registry of public templates and their data.

Level 5: full integration

For your own home page or menus, use the stable presentation services: ProductionQuery, ScheduleQuery, ProductionSchedule::row(), ProductionCard::batch(), Labels::get(), DisplayOptions::for_entity(). Link to collections with their built-in addresses — the plugin redirects them to the chosen collection pages:

$productions = get_post_type_archive_link( 'hype5t_production' );
$people      = get_post_type_archive_link( 'hype5t_person' );
$schedule    = home_url( '/?hype5_collection=schedule' );

Add your own prepared fields with view filters rather than computing them in templates:

add_filter( 'hype5/theater/view/production', function ( array $view, array $display ): array {
    if ( ( $view['component'] ?? '' ) === 'production.hero' ) {
        $view['my_theme'] = [ 'subtitle' => get_post_meta( (int) $view['id'], 'my_subtitle', true ) ];
    }
    return $view;
}, 10, 2 );

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 them with ProductionSchedule::row() and ProductionCard::batch() and skip withheld views.
  3. For lists that combine several productions, apply the public to everyone rule: a production is shown only while it is published without a password in its original and its reader's-language version.
  4. Never build purchase links; use offers[].purchase.
  5. Wrap direct calls so that a missing plugin or a changed internal service cannot break the theme: check HYPE5_THEATER_VERSION and catch exceptions.
  6. Do not write the plugin's options, meta or tables, and do not change its Appearance settings from the theme.

Hype5 Stage as an example

Hype5 Stage follows this guide:

  • a version gate (HYPE5_THEATER_VERSION ≥ 0.6.17, the production post type and the plugin's renderer class exist), which a site can switch off with the hype5_stage_theater_enhancements filter;
  • a wrapper around every call that falls back to the plain theme on any error;
  • overrides in hype5-stage/hype5-theater/ with matching version headers, and a hype5/theater/template/located filter that falls back to the plugin's template when the plugin's template has a newer major version or in the administration;
  • view filters that add fields under a stage key and never remove any;
  • the plugin's stylesheets in a CSS cascade layer, so the theme's component styles win without specificity contests while the site's Hype5 custom CSS still wins last.

Stage also reads some section settings and uses a few services that the plugin classifies as internal; those are documented risks, not a pattern to copy. See Hype5 Theater integration and Presentation services.

Applies to: Hype5 Theater 0.6.17, Hype5 Stage 1.0.2.