Example: Add page/sub-page via PW API

[EyeDentify]

Hello Fellow PW fans.

I have since i started using PW allways been a bit afraid to use the API:s more advanced functions.

Like creating pages or subpages on the fly in my PHP code in the page template file.
So i read alot and finaly got a Eureka the other day. And have now tinkered around a bit and this simple example is the result.
It´s just the bare basics. You could make this more advanced in infinity.

I wanted to put this example somewhere for the future because i don´t think there is such a clean to the point example anywhere on the forums.
All the others are deep within discussion threads with advanced stuff that are not of concern for people who looking for a simple example to start from.

Notes:

You should log in as admin before trying to run this code in your page template.
I put the parent page i use in my testing as unpuplished for security.

As allways, the API reference:

https://processwire.com/api/ref/ 

is allways great to have when tinkering with the API.

Any ways, here it comes, and you have to change paths and such to your requirements.

<?PHP
/* some random strings and stuff for testing */
$randTitle = 'test_' . mt_rand(0, 1000000);
$randHash = 'test_' . md5(mt_rand(0, 100000) + time());

/* 
    Example: Creating a new sub page to a parent page via API
    Author: EyeDentify

    This example do not check if the page name allready exist it
    just tries to save it no mather what. so you have to create that
    check your self.
    
*/

/* get parent page object to add sub page object to */
$addParent = $pages->get('/api-test-start/');

/* Instantiate a new page object */
$newPage = new Page();

/* turn output formating of for property manipulation */
$newPage->of(false);

/* set the page objects parent so it is saved in the right place */
$newPage->parent = $addParent;

/* set the name of the template to be used wich we uploaded before hand. */
$newPage->template = 'tmp_api_test_post';

/* sanitize and set page name and also used in the path */
$newPage->setName($sanitizer->pageNameUTF8($randTitle));

/* the title */
$newPage->title = $sanitizer->text($randTitle);

/* set custom fields propertys, the ones we created ourselfs */
$newPage->api_test_hash = $randHash;

/* save the page object to database as child of the given parent */
$newPage->save();

/* turn on output formatting again, importent because it should be ON when outputting it in template files later on. */
$newPage->of(true);
?>

 

This is kind of a example and code template in one.

I hope this can get others started that are beginners like myself to get more advanced with the PW API.

I expect there is propably things that should be done a certain way but this is my way.

Good luck with your API adventures.

 

Update

created a gist for the github users of the PW community of this example.
https://gist.github.com/magnusbonnevier/4dbb3a28634a9b76bbf5855dd871606f
 

 

Edited September 19, 2016 by EyeDentify
Added the github Gist URL.

[szabesz]

@EyeDentify Thanks for sharing!

May I ask why you turned on output formatting before saving? It is recommended to save first, then turn it on (if it needs to be ON, like normally in the case of the frontend).

See for example: https://processwire.com/blog/posts/processwire-2.6.9-core-updates-and-new-procache-version/#new-page-gt-setandsave-method

API doc: https://processwire.com/api/ref/page/of/

[EyeDentify]

Just now, szabesz said:

@EyeDentify Thanks for sharing!

May I ask why you turned on output formatting before saving? It is recommended to save first, then turn it on (if it needs to be ON, like normally in the case of the frontend).

See for example: https://processwire.com/blog/posts/processwire-2.6.9-core-updates-and-new-procache-version/#new-page-gt-setandsave-method

API doc: https://processwire.com/api/ref/page/of/

I may have gotten things around about output filtering.

I know though that you should put it to Off when manipulating the field propertys and to ON when done doing so.

What difference it makes before saving or not i honestly dont know but i put it to ON so i don´t forget it.

But it should be ON before you output to a template with the page object.

[LostKobrakai]

You should probably take a look at this one, which does the same, but far less verbose: https://processwire.com/api/ref/pages/add/

[EyeDentify]

1 minute ago, LostKobrakai said:

You should probably take a look at this one, which does the same, but far less verbose: https://processwire.com/api/ref/pages/add/

Thank you LostKobrakai.

I have seen it, but i wanted to use this method for learning things a little more advanced but your example is certaintly a way to go.

[szabesz]

16 minutes ago, EyeDentify said:

But it should be ON before you output to a template with the page object.

Sure, so that we get the formatted attribute. However, I would do:

/* save the page object to database as child of the given parent */
$newPage->save();

/* turn on output formatting again, important before outputting in template files */
$newPage->of(true);

Note that it is called formatting and not filtering.

[EyeDentify]

 

Just now, szabesz said:

Sure, so that we get the formatted attribute. However, I would do:

/* save the page object to database as child of the given parent */
$newPage->save();

/* turn on output formatting again, important before outputting in template files */
$newPage->of(true);

Note that it is called formatting and not filtering.

Allready ahead of you

[EyeDentify]

Would this be a correct way of using your example Lostkobrakai ?
 

<?PHP
/* Shorter less verbose example, thanks to Lostkobrakai for the tip. */

/* array of propertys */
$pagePropertysArray['title'] = $sanitizer->text($randTitle);
$pagePropertysArray['name'] = $sanitizer->pageNameUTF8($randTitle);
$pagePropertysArray['api_test_hash'] = $randHash;

/* add to a page object with parent path and new pages template name */
$newPage = $pages->add('tmp_api_test_post', '/api-test-start/', $pagePropertysArray); 

/* save it */
$newPage->save();

/* turn output formatting on */
$newPage->of(true);
?>

 

[LostKobrakai]

It can be as short as this: 

<?php
/* add to a page object with parent path and new pages template name */
$newPage = $pages->add('tmp_api_test_post', '/api-test-start/', $randTitle, array(
	'title' => $sanitizer->text($randTitle),
	'api_test_hash' => $randHash
))->setOutputFormatting(true); 

The longform function to enable output formatting does return the page instead of the current of of status, so you can simply append it, whereas ->of() would make your $newPage variable useless.

[EyeDentify]

8 minutes ago, LostKobrakai said:

It can be as short as this: 

<?php
/* add to a page object with parent path and new pages template name */
$newPage = $pages->add('tmp_api_test_post', '/api-test-start/', $randTitle, array(
	'title' => $sanitizer->text($randTitle),
	'api_test_hash' => $randHash
))->setOutputFormatting(true); 

The longform function to enable output formatting does return the page instead of the current of of status, so you can simply append it, whereas ->of() would make your $newPage variable useless.

Oki. But my example was not wrong ?

Besides, i like my verbose first example

[LostKobrakai]

They do all work.