KO – Project Hero for Divi 5

KO – Project Hero is a single, native Divi 5 module built for project-feature presentations that change as the visitor scrolls:

• The project photograph begins crisp and progressively blurs and darkens.
• The project photograph remains fixed while the scroll reveal is active.
• Shared Work Title 1 and Title 2 values independently scroll in from a selectable left or right starting side.
• The summary divider fades and grows from left to right.
• Summary Title and Summary Text fade into the completed composition.
• Reversing the page scroll reverses every effect.

There are no slides, links, autoplay controls, navigation dots, or background pan/zoom effects.

Editing the module

The complete WordPress post title remains the canonical project name. Title 1 and Title 2 are shared Work post fields, so staff enter the display split once and Project Hero can use the same values as other project views.

Edit both values directly in the KO – Project Hero module's Project Title Content group:

• Title 1
• Title 2

Either shared line may be intentionally blank. An empty stored value is different from a field that has not been migrated yet. When the Work post is saved, an actual change to this pair is synchronized into the registered shared post meta. The separate editable WordPress meta box was removed so staff have one title-editing surface.

Content tab

• Project Image
  • Project Image
• Project Title
  • Title 1
  • Title 2
• Project Summary Title
  • Project Summary Title
• Project Summary Text
  • Summary Text
• Accessibility
  • Hero Label
  • Honor Reduced Motion

Summary Title and Summary Text may be left empty. Empty fields do not reserve visual space.

Shared Work title data contract

The public data contract for project-title consumers is:

Post type: project
Title 1 meta: _ko_project_title_1
Title 2 meta: _ko_project_title_2
Canonical project name: post_title

Both meta fields are registered WordPress post meta with single string values. Consumers should check whether each key exists rather than treating an empty string as a missing value. When both keys exist, Project Hero treats the shared values as authoritative on the published front end, including an intentionally blank line.

The module's titleLineOne and titleLineTwo attributes remain the Visual Builder edit buffer and compatibility fallback. The Builder preview reads them directly so typing updates immediately. On save, only an explicitly changed, unambiguous title pair may synchronize into post meta. Partial, duplicate, or independently changed shared values are protected from overwrite and the result is recorded under Tools > Project Hero Titles.

Migration and rollback

Version 1.1.0 introduced a safe, idempotent one-time backfill for existing Work posts. It runs automatically once on a safe WordPress admin page request, recursively inspects stored Divi blocks, migrates explicit titleLineOne and titleLineTwo values only when a post has exactly one KO Project Hero, confirms the combined lines match the complete WordPress post title, and never overwrites an existing shared value.

The migration journals each value before writing it, verifies that the original post content remains unchanged, and remains safe to resume after an interrupted request. Tools > Project Hero Titles provides explicit run, verify, and rollback actions. Rollback handles each post's migration-created title set together: it removes the unchanged set or protects the entire set when any value was subsequently edited. The original module attributes remain untouched.

Design tab

• Hero Layout
  • Hero Height
  • Scroll Length
  • Scroll Smoothing
  • Image Focal Point – Horizontal
  • Image Focal Point – Vertical
• Background Blur
  • Final Blur
  • Final Image Darkening
  • Blur Begins At
  • Blur Completes At
• Title 1 Text
  • Font Size
  • Text Color
• Title 2 Text
  • Font Size
  • Text Color
• Project Summary Title Text
  • Font Size
  • Text Color
• Summary Text
  • Font Size
  • Text Color
• Title 1 Position & Scroll
  • Final Horizontal Position
  • Final Vertical Position
  • Title Width
  • Scroll From
  • Starting Offset
  • Scroll Begins At
  • Scroll Completes At
  • Final Opacity
• Title 2 Position & Scroll
  • The same direction, scroll, width, horizontal-position, and opacity controls as Title 1
  • Vertical Offset From Title 1
• Summary Position & Fade
  • Horizontal Position From Right
  • Vertical Position
  • Summary Width
  • Fade Begins At
  • Fade Completes At
  • Final Opacity
• Summary Divider
  • Show Divider
  • Divider Width
  • Divider Thickness
  • Final Opacity
  • Reveal Begins At
  • Reveal Completes At

These ten custom Design groups are intentionally kept together above Divi's native Sizing, Spacing, Border, Box Shadow, and other standard groups.

Each custom text field intentionally exposes only Font Size and Text Color. Font family, weight, style, line height, letter spacing, alignment, wrapping, direction, hyphenation, fill, stroke, columns, spacing, and text shadow remain fixed by the module and do not appear as staff settings.

Title 1 and Title 2 default to 120px on desktop, 80px on tablet, and 52px on phone. They use Helvetica Now Display at weight 900, with Arial Black and Arial fallbacks, and both complete at 90% opacity.

