Bummer! This is just a preview. You need to be signed in with a Basic account to view the entire video.
Start a free Basic trial
to watch this video
Gather information from a user by creating a module to construct a custom form.
To add a custom form to a Drupal module, you need to follow these steps:
- Use
hook_menu
to create a menu link which will take us to a page which displays our form. - Use the built in Drupal function
drupal_get_form
as the page callback function. - Use the
page arguments
attribute to pass in the name of the function which will construct the form, which ishook_form
. - Use
hook_form_submit
to get the data out of the form after it has been successfully submitted, and process it. - Display any results or output from the form.
Why?
The function that actually does the work of constructing the form is sum_form
(built from hook_form
by substituting the name of the module sum
for the word hook
).
In order for this function to work, it must be called using drupal_get_form
, and the naming is important. Since it's a hook, you have to name it sum_form
.
-
0:00
To create dynamic websites and exciting new content types in our modules
-
0:05
we need to provide forms so our users can supply information.
-
0:10
Which Drupal in turn can use in a number of different ways.
-
0:14
For example, you might want to create a custom form
-
0:17
if you were running an events calendar website.
-
0:20
You might want to get a lot of information from a user about their event.
-
0:24
Is it a corporate meeting, or a wedding?
-
0:27
How many guests do they expect?
-
0:29
Do they want your event space for the whole day, or by the hour?
-
0:33
If they need it by the hour then when does it start and end?
-
0:37
Did they need to use the in house catering?
-
0:39
These would all be custom form fields.
-
0:43
But let's start simple.
-
0:45
We're going to make a module that just takes two numbers,
-
0:48
chosen by a user, and displays their sum.
-
0:52
If we can do that, then we can expand on it as much as we like.
-
0:57
To add a custom form to a Drupal module, you need to follow four steps.
-
1:03
1 Use hook_menu to create a menu link which will take us to
-
1:07
a page which displays our form.
-
1:10
2 Use its page callback function to construct the form.
-
1:15
3 Use hook_form_submit to get
-
1:20
the data out of the form after it has been successfully submitted, and process it.
-
1:26
And 4 Display any results or output from the form.
-
1:31
Let's start by creating our files.
-
1:33
Since our module adds two numbers, let's name it sum.
-
1:38
First, create a folder named sum inside of your Sites/all/modules directory.
-
1:47
Then, we're going to need two blank text files,
-
1:52
named sum.info, and sum.module.
-
1:56
sum.info.
-
1:58
Remember to change to the right
-
2:03
folder, and sum.module.
-
2:11
Now, the .info file for
-
2:13
this module is pretty much like the other .info files that we've created so far.
-
2:18
It just needs a name for the module, which is going to be Sum.
-
2:24
A description which is going to be that it displays the sum
-
2:31
of two numbers using a form for input.
-
2:37
Then it needs a package.
-
2:40
We'll put it with the other modules.
-
2:42
My First Modules.
-
2:46
The version of Drupal Core, which is still 7.
-
2:49
7.x.
-
2:52
And finally, the name of the corresponding sum.module file that we have made.
-
2:59
There, save that.
-
3:02
The .module file starts out the same way.
-
3:05
We need our opening php tag, and then we need to
-
3:10
implement hook_menu, by declaring a function,
-
3:15
whose name starts with the name of our module,
-
3:19
sum, and then we add _menu, to the end.
-
3:26
We need our parentheses and curly brackets.
-
3:29
And then inside of hook_menu, we create the items array.
-
3:36
And then we need to add one key-value pair to it.
-
3:42
Its key is the URL sum.
-
3:46
Which means that localhost:8888/sum will take us to our form.
-
3:54
We'll set that equal to another array for all of our attributes for the menu item.
-
4:01
The first one being title.
-
4:04
Let's give the form page the title, how about Calculate Sum.
-
4:13
Don't forget the comma after it.
-
4:16
And then we'll assign its type attribute to be
-
4:20
MENU_NORMAL ITEM, so that it shows up in the navigation menu.
-
4:29
We can also set the access callback to be equal to true,
-
4:38
because we want anyone to be able to access the form.
-
4:41
All familiar so far.
-
4:44
We'll set the page callback function to something different.
-
4:49
An existing Drupal function which is called
-
4:52
drupal_get_form.
-
5:01
We also need to use a new attribute called page arguments.
-
5:11
This is set to an array of arguments to pass into the page callback function.
-
5:19
So we'll make an array and we only need one
-
5:24
argument in it, the string sum_form.
-
5:29
In other words, this code so far tells Drupal that when the sum URL is visited,
-
5:36
run the function drupal_get_form with the argument sum_form.
-
5:42
The string sum_form is the name of the function
-
5:47
that Drupal will call to build your form.
-
5:50
So when drupal_get_form runs, it, in turn, runs sum_form.
-
5:57
Let's write that function next.
-
6:00
Function sum_form pair of parentheses pair of curly brackets.
-
6:10
Okay.
-
6:10
It needs to return an array of information about the form we want Drupal to build.
-
6:16
This works similarly to hook_menu, which needs to return an array of URLs
-
6:21
with information about each one stored as a key value pair.
-
6:26
Each key value pair in the form array creates an input field.
-
6:31
First let's make our array and we'll call it form.
-
6:36
Start it off blank, again.
-
6:38
And I'm gonna give myself some room and then, so
-
6:41
I don't forget, I'm gonna go ahead and return the form at the end.
-
6:46
Each key value pair in the form array, creates an input field.
-
6:51
We tell Drupal that we want two fields in our form which we will refer to as
-
6:56
left_number and right_number.
-
6:58
Form left_number and
-
7:03
form right_number.
-
7:10
The strings left number and
-
7:12
right number become the name attribute of the form field in the generated HTML.
-
7:18
We will later use this name to get the user's data out of this form field.
-
7:24
Stored at each key, left number, and
-
7:26
right number, is an array of attributes for the form field.
-
7:32
Array.
-
7:37
And again over here.
-
7:43
Unlike menu item attributes, these must be prefixed
-
7:48
with a hash symbol inside the quotes as in, #title.
-
7:56
The title field is displayed above the field.
-
8:00
It fills in the text on the HTML label tag, let's call this one
-
8:06
the slightly more readable Left Number.
-
8:14
And then we'll set the type
-
8:19
attribute equal to textfield.
-
8:26
This defines what kind of input we need from the user.
-
8:29
Such as integers, decimals, or text, in this case.
-
8:33
It maps to the type HTML attribute on the input tag.
-
8:38
The we have the description.
-
8:43
Let's set that equal to,
-
8:47
please enter your starting number.
-
8:54
The description should provide instructions to the user.
-
8:57
This will be a div right below the input field.
-
9:00
Let's add these to our other number as well.
-
9:06
And rename title to match as Right Number, it should still be a text field.
-
9:13
And this description can say something different like,
-
9:19
please enter a number to add to the starting number.
-
9:23
Number.
-
9:26
Okay.
-
9:27
Then we need to create a submit button as well.
-
9:33
We will also do this inside of our giant form array.
-
9:37
Form, submit.
-
9:41
And it is also equal to an array, though a slightly smaller one.
-
9:45
Because it needs less information.
-
9:48
First, it, again, needs the type attribute.
-
9:54
And it is set to submit so
-
9:58
that the hooks for submitting a form are called when it is clicked.
-
10:03
And then the value attribute should be set to,
-
10:10
say, something along the lines of Calculate Sum.
-
10:16
This is the text that is actually printed on the button.
-
10:20
And finally, we return our form array.
-
10:24
Let's try this out.
-
10:25
Enable the new module by going to the modules administration page.
-
10:30
Per our .info file, it should be called Sum, under my first modules.
-
10:36
Here it is.
-
10:37
I'll enable it and click Save configuration.
-
10:41
Now let's click back Home and
-
10:44
we should have a menu item in our Navigation menu, but we don't.
-
10:48
Something's gone wrong.
-
10:51
First of all, we should try clearing our cache and see if that fixes anything.
-
10:56
I'll click on Performance, Clear all caches.
-
11:00
And then we'll go back to the modules page.
-
11:04
Un-enable our sum module, save it, and re-enable it,
-
11:11
saving again, just to see if that fixes it.
-
11:16
We'll click back home and it's still not there.
-
11:20
Okay, so something is wrong with our code.
-
11:23
Let's take a look at it again.
-
11:26
Since the menu item isn't showing up,
-
11:29
I can be pretty sure that it's something wrong with the sum_menu function here.
-
11:34
We have our items array.
-
11:36
We've given it a title, a type, and
-
11:39
we've set up the access callback, page callback and page arguments.
-
11:45
There aren't any syntax errors because otherwise we would've
-
11:48
gotten a blank screen or
-
11:49
the save would have failed when we clicked it on the module administration page.
-
11:54
So, it must be something else.
-
11:56
And here,
-
11:57
we see that it is the fact that Drupal is not getting our items array back.
-
12:03
We need to remember to return it at the end of the function.
-
12:08
A very common mistake to make.
-
12:11
All right, now let’s try it again.
-
12:13
I’ll go back, and clear the cache,
-
12:17
configuration, performance, clear all caches.
-
12:23
Then I'll go back to the modules page,
-
12:28
un-enable the Sum module, save it and then re-enable it.
-
12:36
Incidentally, this is not always necessary.
-
12:38
It's just for safety's sake since I'm showing this to you guys.
-
12:43
Now let's save it again, and hopefully our problem will be fixed.
-
12:48
Back home, and there it is.
-
12:50
Calculate Sum.
-
12:53
And we can see our form if we click on it.
-
12:56
It's got two text fields Left Number and Right Number, and
-
13:00
a submit button labeled Calculate Sum.
-
13:03
Nothing will happen if you click on it but now we know that the module creates a form
-
13:08
that appears when the user clicks on the link.
-
13:12
In our next video we'll learn how to send the form and how to use the data.
You need to sign up for Treehouse in order to download course files.
Sign up