By default, Runway serves your headless views from
/api. This routes to the
perch/templates/api folder, where you create a PHP file for any headless view you wish to make available.
Create a new PHP file as
perch/templates/api/news.php. This will be a headless view that we’ll configure to access a collection called News. (The file name is not significant, just convenient.)
Once complete, we’ll be able to access our new headless view at the URL:
In this file, open some
<?php tags and create a new instance of the Headless API.
<?php $Headless = $API->get('HeadlessAPI');
Creating a headless view is all about building up the response. We find all the content we want to include, add it to the response, and then at the very end we call
respond() and the result is sent to the client.
So to get started, create a new response:
$Response = $Headless->new_response();
Sourcing the content
For this example, we’re going to query some items from the News collection. To do that, we need to get an instance of
ContentCollections and find our collection by name.
$Collections = $API->get('ContentCollections'); $Collection = $Collections->find('News');
We now have an instance of the News collection quick we can query for content. More on that in a moment.
Each response is made up of one or more content sets. In a simple view like this one, there might just be one set containing our news items. On a more complex view, there could be multiple. For example, a blog post view might have a set containing the post, one containing the comments, and another containing related posts.
It’s the ability to put multiple sets into a response that give the opportunity to build views that contain all the content you need for fetching with a single HTTP request. Of course, you don’t have to put multiple sets into a response, but the fact that you can offers lots of flexibility.
When you create a set, you give it a name to identify it in the response. We’ll call this one
$Set = $Headless->new_set('news');
We then need to call the
add_items() method on the set to pass in our content. We could do something like this:
$Set->add_items([ [ 'id' => 1, 'title' => 'Hello', ], [ 'id' => 2, 'title' => 'World', ], ]);
More realisically, that content needs to come form the CMS somewhere. It’s here that we’re going to query the News collection to get our items. To do that, we use the
query() method, and pass it the same options we’d use for
$Set->add_items($Collection->query([ 'sort' => 'date', 'sort-order' => 'DESC', ]));
Now that the set has items, we can add it to the response.
Sending the response
We’re all done, so send the response to the client:
perch/templates/api/news.php view in full:
<?php $Headless = $API->get('HeadlessAPI'); $Response = $Headless->new_response(); $Collections = $API->get('ContentCollections'); $Collection = $Collections->find('News'); $Set = $Headless->new_set('news'); $Set->add_items($Collection->query([ 'sort' => 'date', 'sort-order' => 'DESC', ])); $Response->add_set($Set); $Response->respond();