Introduction to the Form API

Hi, this is Chris Shattuck with build a module dot com. And I'm going to talk a little bit about the Form API. So the Drupal Form API, API for those aren't familiar stands for Advanced Programming Interface.

And it basically exposes a set of functionality to Drupal developers. It allows them to create forms to do some really hard things with forms but very easily. So if you've had any experience building forms just a straight php or html, you've probably found that it's easy to do, it's easy to create a form.

I mean it's a bunch of html text, but as you build a form, there are implications as you start to develop and evolve the form. Like am I making this secure? How do I validate all of the information before it goes into the database? How do I process after I've gotten all of the information? If there are other aspects of the site that need to plug into that form, how do I expose those? The form api basically boils down a form into its basic elements. And all the form is is an array of values that set the different input.

So it looks a little foreign at first, especially if you're not familiar with arrays because arrays are the way that the form api works. But through the form api you get a lot. So the first thing it does is create a form from an array.

So just apply an array with just the base element. And then you can then theme the form using a form theme function. So this is a good separation of code versus presentation.

And as far as those who are familiar with what a model view controller framework is all about, this sort of falls into that category. And it allows developers to create a form and themers and designers to actually wrap that form. And make it look the way it needs to without influencing any of the validation or functionality or process and it goes along with the form, so that can be very handy.

The form api allows you validate the form before the information gets processed and then it allows you to process the information. Once it's past validation with submit functions. And then finally by using the form api instead of a vanilla form, you know php or html form, you allow other modules to plug into the form and change it with the hook form alter.

With the hook form alter, the entire form arrays passed to any modules who define this hook. And it allows them to do whatever they want with it so they can hide elements, add new elements, change the way certain elements are displayed. So it allows some of your module to be a jumping off point for other modules which can be really cool.

So as you're trying to learn the form api it's really hard to find good simple examples either in core modules or contributed modules. And that's because Drupal has done an awesome job of making all of the simple forms even simpler. In a previous video, we went over the settings form, the administrative settings form for a module.

That's really easy to make, but that would be one candidate where you would see a simple form example. The node form, any time you're working with content, all of those forms are already built in the Drupal. So when people end up having to create forms, therefore, usually advance purposes.

And we'll go over a few examples to kind of illustrate some different variations there. Let me show you a few resources before we go into the examples. So the first resource I want to point you to is the forms api reference page.

Now, as you work on forms and develop forms and start to have more questions, this page is going to be your bible. I go to this page almost every time I have to create a form. Well, it doesn't give you the step by step instructions.

What it does is tell you what attributes are available for what input and gives you lots of examples. So there's tons of information here and so your browser search functionality is going to come in real handy as you want to jump around because scanning this doesn't work so well. If you do you want the quickstart sort of, here's how do you build a simple form.

There's another good page on api dot drupal dot org called the Forms API Quickstart Guide. And this will take you through step by step just how to create a real simple form, how it's structured, how to theme it, how to validate and submit the form. So this is probably a really simple example but it's not necessarily a working one.

I mean, you can get it working but you can't see. Looking at contrib is kind of nice because you can see how those forms are being displayed right away. Also, I should have mentioned this resource in earlier videos.

But the pro drupal development book is a really awesome resource for learning, learning all of this stuff. If you like reading books, it will give you some good tips and good references to a lot of the stuff that I cover on the site. Not all but for instance the forms api, there's a whole section on that.

And if you get the pdf version, that's easily searchable and you can copy and paste and use that. Also, if you're curious about the model view controller framework thingy that I mentioned a little earlier. Just search on Google for drupal mvc and you can see what people talk about around that idea.

Okay. So let's take a look at some code. First, I want to look at the contributed module called voting api.

And the voting api is a cool little module that doesn't really do much physically. But it provides a background resource for other modules like 5 star, several updown dig type modules to track those, to associate, to limit number of votes per user, things like that. And it just so happens that they have one of the simplest forms I could find for generating some dummy votes.

So that if you want to kind of see instead of clicking a bunch of votes to populate your voting database, you can instead generate it. And this is associated with the Devel module. So the Devel module allows you to generate different types of content.

And this plugs into that in order to provide this generate votes functionality. So as you can see we're in the hook menu and there is an item here that says, if this module exist. So if the Devel generate module exist, then go ahead and add this page.

And we went over the module settings form in a previous video and that uses the drupal get form as a page call back as well. And so that's one way to generate a form on a page and it's only going to be the only thing on a page then this is one less step you have to do. So instead of creating a function to generate a page, you can instead call this, and it generates a page and renders the form at the same time.

So that's one less step for you. And then it's being passed, a string that the name of the form that's going to be generated. So that gets passed to the drupal get form function.

And so we want to look at in order to see how the form is constructed is this function. And as you can see there's a file defined for this menu item. So we're going to hop over to this file and take a look at the function.

Okay, here's the function. And I'm just going to scroll down so you can see how long this is. Not too long, just a little longer than a single page here.

Let's go ahead and walk this through step by step. So it starts out by generating an array of node types by using the node get types function. This is a really handy function if you've got a node or take this one down because you'll want it at some point.

Then it loops through each one and creates an array of key value pairs, an associative array which is putting into the options variable. And this options variable is then passed down here, as you can see to a form item. So if you watch the module settings to form a video, you'll know how these form elements are structured.

Basically the key for the array is the name of the input and then the array is a set of key value pairs that set a bunch of parameters for the form element. So in this case, the type corresponds to a type of input. So in this case it's checkboxes but there's also radio buttons, text inputs, text areas.

And the options that are being passed is an array of items that are going to be passed to the checkboxes, so this is one. If you ever try and creating this on your own, you can already see that there's a bunch of timing saved here. Because we're generating a list of checkboxes by just passing an array of options, so that's pretty cool.

Give a title which just helps the user understand what the node type is. The default value is being passed, an array of the keys for the options so thus, it makes all of the options checked by default. So the next input is a select type and the format is very similar to the checkboxes or the radios.

It gets past a list of value, key value pairs in the options. So as you can see the options here, we have a few, five, flag, updown for the different types of modules or the different types of voting. And then we have the default value which looks like it might be carry over from a previous version of the module since there is no percent option here.

The next input is a checkbox, just a simple checkbox and you can see there's this type, title and default value. It's unchecked by default. Then finally there's a submit button.

So when you do create a form, you need a submit button in order for someone to submit it. And then it returns a form. So this definition of a form doesn't actually render it all.

All it is a definition of an array. So you could easily create this array anywhere and then pass it to the drupal get form function. So this function doesn't have a validation function.

It just goes ahead and assumes that the input is going to be valid and then it submits it. And to create a submit function automatically, as you can see we do need to find any submit function in the form, although that is an option. But to do it by default, the drupal will look for the form name, the function name plus an underscore and submit.

And then we passed two variables, ...

Read the last half of the transcript