Ryan Cramer

Content Management

ProcessWire - Developer API

A brief overview covering the basics of ProcessWire’s application programming interface

Note that this article is specific to the ProcessWire v1 developer API. There is also the ProcessWire 2.0 Developer API.

ProcessWire’s PHP-based developer API is loosely inspired by jQuery’s syntax. Pages are located and retrieved by selectors in a manner not unlike DOM elements are retrieved in jQuery. Many methods use a fluent chaining interface, allowing you to bundle a good deal of work into a single expression (when it makes sense to do so).

Getting the value of a field

From within a template, working with the fields on the current page is a simple matter. You just dereference the $page object with a field name, e.g. $page->bodycopy. The field name must be one that you have defined within the fields attached to the template. You can also obtain the value of any field by using something called Tagscript syntax, e.g. . More about this later.

Retrieving pages

You can retrieve pages using their unique numeric ID, but that’s not particularly intuitive. So you can also retrieve pages using their URL or absolute path, their relative path (from current page), or their placement relative to another page (e.g. retrieve the first page that has X as a parent). Furthermore, you can retrieve pages based on what they contain, be that a snippet of text, a reference to another page, a particular image, or just about anything.

Page Retrieval Code Examples

Retrieve a page by ID:
$mypage = $pages->get(123); 
Retrieve a page by path:
$mypage = $pages->get("/about/contact/directory/ceo");
Retrieve a page by relative path (we’re backtracking in this case):
$mypage = $pages->get("../../");
Retrieve a page by relative placement (get the last sibling):
$mypage = $page->parent->children()->last();
Retrieve subpages of current page that contain the word “ryan” in the field “bodycopy”:
$mypages = $page->children("bodycopy*=ryan");
Retrieve all pages that have a name field starting with “Welcome”:
$mypages = $pages->find("name^=Welcome");
Retrieve all pages that contain the phrase “apple ipod” in any field, and have a “quantity” field greater than 1:
$mypages = $pages->find("*='apple ipod', quantity>1");
Retrieve all press releases that cross reference the current page with the ‘topics’ field:
$mypages = $pages->get("/press/releases/")->children("topics=$page");

Building Custom Search Engines

Taking this syntax further, you can see that ProcessWire makes it relatively simple to build any kind of search engine. Here are a couple of examples of live search engines in ProcessWire from the Nanotechnology Project:

Main site search engines (simple):

http://www.synbioproject.org/tools/search/?q=biology
http://www.nanotechproject.org/search/?q=biology

EH&S Search Engine (complex):

http://www.nanotechproject.org/inventories/ehs/search/

Tagscript Syntax

Tagscripts are a means by which to obtain a field’s value or execute logic, and they are always surrounded by curly quotes, i.e. {example}. Use of Tagscripts is of course optional, but they can be handy in many instances. You may access the value of any field on the current page by typing the field name between curly quotes, i.e. {subtitle}. These Tagscripts can be populated into a page’s template, like this:

<h1>{headline}</h1>
<h2>{subtitle}</h2>

Tagscripts can also be typed directly into a page’s fields in the page editor. Meaning, one field can load a value from another, if desired.

Tagscripts can reference data on other pages too. For instance:

Please fax us your resume at {fax, page=/contact} 
if you would like to apply to this position.

But Tagscripts can do more than just output values. They can also be used to perform nearly any API function you want to define. See this screencast (to be added) which demonstrates a {page_list} Tagscript we’ve created to output a listing of subpages wherever we insert it.

The built-in Tagscript tool is intended for more basic needs. If you want to build a Tagscript that is broad enough in scope so as to need it’s own functions and/or libraries, then Tagscripts can be added as plugins.

Data Sharing

Pages can pull any piece of data from one another, be that textual content, images, files, cross-references, or the like. (That is, assuming that no permissions have been setup to limit such sharing). Here are a few examples of this, along with simple template API code samples for those interested:

Iterating through the current page’s family tree to generate a breadcrumb trail:
$parent = $page;   
while($parent = $parent->parent) 
    echo "<a href='‘></a> “;
Pulling the office phone number from a site’s contact page to populate elsewhere (like in the site’s footer):
echo "Tel: " . $pages->get("/about/contact/")->phone; 
The above code sample could also be duplicated with tagscript syntax:
Our number is: {phone, page=/about/contact}
Grabbing a random image from another page we’d setup for storing assets:
$i = $pages->get("/assets/fun/")->images->getRandom();  
echo "<img src='’ alt=’’ />”;
We’re on the homepage. Grab the headline and summary from the latest news item and output it:
echo "<h3>Latest News</h3>";
$item = $pages->get("/news/")->children()->first();
echo "<h4><a href='‘></a><h4>”;
echo “<p></p>”;

Note that the {brackets} used in the examples above are PHP syntax, not Tagscript syntax. These are just a few simple examples that barely scratch the surface, but hopefully demonstrate basics of page-to-page data sharing.

More soon

This article just glosses over a few parts of the developer API. Full API documentation is in the works.

—Ryan Cramer