<?php
//rename this file to form_intro.module, then place it into a directory with form_intro.info
//then you can use it like any other module

// $Id: $

/**
 * Implementation of hook_menu
 *
 * hook_menu documentation @ http://api.drupal.org/api/function/hook_menu/6
 *
 *"type": A bitmask of flags describing properties of the menu item. Many shortcut bitmasks are provided as constants in menu.inc:
 * MENU_NORMAL_ITEM: Normal menu items show up in the menu tree and can be moved/hidden by the administrator.
 * MENU_CALLBACK: Callbacks simply register a path so that the correct function is fired when the URL is accessed.
 * MENU_SUGGESTED_ITEM: Modules may "suggest" menu items that the administrator may enable.
 * MENU_LOCAL_TASK: Local tasks are rendered as tabs by default.
 * MENU_DEFAULT_LOCAL_TASK: Every set of local tasks should provide one "default" task, that links to the same path as its parent when clicked.
 * If the "type" key is omitted, MENU_NORMAL_ITEM is assumed. *
 *
 */

function form_intro_menu () {
  $items = array ();
  $items ['quiz'] = array (
    'title' => t('Super Cool Quiz'),
    'page callback' => 'quiz_page',
/**
 * note: very broad access rights, Probably should have been more granular,called hook_perm, 
 * to define a permission for   this module, and then use that permission.
 */
    'access arguments' => array('access content'),
    'type' => MENU_SUGGESTED_ITEM,    
  );

  //if you forget this-- the hook won't create the menu item
  return $items;
}

/**
 * page callback created in the Implementation of hook_menu
 *
 * drupal_get_form() documentation @ http://api.drupal.org/api/function/drupal_get_form/6
 *
 *
 */
function quiz_page () {
  return drupal_get_form('quiz_form');
}


/**
 * Creating the actual form itself happens here
 * Docs @
 * http://api.drupal.org/api/file/developer/topics/forms_api.html/6
 * http://api.drupal.org/api/file/developer/topics/forms_api_reference.html/6
 *
 */
function quiz_form ($form_state) {
  $form = array();
  
  //make a texfield
  $form['name'] = array (
    '#type' => 'textfield',
    '#title' => t('Please enter your name'),
    '#required' => TRUE,
  );
  
  //a pair of "radio buttons"
  $form ['toast'] =array (
    '#type' => 'radios',
    '#title' => t('Do you like toast?'),
    '#options' => array (t('No'), t('Yes')),
  );
  
  //a "submit" button
  $form['submit'] = array (
    '#type' => 'submit',
    '#value' => t('Make it so...'),  
  );
  
  // If you forget this line your form will never exist
  return $form;
}


/**
 * Validation function, only users who select "yes" are able to submit the form
 * 
 * Docs @
 * http://api.drupal.org/api/function/_form_validate/6
 *
 * form_set_error() Docs @
 * http://api.drupal.org/api/function/form_set_error/6
 *
 * php "if - else" information @
 * http://w3schools.com/php/php_if_else.asp
 *
 */
function quiz_form_validate ($form_id, &$form_state) {
  $toast = $form_state['values']['toast'];  
  if (!$toast) {
    form_set_error('toast', t('You must like toast to take this quiz.'));
  }
}

/**
 * form_submit function, once the form passes the validation (above) this runs
 * 
 * Docs @
 * http://api.drupal.org/api/file/developer/topics/forms_api.html/6
 * (under Submitting Forms)
 * 
 * drupal_set_message() Docs @
 * http://api.drupal.org/api/function/drupal_set_message/6
 *
 */
function quiz_form_submit ($form_id, &$form_state) {
  $name = $form_state['values']['name'];
  $toast = $form_state['values']['toast'];
  $output = t('Hi ');
  // check_plain() makes sure there's nothing nasty going on in the text written by the user.
  // http://api.drupal.org/api/function/check_plain
  $output .= check_plain($name);
  $output .= t(' the form was submitted successfully');

/**
 * Alternate (Better) way of doing that is below.
 * the @name is a palceholder that will call check_plain() on that string
 * Docs @ http://api.drupal.org/api/function/t
 */

  //$output = t('Hi @name the form was submitted successfully', array('@name' => $name));
  
  
  drupal_set_message($output);
}