Please explain to me how Drupal's API works

March 4, 2013 12:27 PM

I'm trying to build a form in Drupal 7 using examples like this but all I've been able to figure out is that I make my own module and... then what? How does the module actually become a form? I feel like I'm missing some huge part of the concept here and Drupal's documentation is either too simple or too advanced. What am I not getting? Thanks MeFi!

What I'm hoping to accomplish in the end is a form with radio buttons, each next to an image.

posted by reductiondesign to computers & internet (8 answers total)

It would help a lot if you could tell us what needs to happen after you have that form. Does it email someone? Keep a tally of responses for a survey? Just look like a form with no real action happening?
posted by advicepig at 12:35 PM on March 4

Have you read the Basic Form tutorial from the docs? Do you see how in the module an admin menu item is created (along with the url my_module/form at which you can access the form ) and how a form is defined containing a textfield?
posted by Foci for Analysis at 12:39 PM on March 4

advicepig, the results will be tallied. Right now I'm more concerned with figuring out how to get the form set up in the first place. Once I do that, I can work on functionality.

Foci, I tried to follow those instructions and the two links provided—http://yoursite_site_url/?q=my_module/form and http://yoursite_site_url/my_module/form—didn't go anywhere on my own site. I just get a "Page not found" error.
posted by reductiondesign at 12:42 PM on March 4

When you have created your module and you login as admin, does it show up on the modules page? Is it enabled?
posted by juv3nal at 12:57 PM on March 4

juv3nal, yes and yes.
posted by reductiondesign at 1:00 PM on March 4

The Basic Form Tutorial that Foci for Analysis linked to looks sound. Couple of troubleshooting things to look at:

- If you copied the tutorial code directly, did you name your module accordingly? (You would need to create a 'my_module' directory containing 'my_module.module' 'my_module.info')

- If you adapted your existing module code to include a new implementation of hook_menu(), you'll need to clear the menu cache. (Admin > Performance > Clear all Caches) - whenever you add or change menu items in module code you'll need to do that.

- Also: Make sure your [modulename]_menu() function is actually returning an array. If I had a nickel for every time I'd carefully built out a big menu function but forgot to add the return statement at the end...
posted by usonian at 1:13 PM on March 4 [1 favorite]

Sideways answer: If you're just building the form to gather information (as opposed to publishing the individual submissions as content), then you will probably be better off just installing the Webform module. Do that, and you'll have your form built in no time (without writing a line of code).
posted by bricoleur at 5:07 PM on March 4 [2 favorites]

To answer your question, the function drupal_get_form() generates the HTML for the form. You give it the id (function name) of your form definition code (i.e mymodule_test_form) and it turns that into formatted HTML and returns the HTML to the function that called drupal_get_form.

So, you can define a page in the hook_menu function and tell Drupal you want that URL to go to a Form, or you can tell Drupal you want to just generate a static HTML page. Anywhere static HTML is being generated, you can actually insert the drupal_get_form and insert the generated HTML form into the page output.

So for instance, if in "mymodule_menu()", you define a page url (not a complete definition below):

$item['/newpage'] = array(
  'title' = t('My new page'),
  'page callback' => 'drupal_get_form',
  'page arguments' => array('mymodule_test_form'),
);

Tells Drupal to create a new url location at /newpage, call drupal_get_form to generate the HTML for the 'mymodule_test_form' that I defined.

If instead, I defined the menu item as:

$item['/newpage'] = array(
  'title' = t('My new page'),
  'page callback' => 'mymodule_test_page',
);

browsing to mysite.com/newpage just calls the mymodule_test_page() function to figure out what to do. In that function, I can choose to generate some HTML and return that to the browser (including my test_form HTML):

function mymodule_test_page() {
  $output = "Some HTML Text";
  $output .= drupal_get_form(mymodule_test_form);
  $output .= "Some closing text.";

  return $output;
}

And voila! You inserted your form into another separate HTML page. If you are wanting to insert a form into content that is programmatically generated by another module or by core, then that can be trickier.

Most people just do the first option, defining the form in the menu 'page callback', but since the actual HTML lifting is performed by drupal_get_form, you can do some cool things by playing with that function.
posted by insert.witticism.here at 6:59 PM on March 4