Blocks

To render your markup, you need to add block templates to your PAGEGRID field.
Go to Setup > PAGEGRID and select the blocks you want to use for your PAGEGRID field.

Block modules

Use and customise our ready-made blocks, or ignore them and create your own block templates.

To use them, go to Setup > PAGEGRID and click on download block modules.

Block modules load the block template files from site/modules/PageGridBlocks/blocks. If you want to modify any of the files, copy them to your site/templates/blocks folder.

Create a custom block

Create a new .php file in the blocks directory under site/templates/blocks/.

Go to Setup > PAGEGRID, select your file and click save.

Block template files can be as simple as a plain HTML file, or they can be as complex as as an entire PHP application.

Optionally, you can also create a .css or .js file (or both) with the same name as your .php file. This will tell PAGEGRID to load those files automatically when this block gets rendered.

Add fields to your block

A template can have multiple fields to hold your data.

To add fields to your template, go to Setup > Templates > YourTemplate and select the fields you want to use. You can use all the fields ProcessWire provides or add even more fields using external Fieldtype modules from the modules directory.

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 PageGridBlocks Module!

Output content from a field

Taking a value from your block item and outputting it from your template file is very simple. Here is an example of a line in a template file that outputs the text field named "myText":

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

The $page variable contains all the fields present on the block template. Every one of those fields can be referenced like the "myText" field above. Learn more about template files in ProcesWire.

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. All PAGEGRID functions are available through the $pagegrid variable (regardless of the field name).

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 this function at the top of your block template file to make your block a container and allow new items to be added to it. New items get added as children to your block page.

 <?php $pagegrid->renderOptions(["children" => true]);  ?>

To render the children, use the renderItem function inside the container block.

<?php
foreach($page->children() as $item) {
  echo $pagegrid->renderItem($item); 
}
?>

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

Wrapper Element

PAGEGRID wraps each item that gets created from your template with a wrapper element. Add this function at the top of your block template file to change the wrapper element to something else than "div". You can also let users change the element in the style panel.

<?php 
// use "h2" as the wrapper element and let the user change it
$pagegrid->renderOptions(['page' => $page, 'tag' => 'h2', 'tags' => 'h1 h2 h3 h4 h5 h6']); 
?>

Parameters Array

'page' => $page ProcessWire Page
'tag' => 'div' Optionally set HTML tag (default div) – the tag to use for the wrapping element (will only affect new items)
'tags' => 'h1 h2 h3 h4 h5 h6' Optionally let the user choose the tag in the Style Panel
'forceTag' => 'false' Optionally force tag for every existing item with the same template (default false)
'classes' => 'class1 class2 class3' Optionally add additional CSS classes to the wrapping element

Backend/Frontend

In PHP you can use this variable 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.

PAGEGRID wraps each item with a wrapper element. This wrapper and the HTML elements inside your block template can be styled by tagname and classes.

Optionally, 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);

Reinitialize javascript for the backend (optional)

In the backend PAGEGRID uses ajax to update the content of your block items without reloading the page. This happens when you edit an element inside the content panel (clicking the pen icon on an element).

If you want custom javascript code to be executed again after the ajax call has been completed. You need to set the iFrame document context like this.

<?php if ($pagegrid->isBackend() && $config->ajax) { ?>
 <script>
  let iframe = document.querySelector('.pg-iframe-canvas');
  let doc = iframe ? iframe.contentDocument || iframe.contentWindow.document : document;
  // now you can get an element like this
  doc.querySelector('.my-element');
 </script>
<?php return; } ?>

Examples

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

PAGEGRID Docs