Skip to content
pagecraft

Getting Started

Audience: Editor and Site Builder.

Adding the fieldtype to a channel

  1. Develop → Channels → Fields, click New Field.
  2. Choose PageCraft Builder as the field type. Give it a short name like body or page_content.
  3. Save. Add the field to a channel via that channel's Fields tab.

You can have more than one PageCraft field on a channel, but in practice one is usually enough — a single PageCraft field can build an entire page.

Per-field settings

Every PageCraft field exposes a settings group on the field-edit screen. The most common knobs:

  • Upload directory — overrides the global default for image uploads inside this field. Leave blank to inherit the addon-wide setting (Add-Ons → PageCraft → Global Settings → Upload Directory).
  • Allowed block packs — restrict which block packs (Simple, Quick, Animated, PageCraft, etc.) appear in the picker for this field.
  • Allowed categories — narrow the section picker to specific categories (e.g. "Hero" + "Photos" only).
  • Custom CSS / Custom JS — per-field stylesheet and script that load alongside the editor canvas. See Template Tags Reference for the runtime story.

Anything not overridden falls back to the addon's Global Settings.

Saving the first entry

Open an entry that uses your new field. The PageCraft canvas mounts in place of a normal text area. Click anywhere to start: the section picker opens on first interaction, and you can drag any section in.

When you save the entry, PageCraft serializes three things into the field as JSON:

  • html — the full canvas markup, before dynamic resolution
  • mainCss — global stylesheet for the page (set in the editor's style panel)
  • sectionCss — per-section CSS that the editor accumulates as you tweak section styles

The JSON lands in exp_channel_data_field_N like any other custom field value.

Front-end output

In the template that renders the entry, output the field with one or more of:

{exp:channel:entries channel="pages"}
    <style>{my_field type="css"}</style>
    {my_field type="html"}
    <style>{my_field type="sectioncss"}</style>
{/exp:channel:entries}

Or, if you want a single tag that returns the full rendered page (HTML + CSS combined with sensible defaults):

{exp:page_craft:html}

The {exp:page_craft:html} tag also resolves dynamic content — embedded EE templates render in place, and the structure-driven nav menu (if enabled) injects the live menu data. See Template Tags Reference for parameter detail.

Previewing on a headless front end

The editor's Preview button opens the EE page for the entry. If your site is built with Astro, Next, Eleventy or anything else that consumes EE as a data source, point it at that instead:

CP → Add-Ons → PageCraft → Global Settings

  • External Preview URL — e.g. http://localhost:4321. Blank is the off switch; leave it empty and Preview behaves exactly as before.

  • External Preview Path — appended to the URL above. Placeholders:

Placeholder Gives Use when
{uri} the Structure URI, e.g. services/consulting Your site uses Structure. Start here
{url_title} just the entry's URL title Flat sites with no nesting
{entry_id} the numeric id Routes like /p/42

Prefer {uri} if you use Structure. The two agree on top-level pages and diverge the moment one is nested: a page under Services has the URI services/consulting but the URL title consulting, so /{url_title}/ sends you to a page that does not exist. That failure only appears the first time someone nests a page, which is a bad time to discover it.

If Structure has no URI for the entry, Preview falls back to the EE page rather than building a URL that is probably wrong.

Override it per environment, and why you should

These settings live in the database, so they travel with a database clone. A preview URL of http://localhost:4321 copied to staging points every editor there at their own machine, and nobody notices until someone clicks Preview.

Set it in system/user/config/config.php instead, which is per-environment and never travels:

$config['pagecraft_external_preview_url']     = 'http://localhost:4321';
$config['pagecraft_external_preview_pattern'] = '/{uri}/';

The config value wins over the stored setting. A config value that is set but empty switches the feature off, so a production config can force it off no matter what a cloned database says:

$config['pagecraft_external_preview_url'] = '';   // production: always the EE page

The home page needs one line on the front end

Most headless front ends render the home page from an index route (index.astro, index.tsx) at /, and exclude it from the dynamic route so it is not built twice. EE still knows that entry by its real URI — usually /home/ — so Preview sends you there and you get a 404.

PageCraft reports the CMS path deliberately; guessing which entry is "the index" would be inventing your app's routing convention. Map it in the app instead. In Astro that is:

export default defineConfig({
  redirects: { '/home': '/', '/home/': '/' },
});

That fixes every link that follows the CMS path, not just the Preview button. Restart the dev server after changing the config.

Which server you point at changes the workflow

This is the part worth getting right:

  • A dev server (astro dev, next dev) fetches your content per request, so

preview shows what you just saved. No build step, nothing to remember.

  • A built static site serves the last build, so preview lags behind your edits

until the site is rebuilt.

For day-to-day editing, the dev server is the one you want.

A new, unsaved entry has no URL title yet. Rather than send you to the front end's index page — which would look like a working preview of the wrong page — Preview falls back to the EE URL until the entry has been saved once.

Where to next