Welcome: Building Atelier

Five minutes to set expectations. After this chapter you have not written any code yet. You have a sketch of the destination, a list of the rails you'll ride on, and a small to-do list to align your local Scriptor install with the tutorial.

What "done" looks like

At the end of chapter 6 you will be able to:

  1. Drop a folder called atelier/ into themes/ of any Scriptor install,
  2. set 'theme_path' => 'atelier/' in data/settings/custom.scriptor-config.php (the update-safe override; chapter 2 covers the file),
  3. reload the site, and
  4. see a finished portfolio site with a working blog, contact form and 404 page, without writing more code.

The finished theme is publishable too: a tagged Composer package that someone else can composer require from a custom theme repo.

The target page tree

You'll build Atelier against a small page tree. Three pages are the bare minimum to make navigation feel real; the others fall in as you go:

Home              template=home       (showcase / hero)
About             template=basic      (one long page)
Projects          template=projects   (gallery of child pages)
  ├── Project A   template=basic
  ├── Project B   template=basic
  └── Project C   template=basic
Contact           template=contact    (form on a basic page)

The Blog is not in the page tree. It lives as markdown files under the theme's own content/blog/ directory and is mounted by the markdown-pages plugin you'll install in chapter 5.

Set this up before chapter 3. Open the editor at /editor/pages/ on your local Scriptor install, create About, Projects, three child pages under Projects, and Contact. Leave each child page's template field as basic for now; you'll change Projects to projects in chapter 3.

The exact titles, slugs and content don't matter. You just need some DB pages so navigation has something to walk.

The rails

Every chapter rides four rails:

  • Scriptor's Site class. Your theme will eventually subclass it. Until then, the default Site is enough.
  • A template.php dispatcher. One file, six lines, picks the right page template based on $page->template. You'll write it in chapter 2 and never touch it again.
  • The $site->render('content' | 'navigation' | …) surface. Theme code only ever calls these helpers; no SQL, no PageRepository lookups, no PSR-14 dispatching in templates.
  • A composer.json with a classmap for lib/. That is the whole "package" story for a theme. There is no "type": "scriptor-theme" marker; Scriptor finds your theme by directory name only.

If any of these phrases sound new, the relevant Concept chapter is linked at the top of the chapter where it shows up.

The rules of the road

Three guard-rails to keep the result honest:

  1. No SQL or repository lookups in templates. Templates call $site->render('content'), $site->page->name, etc. The day you reach for $site->pages->find() inside a .php template, stop and move that into a Site subclass method.
  2. No business logic in template.php. It exists to dispatch to a per-template file and nothing else. The pattern is the same in every theme; chapter 2 shows it.
  3. Plugin-owned data stays inside the plugin. Your theme will consume what the markdown-pages plugin offers, never reach into the plugin's content tree directly. Chapter 5 shows the right hook.

To-do before chapter 2

  • Working Scriptor install: composer install clean and php bin/scriptor install ran successfully (see docs/install.md if you have not done this yet).
  • /editor/pages/ accessible with the admin credentials you set during install; at least one page exists.
  • Create the page tree from the Target page tree section above (you can fill them with placeholder content).
  • Pick an empty directory name. Scriptor splits each theme across two paths: themes/<name>/ for PHP source (templates, partials, lib) and public/themes/<name>/ for browser-served assets (CSS, JS, images). We'll use atelier throughout; substitute your own if you prefer. Chapter 2 walks creating both directories.

When all four boxes are ticked, open chapter 2 and write your first template.php.

Behind the scenes. The page-tree contract Atelier rides on is documented in docs/imanager-2.0-plan.md and in the Concepts → Frontend Nav Registry chapter you'll lean on in chapter 4. The Site class itself lives at boot/Frontend/Site.php.