E.Noorlander/CodePress
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e14f418e63d0ffda51621ea8fa0b181d923eb728
CodePress/guide/nl.codepress.md
Edwin Noorlander e14f418e63 Bump version to 1.6.0, update docs and guides to match current project state 
- version.php: 1.5.0 → 1.6.0 + changelog for media browser, editor,
  theme management, content move/rename, /-media/ prefix
- README.md/README.en.md: complete rewrite with current project structure,
  config format, admin features, CodeMirror, themes, quick start
- guide/nl.codepress.md, guide/en.codepress.md: comprehensive update
  matching all current admin routes, features, and project layout
- TODO.md: compiled from docs/TODO.md with completed/future items
2026-06-24 17:15:14 +02:00

581 lines
20 KiB
Markdown
Raw Blame History

# CodePress CMS Handleiding
## 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
- **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
- **JSON configuratie** in `config.json`
- Dynamische homepage instelling (`default_page`)
- 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.php`
- **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** - `config.json` bewerken met JSON-validatie
- **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
- 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.5.0)
└── vendor/ # Composer dependencies
```
## Configuratie
### Basis Configuratie (`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
}
}
```
- `active_theme` - Bepaalt welk thema uit `themes/` actief is
- `templates_dir` - Map met Mustache templates (`cms/templates`)
- `default_page` - Standaard pagina (bijv. `index`)
- `content_dir` - Map met content bestanden (wordt gewoonlijk niet gewijzigd)
### 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.php`
- **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` | Configuratie editor (`config.json`) |
| `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 |
### 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 `?page=index&lang=nl`
- **Pagina**: `?page=map/pagina&lang=nl`
- **Zoeken**: `?search=zoekterm`
- **Handleiding**: `?guide`
- **Taal wisselen**: `?lang=nl` of `?lang=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.php?route=dashboard`
- **Content bewerken**: `admin.php?route=content-edit&file=pagina.md`
- **Content nieuw**: `admin.php?route=content-new&dir=map`
- **Thema bewerken**: `admin.php?route=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.
## 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. **Automatisch**: Zet `"default_page": "index"` in `config.json` (of verwijder het veld)
2. **Handmatig**: Stel `"default_page": "pagina-naam"` in `config.json`
### 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.php?route=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.php?route=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.php?route=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.5.0** (codenaam: "Enhanced")
Releasedatum: 2025-11-26
## 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.
Reference in New Issue View Git Blame Copy Permalink