Blocks

To use PAGEGRID you need to add block templates to your PAGEGRID field.

Go to Setup > PAGEGRID and select the blocks you want to use.

You can use and customise our ready-made blocks, or create your own block templates.

Block modules

To use our ready-made blocks, go to Setup > PAGEGRID and click on download block modules. Next select the blocks you want to use and click save.

To modify a block, copy the corresponding file from site/modules/PageGridBlocks/blocks to your site/templates/blocks folder.

Create a custom block

This guide will walk you through the process of creating your own custom block using ProcessWire's templates and fields. Don't be afraid, it's easier than you think.

1. Create Your Block Template File

In site/templates/blocks/, create your_block_name.php
Optionally, add your_block_name.css and your_block_name.js for styling/scripts.

2. Register Your Block with PAGEGRID

In ProcessWire Admin, go to Setup > PAGEGRID.
Select your PHP file and click Save.

3. Defining Block Fields (optional)

Go to Setup > Templates in the ProcessWire Admin.
Find the template that corresponds to your block (it will have the same name as your php file).
Add the fields that your block will use.

4. Build Your Block's Markup

Open your block's PHP template file (e.g., your_block_name.php).
Add the HTML markup and PHP logic that defines the structure and content of your block.
Accessing Block Fields
To display data entered into your block's fields, use the $page object within your template. The fields available within $page correspond to the fields you've defined in your block's template settings in the ProcessWire Admin.
Example: If you have a text field named myText in your block's template settings, you can display its value like this:

<h1><?= $page->myText ?></h1>

Don't use the name prefix "pg" for your block templates and fields (e.g. "pg_myblock") to avoid naming conflicts with the templates and fields created by the block modules!

Customize your block

In your block template file, you can use all of the API variables ProcessWire provides. Additionally, PAGEGRID comes with some options to customize your block templates.

Wrapper Element

By default PAGEGRID wraps your content inside a <div> element.

If you need to control the markup of the wrapper element, add the pg-wrapper attribute to the root element of your block's HTML.

Example: Define the <h1> element as the wrapper and add a custom class:

<h1 class="my-class" pg-wrapper>Hello World</h1>

Wrapper Element Attributes

The wrapper element behaves like a normal HTML element, but it's much more powerful. It lets you define special attributes to control how PAGEGRID is interacting with your block. These attributes will not be shown on the frontend.

You can use the following attributes for your PAGEGRID blocks:

Children `pg-children`

PAGEGRID items can be nested. This can be used for layout purposes or to group items together. Another example might be a slider or gallery block that the user can add items to.

Add pg-children="true" to your wrapper to allow users to add children to your block.
Example: Here we loop through the children and use the function $pagegrid->renderItem() to render the children directly inside wrapper element. This will tell PAGEGRID to render the children like any other block, allowing users to use the drag and resize features:

<section pg-children="true" pg-wrapper>
  <?php foreach($page->children() as $item) { ?>
    <?= $pagegrid->renderItem($item); ?>
  <?php } ?>
</section>

This is just an example. You have full control over the markup of the children. Instead of using the function $pagegrid->renderItem() to render the children, you can also define your own markup inside the foreach loop. Also the children don't have to be direct children of the wrapper. More examples: Slider Block, Accordion Block.

Define allowed templates for children

If you want to control which block types can be nested within your container, you can specify the allowed template names in the pg-children attribute.
Example: Allowing only "block_foo" and "block_bar" as child blocks:

<section pg-children="block_foo block_bar" pg-wrapper>
  <?php foreach($page->children() as $item) { ?>
    <?= $pagegrid->renderItem($item); ?>
  <?php } ?>
</section>

You can give other users permission to add children to a block (by drag and drop or via modal edit).

Children Label `pg-children-label`

The attribute pg-children-label defines a label for the children tab and the add new button when editing a block with the pg-children attribute.

<section pg-children="true" pg-children-label="My Items" pg-wrapper>
  <?php foreach($page->children() as $item) { ?>
    <?= $pagegrid->renderItem($item); ?>
  <?php } ?>
</section>

Children Tab `pg-children-tab`

When editing a block item in the content panel of the admin (by clicking on the pen icon) and the pg-children attribute is set, the children field will be shown in it’s own tab.

Use the attribute pg-children-tab="append" to append the children field to the content tab instead. You can also use pg-children-tab="prepend" to insert the children field before any other fields.

<section pg-children="true" pg-children-tab="append" pg-wrapper>
  <?php foreach($page->children() as $item) { ?>
    <?= $pagegrid->renderItem($item); ?>
  <?php } ?>
</section>

Disable automatic title/name for children `pg-autotitle`

PAGEGRID generates a title and a name for your child items automatically. Set the attribute pg-autotitle="false" if you want users to enter a title/name manually.

<section pg-children="true" pg-autotitle="false" pg-wrapper>
  <?php foreach($page->children() as $item) { ?>
    <?= $pagegrid->renderItem($item); ?>
  <?php } ?>
</section>

Disable javascript execution for ajax calls inside the backend `pg-reload-script`

Only set this option if you use a javascript block file (e.g. your_block_name.js) and your javascript code is causing errors in the backend after ajax calls. This is not needed in most cases and should only be used if the errors can not be fixed otherwise.

To disable the execution of your javascript block file after PAGEGRID ajax calls, add the attribute pg-reload-script="false" to your wrapper element.

<h1 pg-reload-script="false" pg-wrapper>Hello World</h1>

Backend/Frontend

In PHP you can use this function to check whether the template is rendered in the backend or frontend of your website.

<?php 
if($pagegrid->isBackend()) { 
  // render things only for the backend
} else {
  // render things only for the frontend
}
?>

In Javascript you can use this check.

var isBackend = document.querySelectorAll('.pg-is-backend').length;
if(isBackend) { 
  // run JS only for the backend
} else {
  // run JS only for the frontend
}

Style Panel

If enabled in the field settings, superusers or users with the “pagegrid-style-panel” permission will be able to style HTML elements visually right on the page.

Note that its use is completely optional. You can also write CSS with your favorite code editor or use a CSS framework if you prefer.

HTML elements inside your block template can be styled by tagname and classes.

Optionally you can add the attribute "data-class" with a class name to any HTML element inside your block template, to make the style panel use that class as the default selector.

<span class="myclass" data-class="myclass">This element will use the class "myclass"</span>

The style panel allows users to add custom CSS classes to block items. If you want you can also let users add classes to other elements within your block template with the getCssClasses function.

<span class="myclass <?= $pagegrid->getCssClasses($page, 'myclass') ?>" data-class="myclass">Hello World</span>

Inline editor

Superusers and users with the permission "page-edit-front" can use the inline editor to edit content directly on the page.

Text fields will become editable automatically by checking the boxes next to each field on the PAGEGRID module settings in the backend.

To enable the file uploader for your block template, place an image or video inside a "pg-edit" tag and add a "page" and a "field" attribute to it. Only single value image/file fields are supported.

<pg-edit page='<?= $page->id ?>' field='image'>
<?php if($page->image) { ?>
 <img src='<?= $page->image->url ?>'>
<?php } ?>
</pg-edit>

Get main page

You can call this function from one of your block templates to get the main page of that block.

// inside a block template file $page refers to the block item.
// Use this function to get the main page that has your pagegrid field.
$mainPage = $pagegrid->getPage($page);

Examples

To see more code examples, check out the PAGEGRID Blocks Module.

PAGEGRID Docs