predefinedBlocks
================

Predefined content blocks for MODX 3. The block editor replaces the Content
field on the templates where you enable it. Editors build a page from a fixed
set of blocks (heading, text and images, table, list, video, custom block,
wrapper / accordion, chunk / snippet / HTML); developers restyle each block by
copying its Fenom template into the theme, and add their own sections as
types of the Custom block. The rendered HTML is saved into the
resource content, so search, teasers and getResources/pdoResources keep
working.

Documentation: {docs_url}

Requirements
------------
- MODX 3.0 or newer, PHP 8.1 or newer (GD for image resizing)
- pdoTools 3 (Fenom) - block templates are Fenom templates
- Bootstrap is optional: the default templates use Bootstrap 5.3 class
  names, and the plugin adds its own blocks.css / blocks.js to pages with
  blocks (install option "Plugin CSS"). With the option "Bootstrap" the theme
  loads Bootstrap and the plugin adds nothing.

Conflict with ContentBlocks
---------------------------
predefinedBlocks and ContentBlocks both take over the Content field and cannot
be used on the same template. On every template with predefinedBlocks enabled
the plugin sets the template property contentblocks.disabled = 1. Existing
ContentBlocks content is not converted.

Enabling the editor
-------------------
Tick the templates in the install form, or on any template:
Elements → Templates → (template) → Properties → Default Properties:
- pb.enabled      Yes = the block editor replaces Content on this template
- pb.path         optional folder with this template's own block templates
                  (looked up first, then the default folder)
- pb.upload_path  optional upload folder for images (overrides the setting)
- pb.custom_path  optional folder with Custom block types for this template
Use Default Properties, not a property set - MODX ignores property sets on
templates. Existing content of a page is wrapped into a "Text and images"
block the first time the page is opened.

System settings (namespace predefinedblocks)
--------------------------------------------
- predefinedblocks.blocks_path      Default folder with block templates
                                    (default {core_path}components/predefinedblocks/blocks/)
- predefinedblocks.media_source     Media source for images (empty = default_media_source)
- predefinedblocks.upload_path      Upload folder, tokens {year} {month} {day} {id} {alias}
                                    (default assets/media/{year}/{month}/)
- predefinedblocks.image_max_width  Content width for image resizing in px (default 1320)
- predefinedblocks.custom_path      General folder with Custom block types (all templates)
                                    (default {core_path}components/predefinedblocks/blocks/custom/,
                                    replaced on upgrade - point it to your theme)
- predefinedblocks.frontend_css     Stylesheet added to pages with blocks; empty = none
- predefinedblocks.frontend_js      Accordion script without Bootstrap; empty = none
- predefinedblocks.spacing_class    Pattern for spacing classes (default {prop}{side}-{size});
                                    reserved, spacing options are not enabled yet

Templates
---------
Each block has a Fenom template <block>.tpl, variants <block>.<variant>.tpl
(label from {* label: Name *} on the first line). The variables of every
block are listed in a comment at the top of its template. After changing
templates, "Clear cache" in the manager re-renders the affected pages.

Custom block
------------
One entry in the block list; the editor chooses the type. A type is a file
<name>.tpl in a custom folder with the fields in its header comment:
  {*
      block: Team member
      fields:
          name: text | Name | group=head
          role: text | Role | group=head
          text: richtext | Text
  *}
  <section id="b{$pb.id}"><h3>{$name}</h3>{raw $text}</section>
Field types: text, textarea, richtext, link, image, images, checkbox, select,
number, list, table, embed. Options: max, min, default, help, rows, group,
width (1-12), collapsible, options=key:Label,... The package ships two example
types in the general folder: "Call to action (example)" and "Pricing package
(example)". Until a type is chosen, the block lists the folders it reads.

Uninstall
---------
Removes the plugin and the system settings. The table pb_block (block data),
the rendered page content and the template properties are kept.

License: GPL-2.0-or-later. Bundled: SortableJS (MIT).
