$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.200

Twitter updates

  • Weekly update: Smooth rollout for ProcessWire 3.0.200 main/master, plus getting started on a new WP-to-PW site conversion and why they can be so rewarding— More
    20 May 2022
  • New main/master version of ProcessWire that has more than 220 commits, resolves more than 80 issues, adds numerous new features, performance improvements and optimizations, and consumes HALF the disk space of our previous release— More
    13 May 2022
  • Summary of weekly core updates for 22 April 2022 More
    22 April 2022

Latest news

  • ProcessWire Weekly #419
    In issue 419 of ProcessWire Weekly we'll check out this week's core updates, introduce a brand new recipe of the week, and more. Read on!
    Weekly.pw / 21 May 2022
  • ProcessWire 3.0.200 new master/main version
    This new main/master version has more than 220 commits, resolves more than 80 issues, adds numerous new features, performance improvements and optimizations, and consumes HALF the disk space of our previous release. This post covers all the details.
    Blog / 13 May 2022
  • Subscribe to weekly ProcessWire news

“To Drupal, or to ProcessWire? The million dollar choice. We decided to make an early switch to PW. And in retrospect, ProcessWire was probably the best decision we made. Thanks are due to ProcessWire and the amazing system and set of modules that are in place.” —Unni Krishnan, Founder of PigtailPundits