The default vertical positions keep the responsive composition balanced without reducing title size. Title 1 begins at 25% on desktop, 40% on tablet, and 38% on phone. The summary begins at 47% on desktop, 60% on tablet, and 58% on phone. These responsive anchors are approximately 100px higher than the preceding defaults at the validated viewports while preserving the title-to-Summary spacing. Title 2 retains its 1em vertical offset from Title 1. Responsive values already saved on an existing module remain authoritative; reset those device values to use the new defaults.

Both title widths default to 52% on desktop and 90% on tablet and phone. This preserves the narrower desktop composition while giving responsive titles enough room to avoid unnecessary wrapping.

Title 2 begins at 12% from the left on desktop and 10% on tablet and phone, keeping its 90% responsive width inside the content layer.

The Project Image focal point defaults to 50% horizontal and 50% vertical on desktop. Tablet and phone default to 75% horizontal and 50% vertical so right-weighted project subjects remain visible in tall responsive crops. Editors can still set each device independently.

Each title has its own Scroll From setting with From Left and From Right choices. Starting Offset remains a positive distance from the selected side, so negative values are not needed to reverse the title direction.

Project Summary Title defaults to 32px desktop, 28px tablet, and 24px phone with a fixed italic treatment. Summary Text defaults to 16px desktop and tablet, and 15px phone. The complete project summary block defaults to 25% width on desktop and 88% on tablet and phone, producing a stacked responsive composition below the wider titles.

At Divi's desktop breakpoint of 981px and wider, the title and summary content layer uses 90% width and is centered within a 1440px maximum width. The project image and its blur treatment remain full-width.

All “Begins At” and “Completes At” values are percentages of this module’s Scroll Length. The completed state remains visible until the sticky stage releases.

Scroll Smoothing controls how long the rendered sequence catches up to the visitor's latest scroll position. It defaults to 500ms, can be adjusted from 0ms to 2000ms, and uses 0ms for immediate scroll-linked motion. It does not lock, snap, or programmatically change page scrolling. Blur, both title lines, the divider, and the summary always use the same smoothed normalized progress, including when the visitor reverses direction.

Visual Builder behavior

The Visual Builder displays the completed composition as a static preview. It intentionally disables the sticky scroll story inside the editor so staff can select the module and adjust its fields without fighting the page scroll.

The Visual Builder reads Title 1 and Title 2 from the module fields so edits are visible immediately. Saving a changed pair synchronizes it to registered post meta on the server. Titles are never injected into the saved page by frontend JavaScript.

The saved front end uses one normalized, reversible scroll-progress value for the blur, title movement, divider reveal, and summary fade. Scroll smoothing applies only to that shared rendered progress, settles and stops after the configured catch-up duration, and is bypassed for reduced-motion visitors.

Accessibility

• The hero is exposed as a labeled region rather than a carousel.
• The image layer is decorative; all meaningful project information remains text.
• Honor Reduced Motion is enabled by default. Visitors requesting reduced motion receive the completed text immediately over a crisp, darkened image, and the extra sticky scroll length is removed.
• Title 1 and Title 2 are server-rendered as spans inside one coherent h1 heading.
• Server-rendered content remains visible if JavaScript is unavailable.

Requirements

• WordPress 6.8 or newer
• Divi 5
• PHP 7.4 or newer

The plugin stays inactive-safe when Divi is unavailable and shows an administrator notice instead of causing a fatal error.

Development

pnpm install --frozen-lockfile
pnpm run build
pnpm test
php -l ko-project-hero-divi-5.php
php -l includes/class-ko-ph5-module.php
php -l includes/class-ko-ph5-shared-titles.php
php tests/shared-titles-test.php
node --check assets/js/ko-project-hero-divi-5.js
node --check assets/js/ko-project-hero-divi-5-builder.js

Webpack compiles the Visual Builder bundle and synchronizes:

src/components/hero/module.json
modules-json/hero/module.json

The neutral architectural photograph under tests/assets/ exists only for local browser QA. It contains no client imagery or branding and is excluded from installable release ZIPs.

Release contents

An installable ZIP contains one top-level ko-project-hero-divi-5/ folder with:

assets/css/ko-project-hero-divi-5.css
assets/js/ko-project-hero-divi-5.js
assets/js/ko-project-hero-divi-5-builder.js
includes/class-ko-ph5-module.php
includes/class-ko-ph5-shared-titles.php
modules-json/hero/module.json
ko-project-hero-divi-5.php
readme.txt

Development source, tests, screenshots, generated QA imagery, dependencies, and repository metadata are not included.

Local source and extracted-package checks confirm release structure and static implementation. They do not substitute for an installed WordPress migration run, Divi editor save, frontend render, or rollback test. Those are reported separately as live runtime QA.

License

GPL-2.0-or-later.