Weekly update – 10 December 2021

[ryan]

There's a new $pages->new() API method on the core dev branch this week. This method is similar to the $pages->add() method, in that it is used to add new pages to the DB, but is a lot better in my opinion.

The $pages->add() method has arguments that you have to remember, whereas $pages->new() accepts a single-argument selector string, like many of the other $pages API methods. This new method can also auto-detect some properties that the add() method cannot (like parent or template). 

Let's take a look at how to use it. Here we create a new page from a selector string, and it returns the new page (saved in the database):

$p = $pages->new("template=category, parent=/categories/, title=New Category");

If you prefer, you can also use an array:

$p = $pages->new([
  'template' => 'category',
  'parent' => '/categories/',
  'title' => 'New Category'
]);

The page name and parent can be auto detected if you specify a path:

$p = $pages->new('path=/blog/posts/foo-bar-baz');

But if you start the selector string with "/" then it is assumed to be the path, so this is is exactly the same thing as above:

$p = $pages->new('/blog/posts/foo-bar-baz');

In your selector string or array, you can specify any page property or field name that you want to set with the new page. It's basically just a quicker way to do something that's already pretty easy to do, but I thought people might find this new option even more handy in many instances.

To create a new page, it needs to know the template and the parent. If your template family settings are configured in a manner where it can auto-detect, then it will do so, at which point parent or template becomes optional. In the last example above, it detected that the template was "blog-post" and the parent was "/blog/posts/".

A few things to note (pulled from the method documentation): 

• 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 a 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. 
• The `class` of the Page will be auto-detected when applicable (and something different than `Page`). 
• An exception will be thrown if it doesn’t have enough information to create a new page in the database.

I've also updated the existing $pages->newPage() method to accept the same selector string (or array). You might already be familiar with this method, but if not, it creates a new page in memory, but not the database. So you might use it to create a new page that you will call save() upon later. 

$p = $pages->newPage('template=blog-post, name=hello-world'); 

This week the core also has a few issue fixes. I'll wait another week before bumping the dev branch version though, as there's more to add first. Though the next few weeks might be little slower on core updates as the end-of-the-year seems to always be the busiest time when it comes to client work... everyone wants to wrap things up before the new year, and I do my best to accommodate that, while also keeping PW updates in progress. Thanks for reading and have a great weekend! 
 

[Ivan Gretsky]

I've searched the API reference for $pages and couldn't find the description for $pages->newPage(). Should it be there?

[adrian]

2 hours ago, Ivan Gretsky said:

I've searched the API reference for $pages and couldn't find the description for $pages->newPage(). Should it be there?

I can't find it there either, but Tracy has you covered :)