Building a Simple Statamic Request Addon

In this tutorial we will look at building a really simple Statamic addon. The addon we will build will let us determine if the incoming web request to our site has a specific query parameter; this will allow us to have greater control in the way our site reacts to visitor's input. We will implement this addon as a tag so that we can take advantage of it from within our Statamic Antlers templates

#Generating the Scaffolding

In the root directory of your site, issue the following command to have Statamic generate the scaffolding we will need to build our custom tag:

1php please make:tags Request

This will generate a new file in the following location within your site's directory structure: site/addons/Request/RequestTags.php; this file will contain contents similar to the following example:

 1<?php
 2 
 3namespace Statamic\Addons\Request;
 4 
 5use Statamic\Extend\Tags;
 6 
 7class RequestTags extends Tags
 8{
 9    /**
10     * The {{ request }} tag
11     *
12     * @return string|array
13     */
14    public function index()
15    {
16        //
17    }
18 
19    /**
20     * The {{ request:example }} tag
21     *
22     * @return string|array
23     */
24    public function example()
25    {
26        //
27    }
28}

You can see that Statamic has generated a few sample methods to help get you started, but we will not be using them. We can remove all of the example methods so that the file becomes:

 1<?php
 2 
 3namespace Statamic\Addons\Request;
 4 
 5use Statamic\Extend\Tags;
 6 
 7class RequestTags extends Tags
 8{
 9 
10}

#Creating the Tag Method

Now that we have an empty tag addon class to work with, let's quickly recap what we want this addon tag to do: what we want to be able to do is determine if a URL query parameter exists. The first thing that I like to do is decide how the addon tag will be used within an Antlers template:

1{{ if {request:has input="q" } }}
2 
3    {{# Do something here. #}}
4 
5{{ /if }}

That looks pretty good; reading the tag name and parameter sounds natural. After this, let's add the method that will make the request:has part work:

 1<?php
 2 
 3namespace Statamic\Addons\Request;
 4 
 5use Statamic\Extend\Tags;
 6 
 7class RequestTags extends Tags
 8{
 9 
10    public function has()
11    {
12 
13    }
14 
15}

Great! We can now use the {{ request:has }} tag within our Antlers template, but we still need to be able to get the value of input into the tag's method body. Luckily, Statamic has made this really simple, you can read about it more in the official documentation Working with Input. However, the basics is that the Tags base class provides us a helper method getParam that we can use to retrieve user input:

 1<?php
 2 
 3namespace Statamic\Addons\Request;
 4 
 5use Statamic\Extend\Tags;
 6 
 7class RequestTags extends Tags
 8{
 9 
10    public function has()
11    {
12        $queryParameter = $this->getParam('input');
13    }
14 
15}

Now whatever argument we pass in for the input parameter will get stored in the $queryParameter variable within our tag's method body. The next thing that we want to do is actually determine whether or not the request contains whatever input was specified.

Since Statamic is built on top of the Laravel Framework, we can take advantage of some of its features here. Namely, we want to take advantage of Laravel's HTTP Requests features, we will do this by importing the Illuminate\Support\Facades\Input facade (still unsure of facades? You should check out the four part series on facades right here on the site; start with Laravel Facades Part One: An Introduction to Facades):

 1<?php
 2 
 3namespace Statamic\Addons\Request;
 4 
 5use Statamic\Extend\Tags;
 6use Illuminate\Support\Facades\Input;
 7 
 8class RequestTags extends Tags
 9{
10 
11    public function has()
12    {
13        $queryParameter = $this->getParam('input');
14    }
15 
16}

We have access to a has method through the `Input facade that can be used to determine if the current request has a given input parameter; this will make finishing our addon tag incredibly simple:

 1<?php
 2 
 3namespace Statamic\Addons\Request;
 4 
 5use Statamic\Extend\Tags;
 6use Illuminate\Support\Facades\Input;
 7 
 8class RequestTags extends Tags
 9{
10 
11    public function has()
12    {
13        $queryParameter = $this->getParam('input');
14 
15        return Input::has($queryParameter);
16    }
17 
18}

That's it! We've just built an addon that can be used to check if the request contains a given input item; it was really simple and pleasant with Statamic and Laravel. Rejoice!

#A Practical Use Case

So where would we use a tag like this? I personally like to use this on search pages to display a search form to the user if they navigate directly to the search results page without entering a search query (this technique has been implemented on this site here http://stillat.com/search).

Using our fancy new tag to accomplish this might look something like this:

1{{ if {request:has input="q"} }}
2 
3    {{# Display the search results. #}}
4 
5{{ else }}
6 
7    {{# Display a nice search form to the user. #}}
8 
9{{ /if }}

#The Finish Line

Congratulations you've just implemented a really simple Statamic addon tag that can be used to learn about request input. It would be trivial to expand this addon tag to learn more about the incoming request; this might be something for another article.

∎