$page→render()

Render output of this Page or a Field

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 arguments definition).
A filename to use for render (in /site/templates/). When used, you can optionally specify an $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, though we'd recommend just using the renderField() 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 the template file, and those values will be available in a variable named $options within the scope of the template file (see examples below).

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.

For simpler and more specific methods, we recommend using, hooking or overriding renderPage() or renderField() instead.

Example

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

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

// render while passing in custom variables
$out = $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

// basic usage
$string = $page->render();

// usage with all arguments
$string = $page->render($options = [], array $options2 = null);

Arguments

Name Type(s) Description

Name	Type(s)	Description
`$options` (optional)	`array` `string`	String of filename to use for render, field name to render, or array of options: `foo_bar` (mixed): Specify any of your own variable names and values to send to the template file (foo_bar is just an example, use your own). `filename` (string): Filename to render, typically relative to /site/templates/. But absolute paths must resolve somewhere in PW’s install. Default:'' `prependFile` (string): Filename to prepend to output, must be in /site/templates/ Default:$config->prependTemplateFile `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. `allowCache` (bool): Allow cache to be used when template settings ask for it? Default:true `forceBuildCache` (bool): If true, the cache will be re-created for this page, regardless of whether it’s expired or not. Default:false Note that the prepend and append options above have default values in `$config` or with the Template.
`$options2` (optional)	`array`	If a filename or field name was used for $options then you may optionally specify options array here instead.

$options (optional)

array string

String of filename to use for render, field name to render, or array of options:

foo_bar (mixed): Specify any of your own variable names and values to send to the template file (foo_bar is just an example, use your own).
filename (string): Filename to render, typically relative to /site/templates/. But absolute paths must resolve somewhere in PW’s install. Default:''
prependFile (string): Filename to prepend to output, must be in /site/templates/ Default:$config->prependTemplateFile
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.
allowCache (bool): Allow cache to be used when template settings ask for it? Default:true
forceBuildCache (bool): If true, the cache will be re-created for this page, regardless of whether it’s expired or not. Default:false
Note that the prepend and append options above have default values in $config or with the Template.

$options2 (optional)

array

If a filename or field name was used for $options then you may optionally specify options array here instead.

Return value

string mixed

Exceptions

Method can throw exceptions on error:

WireException

Hooking $page→render(…)

You can add your own hook events that are executed either before or after the $page->render(…) 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 $page->render(…) method call is executed. This type of hook is especially useful for modifying arguments before they are sent to the method.

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

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

  /* Your code here, perhaps modifying arguments */

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

Hooking after

The 'after' hooks are called immediately after each $page->render(…) method call is executed. This type of hook is especially useful for modifying the value that was returned by the method call.

$this->addHookAfter('Page::render', function(HookEvent $event) {
  // Get the object the event occurred on, if needed
  $page = $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)
  $options = $event->arguments(0);
  $options2 = $event->arguments(1);

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

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