# Product Updates Public Pages Documentation

**Last Updated**: 2026-03-28  
**Status**: Production Ready ✅

## Overview

This document describes all public-facing pages of the Product Updates CMS system, their structure, rendering logic, and how they display content to website visitors.

## Page Types

### 1. Main Listing Page

**URL**: `/produkt-updates`  
**File**: `v2/pages/produkt_updates.php`

#### Purpose

Displays the current month's updates prominently, shows recent improvements, and provides navigation to past months.

#### Content Structure

**Hero Section**:

- Page title (supports blue markup: `*text*` and `**text**`)
- Intro text (rich HTML content)
- Current month indicator

**Big Features Section**:

- Displays up to `max_big_features` (default: 5) features from current month
- Each feature card shows:
  - Featured image
  - Tag badge (Neues Feature, Verbesserung, Bugfix)
  - Published date
  - Title
  - Description (truncated)
  - Platform icons (Desktop/Mobile)
  - "Mehr erfahren" link to individual page

**Small Improvements Section**:

- Displays up to `max_small_improvements` (default: 10) improvements
- Numbered list format (#1, #2, etc.)
- Each improvement shows:
  - Featured image thumbnail
  - Published date
  - Title
  - Description
  - Platform icons

**Past Months Archive**:

- Grid of past months (excluding current month)
- Each month card shows:
  - Month name
  - Featured image (from first feature)
  - Link to month page

#### Data Loading Logic

1. Loads JSON data using `findReadableDataFile()`
2. Falls back to writable location if readable is empty
3. Determines current month from `current_month` field
4. Aggregates all features and improvements across all months
5. Sorts by `published_date` (newest first)
6. Applies display limits from settings

#### Display Limits

Controlled by settings in JSON:

- `settings.max_big_features` (default: 5)
- `settings.max_small_improvements` (default: 10)

#### SEO Elements

- **Title**: "Ordio Updates [Month] | Produkt-Updates" or custom from settings
- **Meta Description**: Intro text + "Entdecke neue Features..."
- **Schema.org**: CollectionPage with ItemList
- **Open Graph**: website type, title, description, image
- **Canonical URL**: `https://www.ordio.com/produkt-updates`
- **RSS Feed Link**: `/produkt-updates/feed.xml`

---

### 2. Month Archive Page

**URL**: `/produkt-updates/[month-slug]` (e.g., `/produkt-updates/november-2025`)  
**File**: `v2/pages/produkt_updates_month.php`

#### Purpose

Displays all updates for a specific month in chronological order.

#### Content Structure

**Header**:

- Month name
- Published date
- Intro text
- Back link to main page

**Big Features Section**:

- All features for the month
- Sorted by `published_date` (newest first)
- Full feature cards with images

**Small Improvements Section**:

- All improvements for the month
- Sorted by `published_date` (newest first)
- Numbered list format

**Navigation**:

- Back to main page link
- Link to individual feature pages

#### Data Loading Logic

1. Validates month slug format (german-month-name-YYYY)
2. Redirects to main page if slug invalid
3. Loads JSON data
4. Finds month data by slug
5. Redirects to main page if month not found
6. Sorts features and improvements by date

#### SEO Elements

- **Title**: "[Month Name] Updates | Ordio Produkt-Updates"
- **Meta Description**: Month intro text + "Entdecke neue Features..."
- **Schema.org**: CollectionPage for the month
- **Open Graph**: article type, month-specific data
- **Canonical URL**: `https://www.ordio.com/produkt-updates/[month-slug]`

---

### 3. Individual Post Page

**URL**: `/produkt-updates/[post-slug]` (e.g., `/produkt-updates/meet-ordio-novi-ai-agent`)  
**File**: `v2/pages/post.php`

#### Purpose

Displays full content for a single feature with hero image, rich content, and detailed information.

#### Content Structure

**Hero Section**:

- Full-width featured image
- Tag badge (Neues Feature, Verbesserung, Bugfix)
- Published date
- Back navigation link

**Content Section**:

- Feature title (H1)
- Tag badge and date
- Full `page_content` (rich HTML)
- Platform icons (Desktop/Mobile)

**Navigation**:

- Back to month page link
- Back to main page link

**Related carousel** (after “Entdecke unsere Produkte: …”, before footer):

- **File**: `v2/base/produkt_updates_carousel.php` (included from `post.php`)
- **Data**: `produkt_updates_carousel_collect()` in `v2/helpers/produkt-updates-carousel-items.php`
- Lists other **big features** that have a `read_more_link` (dedicated post URL), **excluding** the current post, sorted by `published_date` descending (max 12 items)
- Each card: featured image (or placeholder), calendar icon + German publish date, title clamped to two lines, link to `/produkt-updates/{slug}`
- If no other posts exist, the section is omitted

#### Data Loading Logic

1. Extracts slug from URL
2. Searches all months for feature with matching `read_more_link`
3. Finds parent month
4. Redirects to main page if feature not found
5. Supports both `featured_image` (new) and `images` array (old) formats
6. Builds related carousel items from the same JSON (`produkt_updates_carousel_collect`)

#### Image Handling

- Uses `featured_image` field (new format)
- Falls back to `images[0]` (old format) for backward compatibility
- Images served via proxy endpoint: `/v2/api/serve-produkt-updates-image.php?file=...`
- Hero image displayed full-width
- Responsive image sizing

#### SEO Elements

- **Title**: "[Feature Title] | Ordio Produkt-Updates"
- **Meta Description**: Truncated description (155 chars max)
- **Schema.org**: BlogPosting with full metadata
- **Open Graph**: article type, feature-specific data
- **Article Tags**: Tag from feature data
- **BreadcrumbList**: Home → Produkt-Updates → Month → Feature
- **Canonical URL**: `https://www.ordio.com/produkt-updates/[post-slug]`

---

### 4. RSS Feed

**URL**: `/produkt-updates/feed.xml` or `/produkt-updates-feed.xml`  
**File**: `v2/pages/produkt-updates-feed.xml.php`

#### Purpose

Provides RSS 2.0 feed for all product updates, enabling subscription and syndication.

#### Content Structure

**Feed Metadata**:

- Title: "Ordio Produkt-Updates"
- Description: "Die neuesten Features und Verbesserungen von Ordio"
- Link: `https://www.ordio.com/produkt-updates`
- Language: de-DE
- Last Build Date: Current timestamp

**Items**:

- All big features from all months
- All small improvements from all months
- Sorted by `published_date` (newest first)
- Each item includes:
  - Title
  - Description (full HTML in CDATA)
  - Link to individual page (for features) or month page (for improvements)
  - Published date (RFC 822 format)
  - GUID (unique identifier)

#### Data Loading Logic

1. Loads JSON data
2. Aggregates all features and improvements
3. Sorts by published_date
4. Generates RSS XML structure
5. Sets proper Content-Type header

---

### 5. XML Sitemap

**URL**: `/sitemap-produkt-updates.xml`  
**File**: `v2/pages/sitemap-produkt-updates.xml.php`

#### Purpose

Provides XML sitemap for search engines to discover all product update pages.

#### Content Structure

**URLs Included**:

- Main page: `/produkt-updates`
- All month pages: `/produkt-updates/[month-slug]`
- All individual feature pages: `/produkt-updates/[post-slug]`

**Metadata per URL**:

- `loc`: Absolute URL
- `lastmod`: Published date or last_updated timestamp
- `changefreq`: "weekly"
- `priority`: 0.7

#### Data Loading Logic

1. Loads JSON data
2. Iterates through all months
3. Adds main page URL
4. Adds each month page URL
5. Adds each feature page URL (from `read_more_link`)
6. Generates XML sitemap structure

---

## Common Patterns

### Image Display

**Image Source**:

- All images use proxy endpoint: `/v2/api/serve-produkt-updates-image.php?file=filename.webp`
- Supports WebP auto-serving when browser supports it
- Fallback to JPEG/PNG if WebP not available

**Image Attributes**:

- `src`: Proxy URL
- `alt`: Feature/improvement title
- `loading`: "lazy" for below-fold images
- `fetchpriority`: "high" for hero images

### Blue Markup Syntax

**Supported Syntax**:

- `*text*`: Inline blue text (becomes `<span class="text-ordio-blue">text</span>`)
- `**text**`: Block-level blue text with line break (becomes `<span class="block text-ordio-blue">text</span>`)

**Usage**:

- Page titles (month `page_title` field)
- Main page title (settings)

### Date Formatting

**Display Format**:

- German format: "DD.MM.YYYY" (e.g., "10.11.2025")
- Uses `published_date` from feature/improvement or month

**Sorting**:

- Always sorted by `published_date` (newest first)
- Uses `strtotime()` for date comparison

### Platform Icons

**Display**:

- Desktop icon: Shows if "desktop" in platforms array
- Mobile icon: Shows if "mobile" in platforms array
- SVG icons with consistent styling

### Tag Badges

**Tags**:

- `neues-feature`: "Neues Feature" (blue)
- `verbesserung`: "Verbesserung" (green)
- `bugfix`: "Bugfix" (red)
- `update`: "Update" (purple)
- `sicherheit`: "Sicherheit" (orange)
- `performance`: "Performance" (yellow)

**Display**:

- Icon + label
- Color-coded badges
- Consistent styling across pages

## Navigation Flow

```
Main Page (/produkt-updates)
    ├── Month Page (/produkt-updates/november-2025)
    │   └── Feature Page (/produkt-updates/meet-ordio-novi-ai-agent)
    └── Feature Page (direct link)
```

**Back Navigation**:

- Feature page → Month page → Main page
- Month page → Main page
- Always available via "Zurück zu..." links

## Responsive Design

### Mobile Optimization

**Features**:

- Responsive grid layouts
- Touch-friendly buttons
- Optimized image sizes
- Collapsible sections
- Mobile-first CSS

### Desktop Optimization

**Features**:

- Multi-column layouts
- Hover effects
- Larger images
- Side-by-side content

## Performance Considerations

### Image Optimization

- Lazy loading for below-fold images
- WebP format when supported
- Responsive image sizing
- Proxy endpoint caching (1 year)

### Content Loading

- Single JSON file load per request
- Efficient data aggregation
- Minimal database queries (none - JSON-based)

### Caching

- Browser caching for images (1 year, immutable)
- No cache for JSON data (always fresh)
- ETag support for conditional requests

## Error Handling

### Missing Data

- Redirects to main page if month/feature not found
- Graceful degradation if images missing
- Fallback content if data empty

### Invalid URLs

- Slug validation
- Redirects for invalid formats
- 404 handling via redirects

## Related Documentation

- [SEO Implementation](./PRODUCT_UPDATES_SEO.md) - SEO and schema details
- [System Overview](./PRODUCT_UPDATES_SYSTEM_OVERVIEW.md) - Architecture
- [Storage System](./PRODUCT_UPDATES_STORAGE.md) - Data storage details