Using Custom Publish Forms with Statamic

This is going to be a big one, so buckle up. I’ll probably break this down into a couple of posts because this is easily one of the most complicated parts of Statamic, and will require some context to understand.

Before we start, I should stress, you will need a strong understanding of Laravel, Statamic, AND object orientated PHP if you want to work with custom publish forms.

What are custom publish forms?

When you add or edit content on a website, you are do so through a form. In Statamic, this form is called a publish form. Up until version 2.8, it wasn’t possible to create your own; at least, not out of the box.

Normally, this form is generated by Statamic and pulls data from somewhere within Statamic. It then allows you manipulate the data, before saving it.

That’s pretty much what the publish form does. It you want to find out more about it, there’s a pretty good article in the offical docs that goes into far more detail than is needed here.

Why did I need to use a custom publish form?

When the gents designed the system, they envisioned people wanting to hook in data from external sources; maybe an API, or even a database.

However, my use case is slightly different. At the time of writing, at my day job we’re separating the investors information from our corporate site and moving it to a subdomain. Within that, there’s a set of content – our RNS announcements – that were causing a bit of a headache.

Because of their regulatory nature (RNS standing for regulatory news service), the titles of the announcements often repeat. Because Statamic is a flat-file system, the unique identifier is the slug, rather than an ID, as in a relational database. When we tried to publish an entry in a collection with the same name, Statamic threw and hissyfit and told us there was a duplicate slug. This was a problem. A big problem.

After spending some time trying to find a way of hooking into an event to amend the slug before it was created (long story short, the earliest event isn’t early enough), I decided on going down the custom publish form path.

Getting it working

Now a word of caution. Statamic’s custom publish form functionality is extremely tough to get your head around at first. It requires understanding a lot of different moving parts; some of which you’ll likely never dealt with before. Don’t get disheartened if at first, it doesn’t click. It took me a couple of attempts over 6 months for it to finally make sense.

Originally, I had thought about trying to replicate the use of the file system, but quickly realised it would make what was already a complicated, thing even more complicated. So I opted to base it on one of the examples Jason had created.

Using an Eloquent model

Since I didn’t want to spent time setting up an API to feed information into the site, I opted to use the database-based method of creating a custom publish form in an addon.

After banging my head against a wall trying to replicate the functionality, Erin Dalzell suggested just getting Jason’s example working first and then tweaking bit-by-bit; breaking it and then fixing it. I know that sounds like an obvious approach, but I’m so ingrained in the writing-it-out-makes-it-go-in-quicker approach, it competely passed me by as a valid way of doing it.

After downloading the demo and getting it working, I built one in parallel, copying method-by-method; getting it working and then fixing it. After a couple of hours, I had a working custom publish form.

Adding limiting, pagination, and scoping

Unfortunately, it quickly became apparent that while the example got it working, there were limitations. Currently, we have around 160 announcements, with at least 6 being added per month. Around results times, that number can triple.

That meant that pagination wasn’t an option; it was a necessity. Unfortunately, out of the box, the example doesn’t have any provisions for pagination. Thankfully, the underlying logic that would allow us to use pagination in the custom publish form is the same as that found in Statamic’s collection functionality.

Mine and Erin’s secret; reading the source code

When people ask for help on the Statamic discord, the answer can often be found in the documentation. However, in those rare circumstances that there isn’t any documentation, both Erin, I, and the other developers who often help out others turn to the best documentation available – the source code.

Rather than explain how to read this, I’ll link to a video tomorrow, I recorded showing me working through the source code for the CollectionsTag.