My battle with drupal's form In the ancient times when things were easy, you just had to code a form in html and then your php would typically have a if($_REQUEST['some_value']) to handle the request. But now with Drupal, nothing is easy... Here is once more my latest battle to understand how Drupal thinks.

Context: I have a list of news (content type "news") shown on a page with paging system. Each news title links to the news details page. This works fine. There is a new requirement that each news must have one or more "tags". The goal is to show a list of checkboxes on top of the news list to allow the user to filter in/out news with the selected tags.

EDIT: After being defeated by Drupal's form I decided to completely bypass the Form API and generate my own fully flexible form.

There is only one thing remaining, Drupal is forcing some div wrappers around each of my input fields. I want to get rid of them (and stop Drupal to think at my place).

In my_news_list.tpl.php I coded:

&lt;form action="" method="post"&gt; &lt;!-- recall same page on submit --&gt;
&lt;?php
foreach($tags as $tag){
    ?&gt;&lt;input type="checkbox" name="tags[]" 
        value="&lt;?php echo $tag['id'] ?&gt;"
        onchange="form.submit();" 
        &lt;?php if(isset($tag['checked'])){?&gt;checked="checked"&lt;?php }?&gt; 
      /&gt;&lt;?php echo $tag['value'] ?&gt;&lt;?php
}
?&gt;
&lt;/form&gt;


Result(!):

&lt;form action="" method="post"&gt;
    &lt;div class=" ui-checkbox"&gt; &lt;!-- Why those div wrappers?! --&gt;
        &lt;input type="checkbox" name="tags[]" value="15" onchange="form.submit();"&gt;
    &lt;/div&gt;
    Acquisitions
    &lt;div class=" ui-checkbox"&gt;
        &lt;input type="checkbox" name="tags[]" value="14" onchange="form.submit();"&gt;
    &lt;/div&gt;
    Corporate
    &lt;div class=" ui-checkbox"&gt;
        &lt;input type="checkbox" name="tags[]" value="18" onchange="form.submit();"&gt;
    &lt;/div&gt;
    Investor News
    &lt;div class=" ui-checkbox"&gt;
        &lt;input type="checkbox" name="tags[]" value="16" onchange="form.submit();"&gt;
    &lt;/div&gt;
    Products and Services   
&lt;/form&gt;
Drupal's Form API is complex but gives you lot of things: is secure, is extensible, is themeable. Indeed is more difficult than coding a simple HTML form, but with a simpel HTML form you have a simple functionality: just that simple HTML form.

Form API generates the form HTML element and handles the POST requests, and validate and submithandlers, you don't and you shouldn't code your own HTML form. 

I recommend you to read the Drupal 6 Form API Quickstart Guide. Drupal 7 form handling is pretty the same, but check the Drupal 7 Form API Reference and Form API Internal Workflow Illustration.

In the other hand you may prefer to use a module that address what you need without coding, that's a faceted search: Facet API. From its documentation page:


  Faceted search allows our search results to be filtered by defined
  criteria like category, date, author, location, or anything else that
  can come out of a field. We call these criteria facets. With facets,
  you can narrow down your search more and more until you get to the
  desired results.