Move documentation files from custom to content directory
This commit is contained in:
Ruben
parent
cea2c167ff
commit
c501635912
32 changed files with 0 additions and 0 deletions
2
content/docs/utvikling/forklaring/metadata.ini
Normal file
2
content/docs/utvikling/forklaring/metadata.ini
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
title = "Forklaring"
|
||||
summary = "Forstå konseptene og designvalgene bak PnP"
|
||||
2
content/docs/utvikling/forklaring/routing/metadata.ini
Normal file
2
content/docs/utvikling/forklaring/routing/metadata.ini
Normal file
|
|
@ -0,0 +1,2 @@
|
|||
title = "Rutingssystemet"
|
||||
summary = "Forstå hvordan PnPs mappebaserte ruting fungerer"
|
||||
98
content/docs/utvikling/forklaring/routing/page.md
Normal file
98
content/docs/utvikling/forklaring/routing/page.md
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
# Forstå ruting i PnP
|
||||
|
||||
PnP bruker et enkelt, intuitivt mappebasert rutingssystem som kobler mapper direkte til URL-er.
|
||||
|
||||
## Filosofien
|
||||
|
||||
Tradisjonelle webrammeverk krever at du definerer ruter i konfigurasjonsfiler. PnP tar en annen tilnærming: **mappestrukturen ER rutekonfigurasjonen din**.
|
||||
|
||||
Dette designvalget prioriterer:
|
||||
- **Enkelhet**: Ingen rutdefinisjoner å vedlikeholde
|
||||
- **Forutsigbarhet**: URL-er matcher mappestrukturen nøyaktig
|
||||
- **Vedlikeholdbarhet**: Lett å forstå selv år senere
|
||||
|
||||
## Hvordan det fungerer
|
||||
|
||||
### URL til fil-mapping
|
||||
|
||||
Når en forespørsel kommer inn, følger ruteren denne logikken:
|
||||
|
||||
1. **Nøyaktig filmatch**: Hvis `/content/om.html` eksisterer, server den
|
||||
2. **Mappe med sidefil**: Hvis `/content/om/` inneholder `page.md`, server den
|
||||
3. **Mappe med enkeltfil**: Hvis `/content/blogg/innlegg/` inneholder `article.md`, server den
|
||||
4. **Mappelisting**: Hvis `/content/blogg/` inneholder undermapper, list dem
|
||||
|
||||
### Skråstrek-atferd
|
||||
|
||||
PnP omdirigerer automatisk mappebaserte sider til å inkludere skråstrek på slutten:
|
||||
|
||||
- `/blogg/mitt-innlegg` → `/blogg/mitt-innlegg/` (301 redirect)
|
||||
|
||||
Dette sikrer at relative stier i markdown fungerer korrekt (bilder, lenker, etc).
|
||||
|
||||
## Filprioritet
|
||||
|
||||
Når PnP ser etter innhold i en mappe, søker den etter filer i denne rekkefølgen:
|
||||
|
||||
### For enkle sider (artikler, innlegg):
|
||||
1. `single.php`
|
||||
2. `single.html`
|
||||
3. `single.md`
|
||||
4. `post.php`
|
||||
5. `post.html`
|
||||
6. `post.md`
|
||||
7. `article.php`
|
||||
8. `article.html`
|
||||
9. `article.md`
|
||||
|
||||
### For overordnede sider:
|
||||
1. `page.php`
|
||||
2. `page.html`
|
||||
3. `page.md`
|
||||
|
||||
## Språkvariasjoner
|
||||
|
||||
PnP støtter flerspråklige sider. For språk som ikke er standardspråket, søker ruteren etter språkspesifikke filer først:
|
||||
|
||||
```
|
||||
page.en.md → Engelsk versjon
|
||||
page.md → Norsk versjon (standard)
|
||||
```
|
||||
|
||||
URL-strukturen blir:
|
||||
|
||||
```
|
||||
/om/ → Norsk (standard)
|
||||
/en/about/ → Engelsk
|
||||
```
|
||||
|
||||
## Egendefinerte indekssider
|
||||
|
||||
Du kan overstyre standard mappelisting ved å lage en `index.php`-fil i en hvilken som helst mappe.
|
||||
|
||||
## Mappenavn med datoer
|
||||
|
||||
PnP trekker automatisk ut datoer fra mappenavn:
|
||||
|
||||
```
|
||||
/content/blogg/2025-01-15-mitt-innlegg/
|
||||
```
|
||||
|
||||
Datoen formateres automatisk til norsk format: "15. januar 2025"
|
||||
|
||||
## Hvorfor denne tilnærmingen?
|
||||
|
||||
Dette rutingssystemet vil fungere i flere tiår fordi:
|
||||
- Ingen komplekse avhengigheter
|
||||
- Ingen rutdefinisjoner som blir utdaterte
|
||||
- Filsystemoperasjoner er standardiserte og stabile
|
||||
- Enkelt å migrere eller ta backup (bare kopier mapper)
|
||||
- Ingen abstraksjoner som skjuler underliggende struktur
|
||||
- Ingen kompilering eller cache-generering nødvendig
|
||||
|
||||
## Sikkerhet
|
||||
|
||||
Ruteren validerer alle stier for å forhindre directory traversal-angrep:
|
||||
- Filer må være innenfor document root
|
||||
- Realpaths sjekkes mot contentDir
|
||||
- Kun godkjente filtyper serveres
|
||||
|
|
@ -0,0 +1,2 @@
|
|||
title = "Malsystemet"
|
||||
summary = "Forstå hvordan PnPs malsystem fungerer"
|
||||
225
content/docs/utvikling/forklaring/template-system/page.md
Normal file
225
content/docs/utvikling/forklaring/template-system/page.md
Normal file
|
|
@ -0,0 +1,225 @@
|
|||
# Forstå malsystemet
|
||||
|
||||
PnP bruker et enkelt, men kraftig malsystem basert på PHP-inkluderinger.
|
||||
|
||||
## Filosofien
|
||||
|
||||
Tradisjonelle templating-systemer introduserer nye språk og syntaks som må læres. PnP tar en annen tilnærming: **bruk PHP som det er**.
|
||||
|
||||
Dette designvalget gir:
|
||||
- **Ingen læringskurve**: Hvis du kan PHP, kan du lage maler
|
||||
- **Full kraft**: Tilgang til alle PHP-funksjoner
|
||||
- **Null overhead**: Ingen kompilering eller parsing
|
||||
- **Lett feilsøking**: Standard PHP-feilmeldinger
|
||||
|
||||
## Malhierarki
|
||||
|
||||
PnP har tre hovednivåer av maler:
|
||||
|
||||
### 1. Basismal (base.php)
|
||||
Inneholder den overordnede HTML-strukturen:
|
||||
|
||||
```php
|
||||
<!DOCTYPE html>
|
||||
<html lang="<?= $currentLang ?>">
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<title><?= $pageTitle ?? 'Min side' ?></title>
|
||||
</head>
|
||||
<body>
|
||||
<nav><!-- Navigasjon --></nav>
|
||||
<?= $content ?>
|
||||
<footer><!-- Footer --></footer>
|
||||
</body>
|
||||
</html>
|
||||
```
|
||||
|
||||
### 2. Sidemal (page.php)
|
||||
Pakker inn enkeltinnhold:
|
||||
|
||||
```php
|
||||
<article>
|
||||
<?= $content ?>
|
||||
</article>
|
||||
```
|
||||
|
||||
### 3. Listemal (list.php)
|
||||
Viser samlinger av innhold:
|
||||
|
||||
```php
|
||||
<article>
|
||||
<?php foreach ($items as $item): ?>
|
||||
<div>
|
||||
<h2><a href="<?= $item['url'] ?>"><?= $item['title'] ?></a></h2>
|
||||
</div>
|
||||
<?php endforeach; ?>
|
||||
</article>
|
||||
```
|
||||
|
||||
## Dataflyt
|
||||
|
||||
Når en forespørsel kommer inn, flyter data gjennom systemet slik:
|
||||
|
||||
```
|
||||
Request → Router → Content → Page Template → Base Template → Response
|
||||
```
|
||||
|
||||
1. **Router**: Finner riktig innhold
|
||||
2. **Content**: Konverterer markdown/HTML til HTML
|
||||
3. **Page Template**: Pakker innholdet i `$content`
|
||||
4. **Base Template**: Pakker alt i full HTML-struktur
|
||||
|
||||
## Fallback-kjede
|
||||
|
||||
PnP følger en fallback-kjede for maler:
|
||||
|
||||
```
|
||||
custom/templates/base.php
|
||||
↓ (hvis ikke funnet)
|
||||
default/templates/base.php
|
||||
```
|
||||
|
||||
Dette betyr:
|
||||
- Egendefinerte maler overstyrer standardmaler
|
||||
- Du trenger bare å lage egendefinerte maler for det du vil endre
|
||||
- Standardmaler fungerer som fallback
|
||||
|
||||
## Tilgjengelige variabler
|
||||
|
||||
### I base.php
|
||||
|
||||
| Variabel | Type | Beskrivelse |
|
||||
|----------|------|-------------|
|
||||
| `$content` | string | Det rendrede innholdet |
|
||||
| `$navigation` | array | Navigasjonselementer |
|
||||
| `$currentLang` | string | Nåværende språk |
|
||||
| `$defaultLang` | string | Standardspråk |
|
||||
| `$homeLabel` | string | Label for hjem-lenken |
|
||||
| `$translations` | array | Oversettelser fra språkfiler |
|
||||
| `$pageTitle` | string | Sidens tittel |
|
||||
|
||||
### I page.php
|
||||
|
||||
| Variabel | Type | Beskrivelse |
|
||||
|----------|------|-------------|
|
||||
| `$content` | string | Innholdet som skal vises |
|
||||
| `$pageMetadata` | array | Metadata for siden |
|
||||
| `$pageTitle` | string | Sidens tittel |
|
||||
|
||||
### I list.php
|
||||
|
||||
| Variabel | Type | Beskrivelse |
|
||||
|----------|------|-------------|
|
||||
| `$items` | array | Listeelementer |
|
||||
| `$metadata` | array | Metadata for mappen |
|
||||
| `$pageContent` | string | Valgfritt innhold fra page.md |
|
||||
|
||||
## Items-struktur
|
||||
|
||||
I list.php er hvert element i `$items` et array med:
|
||||
|
||||
```php
|
||||
[
|
||||
'title' => 'Innleggstittel',
|
||||
'date' => '15. januar 2025',
|
||||
'url' => '/blogg/2025-01-15-innlegg',
|
||||
'cover' => '/blogg/2025-01-15-innlegg/cover.jpg', // eller null
|
||||
'summary' => 'Kort beskrivelse' // eller null
|
||||
]
|
||||
```
|
||||
|
||||
## Sikkerhet i maler
|
||||
|
||||
### Escape output
|
||||
Bruk alltid `htmlspecialchars()` for brukerdata:
|
||||
|
||||
```php
|
||||
<h1><?= htmlspecialchars($item['title']) ?></h1>
|
||||
```
|
||||
|
||||
### Ikke escape HTML-innhold
|
||||
`$content` inneholder allerede HTML og skal ikke escapes:
|
||||
|
||||
```php
|
||||
<?= $content ?> <!-- RIKTIG -->
|
||||
<?= htmlspecialchars($content) ?> <!-- FEIL -->
|
||||
```
|
||||
|
||||
## Beste praksis
|
||||
|
||||
### Bruk korte echo-tags
|
||||
```php
|
||||
<?= $variable ?> <!-- Bra -->
|
||||
<?php echo $variable; ?> <!-- Fungerer, men mer verbose -->
|
||||
```
|
||||
|
||||
### Sjekk for eksistens
|
||||
```php
|
||||
<?php if (isset($metadata['summary'])): ?>
|
||||
<p><?= htmlspecialchars($metadata['summary']) ?></p>
|
||||
<?php endif; ?>
|
||||
```
|
||||
|
||||
### Bruk ternary for fallbacks
|
||||
```php
|
||||
<title><?= $pageTitle ?? 'Standard tittel' ?></title>
|
||||
```
|
||||
|
||||
### Hold logikk utenfor maler
|
||||
Forbered data i ruteren eller i egne funksjoner, ikke i malene:
|
||||
|
||||
```php
|
||||
<!-- DÅRLIG -->
|
||||
<?php
|
||||
$processedItems = array_filter($items, function($item) {
|
||||
return strlen($item['title']) > 10;
|
||||
});
|
||||
?>
|
||||
|
||||
<!-- BRA -->
|
||||
<!-- Gjør dette i ruteren eller i en egen funksjon -->
|
||||
```
|
||||
|
||||
## Egendefinerte maler
|
||||
|
||||
For å lage egendefinerte maler:
|
||||
|
||||
1. Kopier standardmalen fra `/app/default/templates/`
|
||||
2. Lim den inn i `/app/custom/templates/`
|
||||
3. Endre etter behov
|
||||
|
||||
Eksempel:
|
||||
|
||||
```bash
|
||||
cp app/default/templates/base.php app/custom/templates/base.php
|
||||
# Rediger app/custom/templates/base.php
|
||||
```
|
||||
|
||||
## Spesialiserte maler
|
||||
|
||||
Du kan lage spesialiserte maler for spesifikke formål:
|
||||
|
||||
### list-grid.php
|
||||
En alternativ listevisning med grid-layout:
|
||||
|
||||
```php
|
||||
<article class="grid">
|
||||
<?php foreach ($items as $item): ?>
|
||||
<div class="card">
|
||||
<!-- Grid-basert layout -->
|
||||
</div>
|
||||
<?php endforeach; ?>
|
||||
</article>
|
||||
```
|
||||
|
||||
PnP vil automatisk foretrekke `list-grid.php` over `list.php` hvis den eksisterer.
|
||||
|
||||
## Hvorfor dette systemet?
|
||||
|
||||
Dette malsystemet vil fungere i flere tiår fordi:
|
||||
- Ingen proprietære templating-språk som kan bli utdaterte
|
||||
- Basert på standard PHP-funksjoner
|
||||
- Ingen kompilering eller cache-generering
|
||||
- Lett å debugge med standard PHP-verktøy
|
||||
- Ingen dependencies som kan bryte
|
||||
- Fullt SEO-vennlig (server-side rendering)
|
||||
Loading…
Add table
Add a link
Reference in a new issue