diff --git a/app/README.md b/app/README.md new file mode 100644 index 0000000..be1102d --- /dev/null +++ b/app/README.md @@ -0,0 +1,274 @@ +# Framework Documentation + +This directory contains the core framework for the file-based CMS. It provides a minimal, extensible foundation that can be customized via the `/custom/` directory. + +## Architecture + +The framework is a lightweight PHP-based routing system that: +- Converts URLs to filesystem paths +- Resolves language-specific content and slugs +- Applies templates to render content +- Serves static assets (styles, fonts, images) + +## Directory Structure + +``` +app/ +├── router.php # Main routing logic +├── static.php # Static asset server for /app/* resources +├── config.ini # Default framework configuration +├── vendor/ # Third-party dependencies +│ └── Parsedown/ # Markdown parser +└── default/ # Default templates and styles (fallback) + ├── templates/ + │ ├── base.php # Base HTML structure + │ ├── page.php # Single page/article template + │ └── list.php # Directory listing template + └── styles/ + └── base.css # Default base styles +``` + +## Core Components + +### `router.php` + +The main request router that handles all content requests. Key responsibilities: + +1. **Language Detection**: Extracts language from URL path (`/no/`, `/en/`) +2. **Slug Resolution**: Converts language-specific slugs to directory names using metadata +3. **Path Resolution**: Maps URLs to filesystem paths in `/content/` +4. **Content Loading**: Reads content files (`.md`, `.html`, `.php`) +5. **Template Application**: Applies appropriate template based on content type +6. **Rendering**: Outputs final HTML with base template + +**Key Functions:** +- `resolveLanguageSlugToName()` - Translates slugs to directory names +- `findContentFile()` - Locates content files with language variants +- `renderPage()` - Renders content with templates +- `parseMetadata()` - Parses INI metadata files + +### `static.php` + +Serves static assets from `/app/` directory. Handles requests for: +- `/app/styles/*` - Framework CSS files +- `/app/fonts/*` - Framework fonts +- `/app/default-styles/*` - Default stylesheet aliases + +Includes security checks to prevent path traversal attacks. + +### `config.ini` + +Default configuration for the framework: + +```ini +[languages] +default = "no" # Default language +available = "no,en" # Available languages +``` + +Can be overridden by `/custom/config.ini`. + +### `vendor/` + +Third-party dependencies: +- **Parsedown**: Markdown-to-HTML parser library + +### `default/` + +Fallback templates and styles used when custom templates are not provided. + +## Request Flow + +``` +1. User requests URL (e.g., /no/artikler/pasientinfo) + ↓ +2. Apache routes to /content/index.php + ↓ +3. index.php includes router.php + ↓ +4. router.php: + - Extracts language: "no" + - Resolves slug "artikler" → "artikler" directory + - Resolves slug "pasientinfo" → "pasientinfo" directory + - Checks if path exists in /content/ + - Determines content type (file or directory) + ↓ +5. For single article: + - Loads metadata.ini + - Loads article.no.md (or article.md) + - Applies /custom/templates/page.php (or default) + - Wraps with /custom/templates/base.php + ↓ +6. For directory listing: + - Scans directory for subdirectories + - Loads metadata.ini for each item + - Applies list template specified in metadata + - Wraps with base.php + ↓ +7. Outputs final HTML to browser +``` + +## Template System + +Templates can be overridden by placing files in `/custom/templates/`: + +### Base Template (`base.php`) +Wraps all content with HTML structure, header, footer, navigation. + +**Variables available:** +- `$title` - Page title +- `$content` - Rendered page content +- `$language` - Current language code +- `$metadata` - Page metadata array + +### Page Template (`page.php`) +Renders single articles/pages. + +**Variables available:** +- `$contentHtml` - Parsed HTML content +- `$metadata` - Article metadata +- `$language` - Current language code +- `$parentMetadata` - Parent directory metadata + +### List Templates +Render directory listings. Multiple variants: +- `list.php` - Simple list +- `list-grid.php` - Grid layout +- `list-card-grid.php` - Card grid with images +- `list-faq.php` - Expandable FAQ view + +**Variables available:** +- `$items` - Array of child items with metadata +- `$metadata` - Directory metadata +- `$language` - Current language code + +## Customization + +The framework is designed to be minimal and extensible. All customization should happen in `/custom/`: + +### Override Templates +Create files in `/custom/templates/` with the same name as default templates. + +### Override Configuration +Create `/custom/config.ini` to override default settings. + +### Add Custom Styles +Place CSS in `/custom/styles/` and reference in custom templates. + +### Add Custom Fonts +Place font files in `/custom/fonts/` and reference in CSS. + +### Add Translations +Create or edit `/custom/languages/[lang].ini` files. + +## Metadata System + +Content is configured via `metadata.ini` files placed in each directory. + +### Common Metadata Fields + +```ini +[metadata] +title[no] = "Norwegian Title" +title[en] = "English Title" +slug[no] = "norwegian-slug" +slug[en] = "english-slug" +summary[no] = "Norwegian summary" +summary[en] = "English summary" +date = "2024-10-15" +category = "Category Name" +tags = "tag1,tag2,tag3" +template = "list-card-grid" # For directories +show_in_menu = true +menu_order = 10 +``` + +### Metadata Inheritance +Child items inherit parent metadata when not specified. + +## Content File Resolution + +The router looks for content files in this order: + +1. `article.[language].md` (e.g., `article.no.md`) +2. `article.[language].html` +3. `article.[language].php` +4. `article.md` (fallback) +5. `article.html` (fallback) +6. `article.php` (fallback) +7. `page.[language].md` (for directory index) +8. `page.md` (fallback) + +## Language System + +### URL Structure +- Norwegian: `/no/artikler/pasientinfo` +- English: `/en/articles/patient-info` + +### Slug Translation +Slugs are resolved using metadata: +```ini +slug[no] = "pasientinfo" +slug[en] = "patient-info" +``` + +The router automatically translates URLs to filesystem paths regardless of language. + +### Translation Files +Located in `/custom/languages/`: +- `no.ini` - Norwegian translations +- `en.ini` - English translations + +Format: +```ini +key = "Translated text" +another_key = "More text" +``` + +Access in templates: `$translations['key']` + +## Security Considerations + +- **Path Traversal Protection**: `static.php` validates paths to prevent directory traversal +- **Input Sanitization**: URLs are sanitized before filesystem operations +- **Template Isolation**: Templates run in controlled scope with specific variables +- **No Database**: File-based system eliminates SQL injection risks + +## Performance + +- **No Caching**: Content is rendered on each request (suitable for low-traffic sites) +- **Performance Tracking**: Page generation time is measured and displayed +- **Static Assets**: Served directly by Apache when possible + +## Extending the Framework + +To add new features: + +1. **Custom Functions**: Add helper functions in custom templates +2. **New Template Types**: Create new template files in `/custom/templates/` +3. **Metadata Fields**: Add new fields to `metadata.ini` files +4. **Custom Routes**: Extend `router.php` (requires modifying framework) + +## Debugging + +Enable error reporting in `content/index.php`: +```php +ini_set('display_errors', 1); +error_reporting(E_ALL); +``` + +View page generation time at bottom of each page. + +## Requirements + +- PHP 8.3 or higher +- Apache with mod_rewrite enabled +- Write permissions on content directories (for future admin features) + +## Limitations + +- No built-in caching (regenerates pages on each request) +- No built-in admin interface (content edited via filesystem) +- No user authentication system +- No built-in search functionality +- Performance may degrade with very large content libraries diff --git a/app/default/languages/en.ini b/app/default/languages/en.ini new file mode 100644 index 0000000..761b54b --- /dev/null +++ b/app/default/languages/en.ini @@ -0,0 +1,12 @@ +; English translations +home = "Home" +categories = "Categories" +tags = "Tags" +read_more = "Read more" +read_article = "Read article" +read_full_answer = "Read full answer" +download_pdf = "Download PDF" +summary = "Summary" +footer_text = "Footer content goes here" +footer_handcoded = "This page was generated in" +footer_page_time = "ms" diff --git a/app/default/languages/no.ini b/app/default/languages/no.ini new file mode 100644 index 0000000..514bf0a --- /dev/null +++ b/app/default/languages/no.ini @@ -0,0 +1,12 @@ +; Norwegian translations +home = "Hjem" +categories = "Kategorier" +tags = "Stikkord" +read_more = "Les mer" +read_article = "Les artikkel" +read_full_answer = "Les hele svaret" +download_pdf = "Last ned PDF" +summary = "Oppsummering" +footer_text = "Bunntekst her" +footer_handcoded = "Denne siden ble generert på" +footer_page_time = "ms" diff --git a/app/default/templates/list-card-grid.php b/app/default/templates/list-card-grid.php new file mode 100644 index 0000000..ec5f1dd --- /dev/null +++ b/app/default/templates/list-card-grid.php @@ -0,0 +1,82 @@ + +
+ +
+ + +
+
+ +
+ + + <?= htmlspecialchars($item['title']) ?> + + +

+ + + +

+ +

+ + +

+ +
+ + + + + + + + +
+
+ +
+
+ + diff --git a/app/default/templates/list-faq.php b/app/default/templates/list-faq.php new file mode 100644 index 0000000..e2791dd --- /dev/null +++ b/app/default/templates/list-faq.php @@ -0,0 +1,141 @@ + +
+ +
+ + +
+
+ +
+ +

+ +
+
+ +

:

+ + +
+
+ +
+
+ + diff --git a/app/default/templates/list-grid.php b/app/default/templates/list-grid.php new file mode 100644 index 0000000..0aad44c --- /dev/null +++ b/app/default/templates/list-grid.php @@ -0,0 +1,94 @@ + +
+ +
+ + +
+
+ + + +
+
+ +