Create a new Page populated from selector string or array
This is similar to the $pages->add() method but with a simpler 1-argument (selector) interface. This method can also auto-detect some properties that the add() method cannot.
To create a new page without saving to the database use the $pages->newPage() method instead. It accepts the same arguments as this method.
Minimum requirements to create a new page that is saved in database:
- A
templatemust be specified, unless it can be auto-detected from a givenparent. - A
parentmust be specified, unless it can be auto-detected from a giventemplateorpath.
Please note the following:
- If a
pathis specified but not anameorparentthen both will be derived from thepath. - If a
titleis specified but not anameorpaththen thenamewill be derived from thetitle. - If given
parentorpathonly allows one template (via family settings) thentemplatebecomes optional. - If given
templateonly allows one parent (via family settings) thenparentbecomes optional. - If given selector string starts with a
/it is assumed to be thepathproperty. - If new page has name that collides with an existing page (i.e. “foo”), new page name will increment (i.e. “foo-1”).
- If no
name,pathortitleis given (that name can be derived from) then an “untitled-page” name will be used.
Available since version 3.0.191.
Example
// Creating a page via selector string
$p = $pages->new("template=category, parent=/categories/, title=New Category");
// Creating a page via selector using path, which implies parent and name
$p = $pages->new("template=category, path=/categories/new-category");
// Creating a page via array
$p = $pages->new([
'template' => 'category',
'parent' => '/categories/',
'title' => 'New Category'
]);
// Parent and name can be auto-detected when you specify path…
$p = $pages->new('path=/blog/posts/foo-bar-baz');
// …and even 'path=' is optional if slash '/' is at beginning
$p = $pages->new('/blog/posts/foo-bar-baz');Usage
// basic usage
$page = $pages->new();
// usage with all arguments
$page = $pages->new($selector = '');Arguments
| Name | Type(s) | Description |
|---|---|---|
selector (optional) | string, array | Selector string or array of properties to set |
Return value
Hooking $pages->new(…)
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::new', 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)
$selector = $event->arguments(0);
/* Your code here, perhaps modifying arguments */
// Populate back arguments (if you have modified them)
$event->arguments(0, $selector);
});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::new', 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)
$selector = $event->arguments(0);
/* 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.236