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:

php 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:

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:

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:

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 it's 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):

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:

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. If you've enjoyed this post be sure to leave a comment below and share it with your friends and colleagues!

John Koster

Software developer, writer and Laravel enthusiast.

Join the mailing list to receive awesome blog posts, product updates and more