Skip to content
pagecraft

Editing Existing Templates

Audience: Site Builder.

PageCraft's bundled section templates aren't carved in stone — every section the picker shows can be edited, renamed, recategorised, or replaced from the CP. This page covers the basic CRUD flow plus the regeneration step that keeps the picker in sync with the database.

The Sections manager

CP path: Add-Ons → PageCraft → Sections.

The list shows every row in exp_pagecraft_sections for the current site, with thumbnail, name, category, description, and Edit / Delete actions. Toolbar buttons across the top:

  • Regenerate File — see "Regenerate File button" below
  • Export Sections — downloads a JSON file (the input format for Sections Import)
  • Import Sections — uploads a JSON file (replaces or appends)
  • Import Pack (.zip) — see Importing Custom Templates
  • Ingest Template (.zip) — see Importing Custom Templates
  • Add Section — opens the section editor for a new row

Section editor fields

Click Edit on any row, or click Add Section. The edit screen exposes:

  • Name — shown under the thumbnail in the picker
  • Description — shown only inside the Sections manager (free-form note for your own reference)
  • Category — the picker grouping the section appears under (Grid Builder, PageCraft, or any custom category you've added under PageCraft → Categories)
  • Thumbnail — see "Thumbnail formats" below
  • HTML body — the actual section markup (the source of what gets dropped into the canvas)
  • Sort order — picker order within the category

Saving the form re-runs Services/SectionFileWriter::write() automatically, so the picker reflects your change immediately.

Thumbnail formats

The Thumbnail field accepts four shapes:

  • EE file reference — {file:42:url} resolves through the EE file manager
  • Portable file reference — {filedir_5}my-thumb.png (legacy, still supported)
  • Absolute URL — https://cdn.example.com/thumbs/hero.png
  • Plain filename — hero.png resolves to themes/user/pagecraft/pagecraft-sections/preview/hero.png

The plain-filename path is the most ergonomic for SVG previews you commit to the repo alongside the section. The bundled Grid Builder thumbnails use this pattern (gb-1col.svg, gb-2col.svg, etc.).

Services/SectionFileWriter::buildThumbnailPath() decides which shape it has and returns the right absolute URL when generating the picker JS.

Regenerate File button

The picker reads from themes/user/pagecraft/pagecraft-sections/pagecraft-sections.js. That file is regenerated by SectionFileWriter after any section/category save. Two situations the button helps with:

  • Permission-related failures. If the file isn't writable by the PHP user, the auto-write fails silently. The Regenerate button surfaces the exact error inline ("file is not writable by the PHP user — fix permissions on …").
  • Sections that show in the manager but not in the canvas picker. The DB and the JS file have drifted. Click the button to force a clean rewrite.

The writer is non-destructive: if the DB has zero categories and zero sections (e.g. an empty fresh install) it refuses to overwrite a non-empty existing file, so you can't accidentally clobber the bundled defaults.

Save-as-Section from the canvas

Inside the editor, every section toolbar has a 💾 Save as Section button. Click it, name the new section, pick a category. The flow:

  1. Clones the rendered HTML out of the canvas
  2. Strips ContentBox editor UI (toolbars, drag handles, click hooks) and the data-cb-original-content snapshot via Actions/SaveSection.php
  3. Inserts a new row into exp_pagecraft_sections
  4. Triggers SectionFileWriter::write() so the new section appears in the picker on next page load

Reference

  • Schema: Page_craft_upd::createSectionsTable() and createSectionCategoriesTable() in upd.page_craft.php
  • Generation pipeline: Services/SectionFileWriter.php
  • Save-as-Section action: Actions/SaveSection.php
  • Sections list page: mcp.page_craft.php::sections()
  • Section editor: mcp.page_craft.php::section_edit($id)