$pages->new() method

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 template must be specified, unless it can be auto-detected from a given parent.
  • A parent must be specified, unless it can be auto-detected from a given template or path.

Please note the following:

  • If a path is specified but not a name or parent then both will be derived from the path.
  • If a title is specified but not a name or path then the name will be derived from the title.
  • If given parent or path only allows one template (via family settings) then template becomes optional.
  • If given template only allows one parent (via family settings) then parent becomes optional.
  • If given selector string starts with a / it is assumed to be the path property.
  • 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, path or title is 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

NameType(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->new(…) 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->new(…) 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->new(…) 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


$pages methods and properties

API reference based on ProcessWire core version 3.0.236

Latest news

  • ProcessWire Weekly #518
    The 518th issue of ProcessWire Weekly brings in all the latest news from the ProcessWire community. Modules, sites, and more. Read on!
    Weekly.pw / 13 April 2024
  • ProFields Table Field with Actions support
    This week we have some updates for the ProFields table field (FieldtypeTable). These updates are primarily focused on adding new tools for the editor to facilitate input and management of content in a table field.
    Blog / 12 April 2024
  • Subscribe to weekly ProcessWire news

“I am currently managing a ProcessWire site with 2 million+ pages. It’s admirably fast, and much, much faster than any other CMS we tested.” —Nickie, Web developer