Add a new page using the given template and parent
If no page “name” is specified, one will be automatically assigned.
For an alternate interface for adding new pages, see the $pages->new() method.
Example
// Add new page using 'skyscraper' template into Atlanta
$building = $pages->add('skyscraper', '/skyscrapers/atlanta/');
// Same as above, but with specifying a name/title as well:
$building = $pages->add('skyscraper', '/skyscrapers/atlanta/', 'Symphony Tower');
// Same as above, but with specifying several properties:
$building = $pages->add('skyscraper', '/skyscrapers/atlanta/', [
'title' => 'Symphony Tower',
'summary' => 'A 41-story skyscraper located at 1180 Peachtree Street',
'height' => 657,
'floors' => 41
]);Usage
// basic usage
$page = $pages->add($template, $parent);
// usage with all arguments
$page = $pages->add($template, $parent, string $name = '', array $values = []);Arguments
| Name | Type(s) | Description |
|---|---|---|
template | string, Template | Template name or Template object |
parent | string, int, Page | Parent path, ID or Page object |
name (optional) | string | Optional name or title of page. If none provided, one will be automatically assigned. If you want to specify a different name and title then specify the $name argument, and $values['title']. |
values (optional) | array | Field values to assign to page (optional). If $name is omitted, this may also be 3rd param. |
Return value
PageNew page ready to populate. Note that this page has output formatting off.
Exceptions
Method can throw exceptions on error:
WireException- When some criteria prevents the page from being saved.
Hooking $pages->add(…)
You can add your own hook events that are executed either before or after the $pages 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 $pages method call is executed. This type of hook is especially useful for modifying arguments before they are sent to the method.
$this->addHookBefore('Pages::add', function(HookEvent $event) {
// Get the object the event occurred on, if needed
$pages = $event->object;
// Get values of arguments sent to hook (and optionally modify them)
$template = $event->arguments(0);
$parent = $event->arguments(1);
$name = $event->arguments(2);
$values = $event->arguments(3);
/* Your code here, perhaps modifying arguments */
// Populate back arguments (if you have modified them)
$event->arguments(0, $template);
$event->arguments(1, $parent);
$event->arguments(2, $name);
$event->arguments(3, $values);
});Hooking after
The 'after' hooks are called immediately after each $pages method call is executed. This type of hook is especially useful for modifying the value that was returned by the method call.
$this->addHookAfter('Pages::add', function(HookEvent $event) {
// Get the object the event occurred on, if needed
$pages = $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)
$template = $event->arguments(0);
$parent = $event->arguments(1);
$name = $event->arguments(2);
$values = $event->arguments(3);
/* Your code here, perhaps modifying the return value */
// Populate back return value, if you have modified it
$event->return = $return;
});See Also
API reference based on ProcessWire core version 3.0.244