# CodePress CMS Handleiding

## Inhoudsopgave

- [Overzicht](#overzicht)
- [Functies](#functies)
- [Installatie](#installatie)
- [Projectstructuur](#projectstructuur)
- [Configuratie](#configuratie)
- [Content Structuur](#content-structuur)
- [Admin Console](#admin-console)
- [Templates](#templates)
- [URL Structuur](#url-structuur)
- [SEO Optimalisatie](#seo-optimalisatie)
- [Plugin Systeem](#plugin-systeem)
- [Content API](#content-api-voor-php-content-bestanden)
- [Analytics & Tracking](#analytics--tracking)
- [Veelgestelde Vragen](#veelgestelde-vragen)
- [Troubleshooting](#troubleshooting)
- [Beveiliging](#beveiliging)
- [Versie](#versie)
- [Ondersteuning](#ondersteuning)
- [Licentie](#licentie)

## Overzicht

CodePress CMS is een lichtgewicht, file-based content management systeem gebouwd met PHP (>=8.0). Werkt zonder database.

## Functies

### Navigatie
- Tab-style navigatie met Bootstrap 5 styling
- Dropdown menus voor mappen en sub-mappen
- Home knop met icoon
- Automatische menu generatie op basis van directory structuur
- Responsive design
- Breadcrumb navigatie met sidebar toggle
- Active state marking
- **Sidebar toggle** - Knop links van HOME in de breadcrumb om de sidebar te openen/sluiten. Het icoon wisselt tussen open en gesloten status. De keuze blijft behouden tijdens de sessie

### Content Types
- **Markdown (.md)** - CommonMark ondersteuning via `league/commonmark`
- **PHP (.php)** - Dynamische content met **Content API** (`$api` variabele)
- **HTML (.html)** - Statische HTML pagina's
- **Directory listings** - Automatische directory overzichten
- **Language-specific content** - `nl.` en `en.` prefix

### Zoekfunctionaliteit
- Volledige tekst zoek door alle content
- Resultaten met snippets en highlighting
- Directe navigatie naar gevonden pagina's
- SEO-vriendelijke zoekresultaten
- Search URL: `?search=zoekterm`

### Configuratie
- **Instellingenformulier** in admin paneel via `/admin/config`
- Dynamische homepage instelling via dropdown
- SEO instellingen (description, keywords)
- Author informatie met links
- Thema configuratie via `themes/` directory
- Language settings
- Feature toggles (auto_link_pages, search_enabled, breadcrumbs_enabled)

### Layout & Design
- Flexbox layout voor responsive structuur
- Fixed header met logo en zoekfunctie
- Breadcrumb navigatie
- Fixed footer met file info en links
- Bootstrap 5 styling
- Mustache templates (`cms/templates/`)
- Semantic HTML5 structuur
- **Dynamic layouts** met YAML frontmatter
- **Sidebar support** met plugin integratie en toggle functie via breadcrumb
- **Thema ondersteuning** via `themes/` map met theme.json per thema

### Admin Console
- Ingebouwd admin paneel op `/admin`
- **Dashboard** met statistieken (aantal pagina's, mappen, plugins) en snelle acties
- **Content beheer** - Bestanden browsen, uploaden, aanmaken, bewerken, hernoemen, verplaatsen en verwijderen
- **CodeMirror editor** met toolbar (vet, cursief, kop, link, afbeelding, lijst, media invoegen)
- **Media browser modal** in de editor voor het selecteren van afbeeldingen/bestanden
- **Map beheer** - Mappen aanmaken, hernoemen en verwijderen (alleen lege mappen)
- **Configuratie editor** - Instellingenformulier voor site configuratie (titel, startpagina, taal, SEO, auteur, features)
- **Thema beheer** - Thema's aanmaken, activeren, bewerken (kleuren, achtergrond) en verwijderen
- **Plugin beheer** - Overzicht, aanmaken, bewerken, configureren, in-/uitschakelen en verwijderen
- **Media beheer** - Uploaden en verwijderen van mediabestanden in `content/-assets/`
- **Gebruikersbeheer** - Gebruikers toevoegen, verwijderen, wachtwoorden wijzigen
- **Handleiding** - Ingebouwde documentatie met API referentie
- Session-based authenticatie met bcrypt hashing
- CSRF-bescherming, brute-force lockout (5 pogingen, 15 min)
- Standaard login: `admin` / `admin` (wijzig direct na installatie)

## Installatie

1. Upload bestanden naar webserver
2. Stel permissies in voor webserver
3. Voer `composer install` uit voor CommonMark dependency
4. Configureer `config.json` indien nodig
5. Toegang tot website via browser
6. **PHP ontwikkelserver**: `php -S localhost:8080 -t public` (gebruikt `cms/router.php`)

## Projectstructuur

```
codepress/
├── cms/                            # Core CMS engine
│   ├── core/
│   │   ├── class/
│   │   │   ├── CodePressCMS.php    # Hoofd CMS class (content, navigatie, search)
│   │   │   ├── Logger.php          # Gestructureerd logging systeem
│   │   │   └── SimpleTemplate.php  # Mustache-style template engine
│   │   ├── plugin/
│   │   │   ├── PluginManager.php   # Plugin lader en beheer
│   │   │   └── CMSAPI.php          # API voor plugin developers
│   │   ├── config.php              # Configuratie lader (merge met config.json)
│   │   └── index.php               # Bootstrap (autoloader, requires)
│   ├── lang/                       # Taalbestanden
│   │   ├── nl.php                  # Nederlandse vertalingen
│   │   └── en.php                  # Engelse vertalingen
│   ├── logs/                       # CMS logs
│   ├── templates/                  # Mustache templates
│   │   ├── layout.mustache         # Hoofd layout (CSS, structuur)
│   │   ├── assets/                 # Header, navigation, footer partials
│   │   ├── markdown_content.mustache
│   │   ├── php_content.mustache
│   │   └── html_content.mustache
│   └── router.php                  # PHP dev server router
├── admin/                          # Admin paneel
│   ├── config/
│   │   ├── app.php                 # Admin app configuratie (paden, timezone)
│   │   └── admin.json              # Gebruikers & security (bcrypt hashes)
│   ├── src/
│   │   └── AdminAuth.php           # Authenticatie (sessies, bcrypt, CSRF, lockout)
│   ├── templates/
│   │   ├── login.php               # Login pagina
│   │   ├── layout.php              # Admin layout met sidebar navigatie
│   │   └── pages/
│   │       ├── dashboard.php       # Dashboard met statistieken
│   │       ├── content.php         # Content overzicht met bestanden uploaden
│   │       ├── content-edit.php    # CodeMirror editor met toolbar en rename
│   │       ├── content-new.php     # Nieuwe content aanmaken
│   │       ├── content-dir-form.php    # Map aanmaken/bewerken
│   │       ├── content-move-form.php   # Content verplaatsen
│   │       ├── config.php          # Configuratie editor (JSON)
│   │       ├── plugins.php         # Plugin overzicht
│   │       ├── plugins-edit.php    # Plugin PHP broncode editor
│   │       ├── plugins-new.php     # Nieuwe plugin aanmaken
│   │       ├── plugin-config.php   # Plugin configuratie editor
│   │       ├── theme.php           # Thema beheer (aanmaken, activeren, bewerken)
│   │       ├── media.php           # Media beheer (uploaden, verwijderen)
│   │       └── users.php           # Gebruikersbeheer
│   └── storage/logs/               # Admin logs
├── cli/                            # CLI scripts & tests
├── content/                        # Content bestanden
│   ├── -assets/                    # Geuploade mediabestanden
│   ├── index.md                    # Standaard homepage
│   └── ...                         # Overige content
├── plugins/                        # CMS plugins
│   ├── HTMLBlock/                  # Custom HTML blokken in sidebar
│   ├── MQTTTracker/                # Real-time analytics en tracking
│   └── test/                       # Test plugin
├── public/                         # Web root
│   ├── index.php                   # Website entry point (media serving + CMS)
│   ├── admin.php                   # Admin entry point + routing
│   ├── .htaccess                   # Apache rewrite/security rules
│   ├── assets/                     # CSS, JS, favicons
│   │   ├── codemirror/             # CodeMirror editor (minified JS/CSS)
│   │   └── css/js/                 # Bootstrap, icons, app CSS/JS
│   ├── themes/                     # Geuploade theme achtergronden
│   └── manifest.json / sw.js       # PWA ondersteuning
├── themes/                         # Thema definities
│   ├── default/                    # Standaard thema
│   │   └── theme.json              # Kleuren, hoogtes, achtergrond
│   └── test/                       # Test thema
│       └── theme.json
├── config.json                     # Site configuratie
├── version.php                     # Versie informatie (1.6.0)
└── vendor/                         # Composer dependencies
```

## Configuratie

### Basis Configuratie

De site configuratie wordt beheerd via het **admin paneel** op `/admin/config`. Hier vind je een instellingenformulier met de volgende secties:

- **Algemene instellingen** - Site titel en startpagina (dropdown met beschikbare pagina's)
- **Taal** - Standaard taal en beschikbare talen
- **SEO** - Meta beschrijving en keywords
- **Auteur** - Naam en website
- **Features** - Auto-link pagina's, zoekfunctie, breadcrumbs, versie tonen

De configuratie wordt opgeslagen in `config.json`. Je kunt dit bestand ook handmatig bewerken voor geavanceerde opties zoals `active_theme`, `content_dir` en `templates_dir`.

### Voorbeeld `config.json`

```json
{
    "site_title": "CodePress",
    "content_dir": "content",
    "templates_dir": "cms\/templates",
    "default_page": "index",
    "active_theme": "default",
    "language": {
        "default": "nl",
        "available": ["nl", "en"]
    },
    "seo": {
        "description": "CodePress CMS - Lightweight file-based content management system",
        "keywords": "cms, php, content management, file-based"
    },
    "author": {
        "name": "E. Noorlander",
        "website": "https:\/\/noorlander.info"
    },
    "features": {
        "auto_link_pages": true,
        "search_enabled": true,
        "breadcrumbs_enabled": true
    }
}
```

### Thema Configuratie (`themes/<naam>/theme.json`)

```json
{
    "name": "Standaard",
    "header_color": "#0a369d",
    "header_font_color": "#ffffff",
    "header_height": "56",
    "navigation_color": "#2754b4",
    "navigation_font_color": "#ffffff",
    "nav_height": "42",
    "sidebar_background": "#f8f9fa",
    "sidebar_border": "#dee2e6",
    "background_image": "",
    "background_image_opacity": "100"
}
```

Thema's kunnen worden beheerd via het admin paneel: aanmaken, activeren, kleuren aanpassen, achtergrondafbeelding uploaden en verwijderen.

## Content Structuur

### Bestandsstructuur

```
content/
├── map1/
│   ├── submap1/
│   │   ├── nl.pagina1.md
│   │   └── en.pagina1.md
│   └── pagina3.html
├── map2/
│   └── pagina4.md
├── index.md
└── -assets/
    ├── afbeelding.jpg
    └── document.pdf
```

### Bestandsnamen

- Gebruik lowercase bestandsnamen
- Geen spaties - gebruik `-` of `_`
- Logische extensies - `.md`, `.php`, `.html`
- Unieke namen - geen duplicaten
- Language prefixes - `nl.bestand.md` en `en.bestand.md`

### Media Bestanden

Media bestanden (afbeeldingen, PDFs, video, audio) kunnen in elke `content/` subdirectory worden geplaatst en worden geserveerd via:

- **`/-media/pad/bestand.jpg`** - Media uit elke content subdirectory
- **`/-assets/bestand.jpg`** - Backward compatibility (oude URLs)
- Uploads via het admin paneel gaan naar `content/-assets/`

## Admin Console

### Toegang

- **URL**: `/admin`
- **Standaard login**: `admin` / `admin`

### Routes

| Route | Beschrijving |
|---|---|
| `login` | Inlogpagina |
| `logout` | Uitloggen |
| `dashboard` | Dashboard met statistieken |
| `content` | Content overzicht (browsen, uploaden) |
| `content-edit` | Content bewerken (CodeMirror editor) |
| `content-new` | Nieuwe content aanmaken |
| `content-delete` | Content verwijderen |
| `content-move` | Content verplaatsen naar andere map |
| `content-dir-form` | Map aanmaken of bewerken |
| `content-dir-rename` | Map hernoemen |
| `content-dir-create` | Map aanmaken (POST) |
| `content-dir-delete` | Map verwijderen (alleen leeg) |
| `config` | Configuratieformulier (titel, startpagina, taal, SEO, auteur, features) |
| `theme` | Thema beheer |
| `plugins` | Plugin overzicht |
| `plugins-new` | Nieuwe plugin aanmaken |
| `plugins-edit` | Plugin PHP broncode bewerken |
| `plugins-config` | Plugin configuratie bewerken |
| `plugins-toggle` | Plugin in-/uitschakelen |
| `plugins-delete` | Plugin verwijderen |
| `media` | Media beheer (uploaden, verwijderen) |
| `media-list` | JSON lijst van alle media (voor editor modal) |
| `users` | Gebruikersbeheer |
| `guide` | Handleiding (deze documentatie) |

### Editor Functionaliteit

De content editor (`content-edit`, `content-new`) bevat:

- **CodeMirror** syntax highlighting voor Markdown/PHP/HTML
- **Toolbar** met knoppen voor: vet, cursief, kop, link, afbeelding, lijst, media invoegen
- **Media browser modal** - Open via de "Media" knop om afbeeldingen/bestanden te selecteren
- **Bestandsnaam hernoemen** - Inline filename input met extensie badge
- **Layout selector** - Kies uit beschikbare layouts
- **Plugin per-page zichtbaarheid** - Selecteer welke plugins op deze pagina tonen
- **Upload en "Aanmaken" knoppen** zijn disabled totdat er input is
- **"Annuleren"** knop (i.p.v. "Terug") bij ongewijzigde wijzigingen

## Templates

### Template Variabelen

#### Site Info
- `site_title` - Website titel
- `author_name` - Auteur naam
- `author_website` - Auteur website
- `author_git` - Git repository link

#### Page Info
- `page_title` - Pagina titel
- `content` - Content (HTML)
- `file_info` - Bestandsinformatie
- `is_homepage` - Boolean: is dit de homepage?

#### Navigation
- `menu` - Navigatie menu
- `breadcrumb` - Breadcrumb navigatie
- `homepage` - Homepage link

#### Theme (uit theme.json)
- `header_color` - Header achtergrondkleur
- `header_font_color` - Header tekstkleur
- `header_height` - Header hoogte in pixels
- `navigation_color` - Navigatie achtergrondkleur
- `navigation_font_color` - Navigatie tekstkleur
- `nav_height` - Navigatie hoogte in pixels
- `sidebar_background` - Sidebar achtergrondkleur
- `sidebar_border` - Sidebar randkleur
- `background_image_css` - CSS voor achtergrondafbeelding
- `background_image_opacity` - Dekking van de overlay

#### Language
- `current_lang` - Huidige taal (nl/en)
- `current_lang_upper` - Huidige taal (NL/EN)
- `t_*` - Vertaalde strings

### Layout Opties

Gebruik YAML frontmatter om layout te selecteren:

```yaml
---
title: Mijn Pagina
layout: sidebar-content
plugins: HTMLBlock
---
```

### Beschikbare Layouts

- `sidebar-content` - Sidebar links, content rechts (standaard)
- `content` - Alleen content (volle breedte)
- `sidebar` - Alleen sidebar
- `content-sidebar` - Content links, sidebar rechts
- `content-sidebar-reverse` - Content rechts, sidebar links

### Meta Data

```yaml
---
title: Pagina Titel
layout: content-sidebar
description: Pagina beschrijving
author: Auteur Naam
date: 2025-11-26
plugins: HTMLBlock, MQTTTracker
---
```

## URL Structuur

### Frontend Pagina URLs
- **Home**: `/` of `/nl/`
- **Pagina**: `/nl/map/pagina`
- **Zoeken**: `?search=zoekterm` (via zoekformulier)
- **Handleiding**: `/nl/guide`
- **Taal wisselen**: `/nl` of `/en`

### Media URLs
- **Media**: `/-media/pad/naar/bestand.jpg` (uit elke content subdirectory)
- **Assets**: `/-assets/bestand.jpg` (uit content/-assets/, backward compatible)

### Admin URLs
- **Admin**: `/admin`
- **Dashboard**: `/admin/dashboard`
- **Content bewerken**: `/admin/content-edit?file=pagina.md`
- **Content nieuw**: `/admin/content-new?dir=map`
- **Thema bewerken**: `/admin/theme?edit=themanaam`

## SEO Optimalisatie

### Meta Tags

De CMS voegt automatisch meta tags toe:
```html
<meta name="generator" content="CodePress CMS">
<meta name="author" content="E. Noorlander">
<meta name="description" content="...">
<meta name="keywords" content="...">
```

### Security Headers

```http
X-Content-Type-Options: nosniff
X-Frame-Options: SAMEORIGIN
X-XSS-Protection: 1; mode=block
Referrer-Policy: strict-origin-when-cross-origin
Content-Security-Policy: default-src 'self'; script-src 'self' 'unsafe-inline'; ...
```

## Plugin Systeem

### Plugin Structuur

```
plugins/
├── HTMLBlock/
│   ├── HTMLBlock.php         # Plugin class (verplicht)
│   ├── config.json            # Configuratie (optioneel)
│   └── README.md              # Documentatie (optioneel)
├── MQTTTracker/
│   ├── MQTTTracker.php
│   ├── config.json
│   └── README.md
└── test/
    ├── test.php
    ├── config.json
    └── README.md
```

### Plugin Ontwikkeling

- **API toegang** via `CMSAPI` class - geeft toegang tot CMS configuratie, templates, menu
- **Sidebar content** met `getSidebarContent()` - retourneert HTML voor sidebar
- **Metadata toegang** uit YAML frontmatter via `CMSAPI`
- **Configuratie** via `config.json` - bewerkbaar via admin paneel
- **viewable** veld in config.json bepaalt of plugin zichtbaar is in sidebar
- **Per-page zichtbaarheid** - via de editor plugin selector per pagina

### Plugin Boilerplate

```php
<?php

class MijnPlugin
{
    private ?CMSAPI $api = null;
    private array $config;

    public function __construct()
    {
        $this->config = [
            'viewable' => true,
        ];
    }

    public function setAPI(CMSAPI $api): void
    {
        $this->api = $api;
    }

    public function getSidebarContent(): string
    {
        return '';
    }

    public function getConfig(): array
    {
        return $this->config;
    }

    public function setConfig(array $config): void
    {
        $this->config = array_merge($this->config, $config);
    }
}
```

### Beschikbare Plugins

- **HTMLBlock** - Custom HTML blokken in sidebar
- **MQTTTracker** - Real-time analytics en tracking via MQTT
- **test** - Voorbeeld/test plugin

### Bekende Issue: MQTTTracker Credentials

De MQTTTracker plugin slaat `broker_host`, `broker_port`, `client_id`, `username` en `password` op in plain text in `plugins/MQTTTracker/config.json`. Dit is een bekend openstaand security punt - bij een productieomgeving wordt aangeraden deze gegevens te externaliseren naar omgevingsvariabelen of een aparte credentials manager.

## Content API (voor PHP content bestanden)

PHP content bestanden (`.php` in de `content/` map) hebben toegang tot een `$api` variabele met de volgende methodes:

### Pagina's opvragen

```php
// Alle pagina's met titels ophalen
$pages = $api->getAllPages();
// Resultaat: ['index' => 'Home', 'over-ons' => 'Over ons', ...]

// specifieke pagina inhoud ophalen
$page = $api->getPage('over-ons');
// $page['title'], $page['content'], $page['path'], $page['layout'], $page['metadata']

// Controleren of een pagina bestaat
if ($api->pageExists('contact')) {
    // ...
}
```

### Navigatie

```php
// Menu structuur ophalen
$menu = $api->getMenu();
// Bevat geneste array met 'title', 'path', 'url', 'children'
```

### Configuratie

```php
// Configuratie waarde opvragen (punt-notatie)
$title = $api->getConfig('site_title');
$lang = $api->getConfig('language.default');
$seoDesc = $api->getConfig('seo.description', 'Standaard beschrijving');
```

### Huidige pagina

```php
// Huidige pagina titel
$pageTitle = $api->getCurrentPageTitle();

// Huidige pagina pad
$pagePath = $api->getCurrentPagePath();

// Check of dit de homepage is
if ($api->isHomepage()) {
    echo 'Welkom!';
}
```

### URLs en taal

```php
// URL bouwen voor een pagina
$url = $api->buildUrl('over-ons', 'nl');

// Huidige taal
$lang = $api->getCurrentLanguage();

// Beschikbare talen
$languages = $api->getAvailableLanguages();

// Site titel
$title = $api->getSiteTitle();
```

### Vertalingen en zoeken

```php
// Vertaling ophalen
$label = $api->t('home');

// Zoekresultaten (als er gezocht wordt)
if ($api->isSearching()) {
    $results = $api->getSearchResults();
}
```

### Voorbeeld PHP content bestand

```php
---
title: Pagina Overzicht
layout: content
---
<h1>Alle Pagina's</h1>
<ul>
<?php foreach ($api->getAllPages() as $path => $title): ?>
    <li><a href="<?= $api->buildUrl($path) ?>"><?= htmlspecialchars($title) ?></a></li>
<?php endforeach; ?>
</ul>
```

## Analytics & Tracking

### MQTT Tracker

- Real-time page tracking via MQTT broker
- Session management
- Business Intelligence data
- Privacy aware (GDPR compliant)
- MQTT integration voor dashboards
- Optioneel: visitor tracking, page views, performance metrics, user flows

## Veelgestelde Vragen

### Hoe stel ik de homepage in?

1. Ga naar **Configuratie** in het admin paneel (`/admin/config`)
2. Selecteer de gewenste pagina in het **Standaard/startpagina** dropdown
3. Klik op **Configuratie opslaan

### Hoe werkt de navigatie?

- **Mappen** worden dropdown menus
- **Bestanden** worden directe links
- **Sub-mappen** worden geneste dropdowns
- Alleen bestanden zonder taalprefix tonen in het menu

### Hoe voeg ik nieuwe content toe?

1. Via het admin paneel: `/admin/content-new`
2. Of upload bestanden naar de `content/` map
3. Organiseer in logische mappen
4. Gebruik juiste bestandsnamen en extensies

### Hoe verplaats ik een bestand of map?

1. Ga naar `/admin/content`
2. Klik op "Verplaatsen" naast het item
3. Selecteer de doelmap
4. Bevestig de verplaatsing

### Hoe maak ik een nieuw thema?

1. Ga naar `/admin/theme`
2. Voer een naam in en klik "Aanmaken"
3. Pas kleuren, hoogtes en achtergrond aan
4. Activeer het thema

## Troubleshooting

### Pagina niet gevonden (404)

1. Controleer bestandsnaam en pad
2. Controleer bestandsextensie (.md, .php, .html)
3. Controleer permissies van bestanden
4. Controleer of het bestand de juiste taalprefix heeft (`nl.` of `en.`)

### Navigatie niet bijgewerkt

1. Herlaad de pagina
2. Controleer content map structuur
3. Controleer bestandsnamen (geen spaties)
4. Bestanden met taalprefix worden alleen getoond in de juiste taalmodus

### Admin paneel niet toegankelijk

1. Controleer of de sessie nog geldig is
2. Bij lockout: wacht 15 minuten of wis `admin/config/admin.json` lockout data
3. Controleer CSRF token (herlaad de pagina)

## Beveiliging

- **CSRF-bescherming** via tokens op alle admin formulieren
- **Brute-force lockout** na 5 mislukte pogingen (15 minuten blokkade)
- **Bcrypt password hashing** voor gebruikerswachtwoorden
- **Path traversal preventie** via `realpath()` en prefix-controle
- **Directe content toegang** geblokkeerd (403 Forbidden)
- **Security headers** voor alle pagina's
- **PHP uitvoering** in content directory geblokkeerd
- **Bestandsupload restricties** op toegestane extensies

## Versie

Huidige versie: **1.6.0** (codenaam: "Enhanced")
Releasedatum: 2026-07-14

## Ondersteuning

Voor technische ondersteuning:
- **Git**: https://git.noorlander.info/E.Noorlander/CodePress
- **Website**: https://noorlander.info
- **Issues**: Rapporteer problemen via Git issues

## Licentie

CodePress CMS is open-source software onder dual-license: AGPL v3 voor open-source gebruik, commerciële licentie voor proprietary gebruik.