PageTree Documentation

Requirements

PageTree 2.x requires:

• October CMS 4.2 or later
• PHP 8.2 or later

Optional integrations:

• RainLab.Translate for translated pages and slugs
• October CMS multisite

For October CMS 3.7 through 4.1.x, use PageTree 1.0.7.

Installation

Install the plugin in:

plugins/lucaspalomba/pagetree

Run the database migrations:

php artisan october:migrate

Then give your editors the:

Settings → Administrators → Roles → Manage block pages

permission.

The Block Pages section will then be available in the backend.

---

Creating a page

Go to:

Block Pages → New Page

Enter the page title and slug.

For example:

Title: About us
Slug: about-us

The page will be available at:

https://example.com/about-us

Select a layout from your active theme.

The selected layout is used both for the frontend page and for the live preview.

---

Adding blocks

Open the Components tab and select Add Component.

Blocks can be:

• Added from the block library
• Reordered using drag and drop
• Edited by double-clicking them
• Duplicated
• Copied and pasted
• Hidden without deleting them

Multiple blocks can be selected using Ctrl + click.

Every block contains an Is displayed? switch.

---

Page visibility

A PageTree page is publicly accessible only when:

1. The page is active
2. The page is published
3. Its publication date has been reached

Otherwise the page returns a 404 response.

---

Theme integration

PageTree pages automatically use the layout selected on the page.

No additional integration is required.

Your layout should contain the standard October CMS asset tags:

{% styles %}
{% scripts %}

These are required for assets provided by October CMS components used as PageTree blocks.

---

SEO

The SEO tab provides configuration for search engines and social networks.

Available values include:

meta_title
meta_description
meta_image
meta_type
meta_robots

They are also available through:

this.page.apiBag.pagetree_seo

PageTree fills the native October CMS page properties, allowing existing themes to use:

<title>{{ this.page.meta_title }}</title>
<meta name="description" content="{{ this.page.meta_description }}">

For complete SEO output, add the pageTreeSeo component to your layout:

[pageTreeSeo]
==

Then render it inside <head>:

{% component 'pageTreeSeo' %}

The component can generate:

• Title
• Description
• Robots
• Canonical URL
• hreflang alternates
• Open Graph metadata
• Twitter cards
• JSON-LD WebPage data
• JSON-LD BreadcrumbList data

---

October CMS components as blocks

PageTree automatically exposes frontend components registered by installed plugins in the block library.

Component properties are converted into editable backend fields.

Supported property types include:

• Text
• Textarea
• Checkbox
• Dropdown
• String lists

Dropdown options provided through get{Property}Options() and optionsMethod are supported.

The component continues to operate as a normal October CMS component on the frontend.

Its:

• init()
• onRun()
• AJAX handlers
• Component partials
• Assets

continue to work normally.

The generated component alias follows this format:

pagetreeComponent_<blockId>

To override its partials from a theme:

partials/pagetreeComponent_<blockId>/

Properties of type set, dictionary, object and objectList are not currently editable and use their default values.

URL parameters such as:

{{ :slug }}

are not available on PageTree pages.

---

Custom blocks

Superusers can create custom blocks directly from:

Editor → Block Pages → Custom blocks

A custom block consists of:

Fields

A backend form definition using standard October CMS fields.

Data

Optional data sources such as:

• Tailor entries
• Plugin models

Data sources can define sorting and limits.

Template

The block frontend markup is written in Twig.

Form values are available through:

data

Data source variables are also available to the template.

Custom blocks are only manageable by superusers because their Twig templates are compiled in the CMS Twig environment.

---

Creating a developer block

A block can be scaffolded with:

php artisan create:block Acme.Blog Testimonial

This creates:

blocks/Testimonial.php
blocks/testimonial/config_fields.yaml
blocks/testimonial/default.php

Register the block in the plugin:

public function registerBlocks()
{
    return [
        'blog.testimonial' => \Acme\Blog\Blocks\Testimonial::class,
    ];
}

The block then appears in the PageTree block library under the plugin name.

---

Block class

A basic block can extend PageTree's component base:

<?php namespace Acme\Blog\Blocks;

use LucasPalomba\PageTree\Classes\ComponentBase;

class Testimonial extends ComponentBase
{
    public $config_fields = 'config_fields.yaml';

    public $uniqueKey = 'blog.testimonial';

    public function componentDetails()
    {
        return [
            'label' => 'Testimonial',
            'description' => 'Customer quote with author',
            'icon' => 'ph ph-quotes',
        ];
    }
}

Blocks can define additional options and variables through their class methods.

---

Block form

The form is defined in config_fields.yaml.

Example:

fields:
    quote:
        label: Quote
        type: textarea

    author:
        label: Author
        type: text
        span: left

    style:
        label: Style
        type: dropdown
        span: right

An Is displayed? field is automatically added to every block.

Its field name is:

isActive

Define it manually only if you need to customize its label or position.

---

Block template

Block templates use Twig.

Form values are available through data:

<blockquote class="testimonial testimonial--{{ data.style|default('light') }}">
    <p>{{ data.quote }}</p>
    <footer>{{ data.author }}</footer>
</blockquote>

Content entered by editors is not evaluated as Twig on the website.

---

Rendering PageTree blocks from a CMS page

PageTree blocks can also be rendered inside a regular October CMS page using:

{% pagecomponent block %}

The PageTree page can be loaded from the model and its components passed to the template.

This allows PageTree content to be reused inside custom CMS pages and layouts.

---

Page Finder

PageTree pages are available through the October CMS page finder.

They appear under the:

Block Pages

type.

This allows PageTree pages to be selected from menus, links and other October CMS features using the standard page finder.

---

Styling built-in blocks

Built-in blocks load their styles from:

assets/css/blocks/

Their CSS uses low-specificity selectors, allowing the active theme to override the styles.

The main CSS variables include:

:root {
    --ptb-primary: #0f766e;
    --ptb-primary-contrast: #fff;
    --ptb-secondary: #475569;
    --ptb-light: #f3f4f6;
    --ptb-dark: #1f2937;
    --ptb-radius: 0.5rem;
    --ptb-gap: 1.5rem;
    --ptb-space-s: 1rem;
    --ptb-space-m: 2rem;
    --ptb-space-l: 4rem;
    --ptb-space-xl: 6rem;
    --ptb-container: 1200px;
}

Theme styles can target the ptb-* classes directly.

---

Settings

PageTree settings are available under:

Settings → Block Pages Settings

Available settings include:

• Backend menu label
• Default preview stylesheets
• Default preview scripts
• Site name
• SEO title template
• Default robots directive
• Twitter account
• Default Open Graph image

---

Permissions

PageTree provides two permissions:

Permission	Description
Manage block pages	Create, edit and delete PageTree pages
Manage block pages settings	Manage PageTree settings

---

Troubleshooting

A page returns a 404

Check:

• The page is active
• The page is published
• The publication date has been reached
• No CMS page uses the same URL

Component assets are missing

Make sure the selected layout contains:

{% styles %}
{% scripts %}

The live preview is empty

Check that the selected layout renders correctly on its own.

Then inspect:

storage/logs/system.log

Saving a large page returns HTTP 413

Increase the client_max_body_size value in your NGINX configuration.