Skip to content

Portal rendering system refactor

Published on June 5, 2026

Last updated on June 8, 2026

Portal pages were refactored into a modular rendering system that separates data collection, presentation logic, and styling into independent components. This architectural change allows multiple portal views to coexist while sharing the same underlying dataset, making future portal experiments significantly easier to build and maintain.

One of the recurring challenges with the portal system was that every portal page combined data collection, query logic, rendering, and CSS into a single monolithic template. While this worked for the initial implementation, it made experimentation difficult because every new display style required duplicating large portions of code.

The portal architecture has now been split into three distinct layers:

Data layer

A dedicated data.php file now handles:

  • Portal taxonomy discovery
  • Taxonomy query construction
  • Content aggregation
  • Section organization
  • Metadata preparation
  • Entry counting
  • Shared portal datasets

Rather than each renderer rebuilding its own queries, all portal views now consume the same centralized dataset.

Example:

$portal_data = [
    'sections'        => $sections,
    'active_sections' => $active_sections,
    'total_entries'   => $total_entries,
    'section_order'   => $section_order,
    'section_labels'  => $section_labels,
    'map'             => $map,
];

This effectively turns portal rendering into a presentation problem rather than a query problem.

Renderer layer

Portal output is now separated into dedicated renderer templates.

Current renderers include:

Atlas View
The modern card‑based Knowledge Atlas layout. Features include: hero section, section navigation, statistics cards, responsive card grid, CPT‑specific metadata, featured images, and excerpts.

Index View
A utility‑oriented alphabetical browser inspired by the site index tool. Features include: alphabetical sorting, CPT filtering, dynamic checkbox controls, lightweight browsing experience, and administrative review workflow.

Example filtering behavior:

const active = Array.from(checkboxes)
    .filter(cb => cb.checked)
    .map(cb => cb.value);

This view is particularly useful during taxonomy review and portal auditing.

CSS layer

Portal styles were extracted from inline templates and moved into dedicated stylesheet files. Structure now resembles:

template-parts/
└── portal/
    ├── data.php
    ├── renderers/
    │   ├── atlas.php
    │   └── index.php
    └── css/
        ├── portal-atlas.css
        └── portal-index.css

Moving CSS into dedicated files immediately improved maintainability and established a pattern that can later be applied to other large templates across the site.

View switching framework

A rendering switcher was introduced, allowing multiple portal displays to coexist.

Example:

$view = $_GET['view'] ?? 'index';

switch ($view) {
    case 'atlas':
        include 'renderers/atlas.php';
        break;
    case 'index':
    default:
        include 'renderers/index.php';
        break;
}

This creates a foundation for future renderers without requiring changes to the portal query logic.

Future portal views

The new architecture makes several portal experiments possible without major refactoring:

  • Reader View (full content rendering)
  • Plain Text View
  • Directory View
  • Study Mode
  • Cover Block Rendering
  • CPT‑Specific Presentation Modes

Because all views now share the same data layer, future renderers can be developed independently and swapped in or out as needed.

Outcome

The primary achievement of this project was not the creation of a new portal design, but the transformation of the portal system from a single‑purpose template into a modular rendering framework. Future portal experiments now require creating a renderer rather than rebuilding an entire portal page, dramatically reducing development complexity and making the portal system far more flexible going forward.