$pages is your connection to all the pages in your site

While the $page variable holds the current page, the $pages variable is where you can get at all the other pages in your site. It includes functions for getting, finding, saving and deleting pages. Each of these is documented below, following by several examples.

Quick Reference

$pages->find("selector")Find and return all pages matching the given selector string. Returns a PageArray.
$pages->get("selector")Get the page matching the given selector string. Returns a Page, or a NullPage if not found.
$pages->get(123)Get the page matching the given numeric ID. Returns a Page, or a NullPage if not found.
$pages->get("/path/to/page/")Get the page matching the given path or URL. Returns a Page, or a NullPage if not found.
$pages->save($page)Save any changes made to the given $page.
Same as: $page->save()
$pages->saveField($page, 'field')Save just the named field from $page. (v2.1+)
Same as: $page->save('field')
$pages->trash($page)Move the given page to the Trash.
$pages->delete($page)Permanently delete the given page and any attached media. Throws error when $page has children.
$pages->delete($page, true)Recursively delete $page and all it's children and attached media, permanently. 
$pages->clone($page)Creates a brand new cloned copy of the given page (and any children) and returns it.  (v2.1+)
$pages->clone($page, $parent)Like the above, but with a new $parent page specified. (v2.1+)
$pages->clone($page, $parent, false)Like the above, but only the given page will be cloned (and not any children). (v2.1+)

Examples of getting and finding pages

These examples correspond to the skyscrapers demo site. For this first example, we'll get a specific page and print it's title:

echo $pages->get("/cities/chicago/sears-tower/")->title; 

Find all skyscrapers (i.e. pages using the skyscraper template). Then make a list linking to each of them. Note that this foreach() example below also applies to all examples below this – the foreach() has been left out of later examples for brevity.

$skyscrapers = $pages->find("template=skyscraper");
foreach($skyscrapers as $s)
    echo "<li><a href='{$s->url}'>{$s->title}</a></li>";

Find all skyscrapers with a height greater than 500 ft, and less than or equal to 1000 ft:

$skyscrapers = $pages->find("template=skyscraper, height>500, height<=1000");

Find all skyscrapers in Chicago with 60+ floors, sorted by floors ascending:

$skyscrapers = $pages->get("/cities/chicago/")->find("floors>=60, sort=floors");

Find all skyscrapers built before 1950 with 10+ floors, sorted by year descending, then floors descending:

$skyscrapers = $pages->find("template=skyscraper, year<1950, floors>=10, sort=-year, sort=-floors");

Find all skyscrapers by architects David Childs or Renzo Piano, and sort by height descending:

$david = $pages->get("/architects/david-childs/");
$renzo = $pages->get("/architects/renzo-piano/");
$skyscrapers = $pages->find("architect=$david|$renzo, sort=-height");

Find all skyscrapers that mention the words "limestone" and "granite" somewhere in their body copy:

$skyscrapers = $pages->get("/cities/")->find("template=skyscraper, body~=limestone granite");

Find all skyscrapers that mention the phrase "empire state building" in their body copy:

$pages->get("/cities/")->find("template=skyscraper, body*=empire state building");

Examples of saving and deleting pages

Load a page, change it's year field and save it:

$skyscraper = $pages->get("/cities/chicago/sears-tower/"); 
$skyscraper->year = 1974;
$pages->save($skyscraper); // $skyscraper->save() does the same thing

Find all pages with the text "Sears Tower" in their bodycopy, and update them to say "Willis Tower":

foreach($pages->find("body*=Sears Tower") as $p) {
    $p->body = str_replace("Sears Tower", "Willis Tower", $p->body);
    $p->save();
} 

Create a new skyscraper page in Atlanta and save it, then add an image and save again:

$skyscraper = new Page();
$skyscraper->template = $templates->get("skyscraper");
$skyscraper->parent = $pages->get("/cities/atlanta/");
$skyscraper->title = "W-Hotel Tower";
$skyscraper->height = 400;
$skyscraper->year = 2009;
$skyscraper->body = "This is a nice hotel and it has a helicopter landing pad on top of it."
$skyscraper->save();
$skyscraper->images->add("http://starwoodhotels.com/w-atlanta.jpg");
$skyscraper->save();

Find all skyscrapers built in the 1950s and move them to the trash:

$skyscrapers = $pages->find("year>=1950, year<1960");
foreach($skyscrapers as $skyscraper) {
    $pages->trash($skyscraper);
}

Permanently delete a page:

$p = $pages->get("/about/locations/southpark/"); 
$pages->delete($p);
// or: $pages->get("/about/locations/southpark/")->delete();

Permanently delete a page and all it's children. In this case it will delete a city page and all the skyscrapers below it:

$city = $pages->get("/cities/houston/"); 
$pages->delete($city, true); // specify true as a second param to make the delete recursive

Note about access roles and pages

In the ProcessWire API, the results of any page selection functions like get(), find(), children() and siblings() do not consider roles. If the page is in your site tree, you can select it in the API regardless of what access roles it has. This is so that you can continue to use assets from a page in the API even if the page isn't a URL on your site. 'Page' is just an abstract term that doesn't have to refer to a page on your site... You might be using a page for storage of shared image assets, site configuration or other items that you don't want to be directly accessible via a URL, but you DO want to utilize in the API.

As a result, if you don't want a page showing up in navigation or search results you can do one of 2 things: 

  1. Check the box for the 'hidden' status when editing a page, which will hide it from find(), children() and siblings() methods. The page will still be accessible via it's URL unless you remove the 'guest' role. 
  2. Or, when generating your navigation, check if the page is viewable before outputting the link via $page->isViewable(). For example:
foreach($page->children() as $child) {
    if($child->isViewable()) echo "<a href='{$child->url'}'>{$child->title}</a> ";
}

I don't like having to check access from the API, so recommend doing #1 over #2. In the near future, automatic access checking will be an option you can optionally enable with API functions (should you want to). 

See Also

$page
PageArray

Comments

  • diogo

    diogo 6 years ago 11

    I'm not experienced with PHP, but I think there is a small s missing on the 4th "saving and deleting pages" example.

    Should be "foreach($skyscrapers as $skyscraper)" instead of "foreach($skyscraper as $skyscraper)", no?

    Congratulations on ProcessWire, Ryan. Looks like a great CMS :)

  • Nico

    Nico 4 years ago 11

    There is a semicolon (;) missing after: $skyscraper->body = "This is a nice hotel and it has a helicopter landing pad on top of it."

Post a Comment

Your e-mail is kept confidential and not included with your comment. Website is optional.