PageRender::renderPage() method

Return a string with the rendered output of this Page from its template file (other usages available as well)

This method provides the implementation for $page->render() and you sould only call this method as render() from Page objects.

You may optionally specify 1-2 arguments to the method. The first argument may be any of the following:

An $options array with predefined options or custom variables (see available options further below).
A filename to use for render (in /site/templates/). When used, you can optionally specify the $options array as the 2nd argument.
A field name to render. An optional 2nd argument can be a filename (in /site/templates/fields/) to use to render the field. Please see the Page::renderField() method for more details for this usage (you may want to use that method instead).

If using the $options array argument (whether 1st or 2nd argument), you may use it to specify your own variables to pass along to your template file, and those values will be available in a variable named $options within the scope of the template file (see examples below).

In addition, the following options are present and recognized by the core:

forceBuildCache (bool): If true, the cache will be re-created for this page, regardless of whether it’s expired or not. (default=false)
allowCache (bool): Allow cache to be used when template settings ask for it. (default=true)
filename (string): Filename to render, optionally relative to /site/templates/. Absolute paths must resolve somewhere in PW’s install. (default=blank)
prependFile (string): Filename to prepend to output, must be in /site/templates/.
prependFiles (array): Array of additional filenames to prepend to output, must be relative to /site/templates/.
appendFile (string): Filename to append to output, must be in /site/templates/.
appendFiles (array): Array of additional filenames to append to output, must be relative to /site/templates/.
pageStack (array): An array of pages, when recursively rendering. Used internally. You can examine it but not change it.

Note that the prepend and append options above have default values that have defaults configured in $config or the Template object.

Note: If the page’s template has caching enabled, then this method will return a cached page render (when available) or save a new cache. Caches are only saved on guest users.

Example

// regular page render call
$output = $page->render();

// render using given file (in /site/templates/)
$output = $page->render('basic-page.php');

// render while passing in custom variables
$output = $page->render([
  'firstName' => 'Ryan',
  'lastName' => 'Cramer'
]);

// in your template file, you can access the passed-in variables like this:
echo "<p>Full name: $options[firstName] $options[lastName]</p>";

Usage

$pageRender->renderPage(HookEvent $event);

Arguments

Name	Type(s)	Description
`event`	HookEvent

Exceptions

Method can throw exceptions on error:

WirePermissionException or Wire404Exception or WireException

Hooking PageRender::renderPage(…)

You can add your own hook events that are executed either before or after the PageRender::renderPage(…) method is executed. Examples of both are included below. A good place for hook code such as this is in your /site/ready.php file.

Hooking before

The 'before' hooks are called immediately before each PageRender::renderPage(…) method call is executed. This type of hook is especially useful for modifying arguments before they are sent to the method.

$this->addHookBefore('PageRender::renderPage', function(HookEvent $event) {
  // Get the object the event occurred on, if needed
  $PageRender = $event->object;

  // Get values of arguments sent to hook (and optionally modify them)
  $event = $event->arguments(0);

  /* Your code here, perhaps modifying arguments */

  // Populate back arguments (if you have modified them)
  $event->arguments(0, $event);
});

Hooking after

The 'after' hooks are called immediately after each PageRender::renderPage(…) method call is executed. This type of hook is especially useful for modifying the value that was returned by the method call.

$this->addHookAfter('PageRender::renderPage', function(HookEvent $event) {
  // Get the object the event occurred on, if needed
  $PageRender = $event->object;

  // An 'after' hook can retrieve and/or modify the return value
  $return = $event->return;

  // Get values of arguments sent to hook (if needed)
  $event = $event->arguments(0);

  /* Your code here, perhaps modifying the return value */

  // Populate back return value, if you have modified it
  $event->return = $return;
});

PageRender methods and properties

API reference based on ProcessWire core version 3.0.236