# ZAB Site Package (`zab_site`)

This is the TYPO3 sitepackage (theme) for the project.

## First day setup

1. Start the environment
	- `ddev start`
2. Install PHP dependencies (project root)
	- `composer install`
3. Install frontend dependencies (`packages/zab_site`)
	- `npm install`
4. Build assets once (`packages/zab_site`)
	- `npm run build`
5. Start frontend development with HMR (`packages/zab_site`)
	- `npm run dev`

## Main folders

- `Classes/` — PHP code for the extension
- `Configuration/` — TYPO3 configuration + Vite entrypoint mapping
- `ContentBlocks/` — content components used by editors
- `Resources/Private/Assets/` — source JS/SCSS
- `Resources/Public/Dist/` — generated frontend files

## How assets are loaded (important)

Vite has two modes:

- **Dev mode** (`npm run dev`): serves assets from `http://localhost:5173` with HMR
- **Build mode** (`npm run build` / `npm run build:prod`): writes static files and manifest to `Resources/Public/Dist`

TYPO3 uses two key configs:

1. `Configuration/ViteEntrypoints.json` (required)
	- tells TYPO3 which frontend entry files to load
	- current entries:
	  - `../Resources/Private/Assets/app.js`
	  - `../Resources/Private/Assets/main.scss`

2. `config/system/settings.php` → `EXTENSIONS.vite_asset_collector`
	- `defaultManifest`: `EXT:zab_site/Resources/Public/Dist/.vite/manifest.json`
	- `devServerUri`: `http://localhost:5173`
	- `useDevServer`:
	  - `true` = load assets from Vite dev server
	  - `false` = load built assets from `Resources/Public/Dist`

## Scripts

- `npm run dev` — run Vite dev server (with TYPO3 cache flush)
- `npm run watch` — alias of `dev`
- `npm run build` — build assets (with TYPO3 cache flush)
- `npm run build:prod` — clean + production build
- `npm run clean` — remove generated assets and flush TYPO3 cache
- `npm run preview` — preview Vite build output

> Note: these scripts call `ddev typo3 cache:flush`, so DDEV must be available.

## Useful links

- TYPO3 documentation: https://docs.typo3.org/
- TYPO3 Explained (core concepts): https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/
- Content Blocks (FriendsofTYPO3): https://github.com/FriendsOfTYPO3/content-blocks
- Vite: https://vite.dev/
- DDEV: https://ddev.readthedocs.io/

### Extensions used in this project

- `friendsoftypo3/content-blocks` — https://github.com/FriendsOfTYPO3/content-blocks
- `fluidtypo3/vhs` — https://github.com/FluidTYPO3/vhs
- `s2b/vite-asset-collector` — https://github.com/s2b/vite-asset-collector
- `netresearch/t3x-rte_ckeditor_image` — https://github.com/netresearch/t3x-rte_ckeditor_image
- `TYPO3-CMS/indexed_search` — https://github.com/TYPO3-CMS/indexed_search

## Search indexed

This project uses `TYPO3/indexed_search` for site-wide search. To index PDF files so they appear in search results, the server must have `poppler-utils` installed (provides `pdftotext` and `pdfinfo`).

```bash
# Install on Ubuntu/Debian
sudo apt install poppler-utils
	or
apt install -y poppler-utils

# test if poppler-utils is install (run 'which pdftotext')
# For DDEV: already configured via .ddev/web-build/Dockerfile.poppler
```

After installing, re-index pages that contain PDF files (via the TYPO3 backend or by visiting them in the frontend).


## Local requirements

- Node.js `>=22` (defined in `package.json`)
- Installed NPM dependencies (`npm install`)
- A working TYPO3/DDEV environment for scripts that flush cache

## Daily workflow

For normal frontend work:

1. `ddev start`
2. In `packages/zab_site`: `npm run dev`
3. Keep TYPO3 open and edit assets/content blocks

Before commit/deploy:

1. In `packages/zab_site`: `npm run build:prod`
2. Confirm generated files exist in `Resources/Public/Dist`