What the API is, why we think you'll like it, and how it makes ProcessWire a unique platform in the CMS landscape.
- Introduction to the API
- What makes up the API?
- How is the API similar to jQuery?
Introduction to the API
What is an API in a CMS?
API means application programming interface. In our context, it most commonly refers to the clearly defined interface (or tools) that the web developer uses to interact with content managed by the CMS. This interaction is most commonly used to produce output (like markup for the front-end of a site). In our case, the interactions can also be to manipulate content, create new content, and so on.
ProcessWire is entirely built around the API, and its admin panel is actually a website built using this API. ProcessWire was a headless CMS before there was a term for it. ProcessWire's easy-to-use API can do everything that you can do interactively in the admin, and more.
Why is the API so important?
The quality, consistency and simplicity of using that API, and how well it works in the context of the front-end output, either makes or breaks the development experience.
This is where ProcessWire's API comes into play. It focuses on making the development experience a joy while being simple, productive and powerful. It's about working the way you do, getting more done with less time, and having fun in the process.
What’s unique about ProcessWire’s API?
The ProcessWire API may already be comfortable and familiar for you, even if you've never used it before. To explain why it's both unique and familiar, lets first look at where it came from.
It wasn't long after discovering and learning jQuery that I started longing for a similar experience in a CMS. There were a lot of open source CMSs out there, and I tried them all, but nothing approached the powerful and simple joy of jQuery when it came to web development. I had already been developing custom CMS platforms for many years, and I thought it was time to pursue this project.
After more than a year of planning and development, the first open source version of ProcessWire was born. First came the design and planning of the API, then the CMS was built around it. Like jQuery, it's fun, fast, powerful, and a joy to use. It has also proven to be a secure platform for websites and applications, and every bit as sought after of a tool for clients as it is for developers. It's pure enjoyment in a CMS.
Now more than eight years since the original open souce release of ProcessWire, this original concept is still our foundation and guide.
What makes up the API?
ProcessWire’s API consists of a few different components:
The API consists of a few variables (via PHP objects) which are provided to your site's template files. These variables enable you to get or modify anything from your content, much in the same way that jQuery enables you to get and modify anything from the DOM.
The two most common API variables are $page and $pages. For some sites, this is all that you will ever use. The $page API variables represents the current page being viewed, and $pages represents all the other pages in your site. These can be thought of like the
$() object in jQuery.
ProcessWire's API variables provide access to all the components in ProcessWire, including all the site's pages, users, templates and fields. They provide a means of finding, getting, creating, modifying, saving and deleting these types of data.
You don't even need to build a site or application in ProcessWire in order to use the API. That's because the API can also be accessed by bootstrapping ProcessWire from another PHP script. More about API variables
Another major component of ProcessWire's API are selectors. Like in jQuery, selectors are simple strings of text that specify fields and values. For example, "name=ryan" is a simple selector that says: "find items that have the name ryan." These selectors are used throughout ProcessWire to get and find pages (and other types of data). ProcessWire selectors resemble jQuery selectors in many instances, but are also quite different. More about ProcessWire selectors
Most of the API objects in ProcessWire are chainable, using a fluent interface. This enables you to accomplish multiple operations on one line, for example:
echo $pages->get("/products/2010/") ->find("template=faq, body*=Tobiko") ->first() ->url;
Might print something like this:
Of course, you don't have to chain statements like that unless you want to.
Module Plugin Architecture
ProcessWire is built around a modular architecture. Modules exist to enable a high level of extensibility and customization to an installation of ProcessWire. Nearly every component and action in ProcessWire is hookable. Much of ProcessWire itself is a collection of plugin modules. More about Modules
How is the API similar to jQuery?
ProcessWire's API is inspired by jQuery and its style and syntax. You'll find a lot of similarities, and you'll also find some differences. The goal behind the ProcessWire API is to provide the level of accessibility and control to your site's pages that jQuery provides to the DOM.
DOM / Site Map
You interact with your site's structure via ProcessWire's API in a manner similar to working with the DOM in jQuery. The hierarchy of your site can be thought of like a DOM hierarchy, where every node (page) has a parent and every node may have children, and so on. Likewise, every node (page) can have its own attributes (fields). Depending on the type of node (template) the attributes (fields) will be different.
For the most part, ProcessWire's API attempts to use the same method naming conventions as jQuery. For example, you may use the find(), children(), siblings(), parent() and parents() methods on any page (aka node) and optionally supply a selector.
ProcessWire takes the idea of attribute selectors from jQuery and lets you apply that methodology to getting and finding pages in your site based on values in their attributes (aka fields). These selectors are a simplified version of what you find in jQuery, but the intention, experience and results are the same. For the most part, the operators used in a selector are the same as the operators used in jQuery selectors. More about Selectors
Like in jQuery, you can chain method calls in ProcessWire if you want to. This is what's called a fluent interface. Sometimes this is convenient and sometimes not, but the option is always there. For example, the following bit of code of grabs the first file from a field named images on the current
$page, resizes it to 200px width, and outputs the URL in an
<img src='<?=$page->images->first->width(200)->url?>' alt='Example'>
Like in jQuery, most traversing methods return values that can themselves be traversed and compared. For instance, a call to
$page->children(...) returns an array type that also has its own methods for find(), filter(), first(), has(), add(), filter() and so on.