To create dynamic websites and exciting new content types in our modules

we need to provide forms so our users can supply information.

Which Drupal in turn can use in a number of different ways.

For example, you might want to create a custom form

if you were running an events calendar website.

You might want to get a lot of information from a user about their event.

Is it a corporate meeting, or a wedding?

How many guests do they expect?

Do they want your event space for the whole day, or by the hour?

If they need it by the hour then when does it start and end?

Did they need to use the in house catering?

These would all be custom form fields.

But let's start simple.

We're going to make a module that just takes two numbers,

chosen by a user, and displays their sum.

If we can do that, then we can expand on it as much as we like.

To add a custom form to a Drupal module, you need to follow four steps.

1 Use hook_menu to create a menu link which will take us to

a page which displays our form.

2 Use its page callback function to construct the form.

3 Use hook_form_submit to get

the data out of the form after it has been successfully submitted, and process it.

And 4 Display any results or output from the form.

Let's start by creating our files.

Since our module adds two numbers, let's name it sum.

First, create a folder named sum inside of your Sites/all/modules directory.

Then, we're going to need two blank text files,

named sum.info, and sum.module.

sum.info.

Remember to change to the right

folder, and sum.module.

Now, the .info file for

this module is pretty much like the other .info files that we've created so far.

It just needs a name for the module, which is going to be Sum.

A description which is going to be that it displays the sum

of two numbers using a form for input.

Then it needs a package.

We'll put it with the other modules.

My First Modules.

The version of Drupal Core, which is still 7.

7.x.

And finally, the name of the corresponding sum.module file that we have made.

There, save that.

The .module file starts out the same way.

We need our opening php tag, and then we need to

implement hook_menu, by declaring a function,

whose name starts with the name of our module,

sum, and then we add _menu, to the end.

We need our parentheses and curly brackets.

And then inside of hook_menu, we create the items array.

And then we need to add one key-value pair to it.

Its key is the URL sum.

Which means that localhost:8888/sum will take us to our form.

We'll set that equal to another array for all of our attributes for the menu item.

The first one being title.

Let's give the form page the title, how about Calculate Sum.

Don't forget the comma after it.

And then we'll assign its type attribute to be

MENU_NORMAL ITEM, so that it shows up in the navigation menu.

We can also set the access callback to be equal to true,

because we want anyone to be able to access the form.

All familiar so far.

We'll set the page callback function to something different.

An existing Drupal function which is called

drupal_get_form.

We also need to use a new attribute called page arguments.

This is set to an array of arguments to pass into the page callback function.

So we'll make an array and we only need one

argument in it, the string sum_form.

In other words, this code so far tells Drupal that when the sum URL is visited,

run the function drupal_get_form with the argument sum_form.

The string sum_form is the name of the function

that Drupal will call to build your form.

So when drupal_get_form runs, it, in turn, runs sum_form.

Let's write that function next.

Function sum_form pair of parentheses pair of curly brackets.

Okay.

It needs to return an array of information about the form we want Drupal to build.

This works similarly to hook_menu, which needs to return an array of URLs

with information about each one stored as a key value pair.

Each key value pair in the form array creates an input field.

First let's make our array and we'll call it form.

Start it off blank, again.

And I'm gonna give myself some room and then, so

I don't forget, I'm gonna go ahead and return the form at the end.

Each key value pair in the form array, creates an input field.

We tell Drupal that we want two fields in our form which we will refer to as

left_number and right_number.

Form left_number and

form right_number.

The strings left number and

right number become the name attribute of the form field in the generated HTML.

We will later use this name to get the user's data out of this form field.

Stored at each key, left number, and

right number, is an array of attributes for the form field.

Array.

And again over here.

Unlike menu item attributes, these must be prefixed

with a hash symbol inside the quotes as in, #title.

The title field is displayed above the field.

It fills in the text on the HTML label tag, let's call this one

the slightly more readable Left Number.

And then we'll set the type

attribute equal to textfield.

This defines what kind of input we need from the user.

Such as integers, decimals, or text, in this case.

It maps to the type HTML attribute on the input tag.

The we have the description.

Let's set that equal to,

please enter your starting number.

The description should provide instructions to the user.

This will be a div right below the input field.

Let's add these to our other number as well.

And rename title to match as Right Number, it should still be a text field.

And this description can say something different like,

please enter a number to add to the starting number.

Number.

Okay.

Then we need to create a submit button as well.

We will also do this inside of our giant form array.

Form, submit.

And it is also equal to an array, though a slightly smaller one.

Because it needs less information.

First, it, again, needs the type attribute.

And it is set to submit so

that the hooks for submitting a form are called when it is clicked.

And then the value attribute should be set to,

say, something along the lines of Calculate Sum.

This is the text that is actually printed on the button.

And finally, we return our form array.

Let's try this out.

Enable the new module by going to the modules administration page.

Per our .info file, it should be called Sum, under my first modules.

Here it is.

I'll enable it and click Save configuration.

Now let's click back Home and

we should have a menu item in our Navigation menu, but we don't.

Something's gone wrong.

First of all, we should try clearing our cache and see if that fixes anything.

I'll click on Performance, Clear all caches.

And then we'll go back to the modules page.

Un-enable our sum module, save it, and re-enable it,

saving again, just to see if that fixes it.

We'll click back home and it's still not there.

Okay, so something is wrong with our code.

Let's take a look at it again.

Since the menu item isn't showing up,

I can be pretty sure that it's something wrong with the sum_menu function here.

We have our items array.

We've given it a title, a type, and

we've set up the access callback, page callback and page arguments.

There aren't any syntax errors because otherwise we would've

gotten a blank screen or

the save would have failed when we clicked it on the module administration page.

So, it must be something else.

And here,

we see that it is the fact that Drupal is not getting our items array back.

We need to remember to return it at the end of the function.

A very common mistake to make.

All right, now let’s try it again.

I’ll go back, and clear the cache,

configuration, performance, clear all caches.

Then I'll go back to the modules page,

un-enable the Sum module, save it and then re-enable it.

Incidentally, this is not always necessary.

It's just for safety's sake since I'm showing this to you guys.

Now let's save it again, and hopefully our problem will be fixed.

Back home, and there it is.

Calculate Sum.

And we can see our form if we click on it.

It's got two text fields Left Number and Right Number, and

a submit button labeled Calculate Sum.

Nothing will happen if you click on it but now we know that the module creates a form

that appears when the user clicks on the link.

In our next video we'll learn how to send the form and how to use the data.