Frontend Templating System Manual

---

1. System Overview

The Frontend Templating System is responsible for rendering all public-facing genealogy pages, including:

• Individual profile pages
• Family group sheets
• Pedigree and relationship charts
• Other dynamic genealogy-related views

It operates by intercepting WordPress’s page-loading process and substituting the default theme templates with plugin-specific ones.

This design ensures LineagePress can display complex genealogical data within any WordPress theme — whether it’s a legacy (“classic”) theme or a modern block theme.

---

Key Responsibilities

• URL Rewriting – Generates SEO-friendly, human-readable URLs (e.g., /genealogy/person/I123/).
• Request Interception – Detects when a request corresponds to a genealogy page type.
• Data Querying – Retrieves genealogical data (individuals, families, events) from the database.
• Template Loading – Overrides WordPress’s template hierarchy to load plugin templates.
• Theme Compatibility – Allows themes to override plugin templates for complete styling control.

---

2. Architectural Flow

The system uses WordPress’s Rewrite API and template filters to seamlessly integrate LineagePress pages into the normal front-end rendering cycle.

---

Step-by-Step Flow

1. Rewrite Rule Registration (HP_Rewrite_Manager)
   • The class \LineagePress\Core\HP_Rewrite_Manager hooks into the init action.
   • It calls HP_Genealogy_Controller to register rewrite rules such as: add_rewrite_rule( 'genealogy/person/([^/]+)/([^/]+)/?$', 'index.php?hp_view=person&person_id=$matches[1]&tree_id=$matches[2]', 'top' );
   • These rules tell WordPress to treat URLs like /genealogy/person/I123/ as valid routes and set the necessary query variables.

---

2. Request Detection & Data Fetching (HP_Genealogy_Controller)
   • On each page load, the controller checks for query vars like hp_view.
   • If present, it identifies the request as a genealogy view.
   • The controller queries the database for all required data (e.g., person info, family relationships, life events).
   • This data is stored in a global or static registry (e.g., $hp_genealogy_data) for use by templates.

---

3. Template Injection (template_include filter)
   • The controller hooks into template_include.
   • If hp_view is detected, it replaces the normal template (e.g., page.php) with the plugin’s own file: /wp-content/plugins/lineagepress/public/templates/person-page.php
   • WordPress then proceeds to render this file instead of the theme default.

---

4. Template Rendering (e.g., person-page.php)
   • The selected template file is loaded and can access the $hp_genealogy_data variable.
   • Standard WordPress functions such as get_header() and get_footer() are used to wrap the template in the active theme’s structure.
   • The HTML is generated using the fetched data and CSS from the Theming System.

---

Visual Summary

URL Request
     ↓
WordPress Rewrite API
     ↓
Query Vars Set
     ↓
HP_Genealogy_Controller
     ↓
Data Fetched
     ↓
template_include Filter
     ↓
Plugin Template File Returned
     ↓
Template Renders Data

---

3. Core Components

includes/class-hp-rewrite-manager.php

• Entry point for frontend routing.
• Registers all custom genealogy URL structures.
• Delegates to HP_Genealogy_Controller for data and template handling.

---

includes/frontend/class-hp-genealogy-controller.php

Main orchestrator for frontend logic.
Handles:

• Custom rewrite rule registration.
• Request detection and query var management.
• Data retrieval from the database.
• Template override logic via the template_include filter.

---

public/templates/

Contains all built-in templates for displaying genealogy content.

Template	Purpose
person-page.php	Displays a single person’s profile, including family links and life events.
families-page.php	Shows a list or summary of family groups.
pedigree-chart.php	Displays an interactive or visual pedigree chart.

Each template is a PHP/HTML hybrid designed to integrate into any active WordPress theme.

---

4. Overriding Templates in a Theme

The LineagePress templating system supports full theme overrides to give developers total control over layout and styling.

How to Override a Template

1. Create a directory inside your theme: wp-content/themes/<your-theme>/lineagepress/
2. Copy the desired template from the plugin: wp-content/plugins/lineagepress/public/templates/person-page.php
3. Paste it into your theme’s new folder: wp-content/themes/<your-theme>/lineagepress/person-page.php

When WordPress loads the page, the HP_Genealogy_Controller will check if a corresponding template exists in the theme’s lineagepress directory.

• ✅ If found, it loads the theme’s version.
• 🔄 Otherwise, it falls back to the default plugin template.

---

Example Directory Structure

my-theme/
├── functions.php
├── style.css
└── lineagepress/
    ├── person-page.php
    ├── families-page.php
    └── pedigree-chart.php

---

✅ Result:
Theme developers can fully customize the layout and markup of all LineagePress frontend pages without modifying core plugin files.