Overview
--------
Webform supports theming similar to the Flexinode or Views modules. Any webform
may be themed on the server side, though doing so may require a reasonable
amount of knowledge about the Drupal Forms API. More information about the Forms
API may be found at http://drupaldocs.org/api/head/file/contributions/docs/developer/topics/forms_api_reference.html

Theme submission emails
-----------------------
The default emails sent by webform are fairly basic. If you like, you may
customize the display of emails sent by each individual webform. This tutorial
assumes use of the phptemplate engine.

- Open your template.php file located in your theme's directory.
- Add the following lines of php code:

function phptemplate_webform_create_mailmessage_[node id here] ($form_data, $node) {
  return _phptemplate_callback('webform_create_mailmessage_[node id here]', array('form_data' => $form_data, 'node' => $node));
}

- Create a new file in your theme's directory named
  "webform_create_mailmessage_[node id here].tpl.php", once again replacing [node id here]
  with the node ID of the webform.
  
- Open up your new file and customize the webform email. Here's a simple template
  to get you started:
  
  <?php /* Begin sample create_mailmessage file */ ?>
  
  Company X Official Website Submission
  
  Message was submitted <?php echo format_date(time(), 'small') ?>
  
  From the IP address <?php echo $_SERVER['REMOTE_ADDR']; ?>
  
  The user's favorite color is <?php echo $form_data['submitted_tree']['favorite_color'] ?>
  
  The user's problem is below:
  <?php echo $form_data['submitted_tree']['problem'] ?>
  
  <?php /* End sample create_mailmessage file */ ?>

- To get a better idea of what variables are available to you, you can include
  the print_r function in your email. Simply include the line:
  
  <?php print_r($form_data) ?>
  
  to get a listing of all the available fields you can use in your mail.
  
- An Important Note for Webform Themers: When webforms added support for fieldsets
  (i.e. nested fields), it became necessary to increase the complexity of themed
  emails. Previously, the $form_data variable only sent the values of the form in
  a flat array. Now, $form_data contains several arrays of information:
  
  $form_data['submitted'] => An array of fields and their submitted values (identical to the previous value of $form_data)
  $form_data['submitted_tree'] => An array of fields and their values structured in a recursive array
  $form_data['components'] => An array of component_ids and their field names
  

Theme an entire webform
-----------------------

Theming a webform can be useful for rearranging elements or customizing the
appearance of multiple components at once. This tutorial assumes usage
of the phptemplate engine.

- Open your template.php file located in your theme's directory.
- Add the following lines of php code:

function phptemplate_webform_form_[node id here] ($form) {
  return _phptemplate_callback('webform_form_[node id here]', array('form' => $form));
}

- Replace "[node id here]" with the node ID of the form.

- Create a new file in your theme's directory named
  "webform_form_[node id here].tpl.php", once again replacing [node id here]
  with the node ID of the webform.
  
- Open up your new file and customize the webform however you like. Here's an
  example putting a field with the "email" key inside of another fieldset.
  
<?php
  // Create a new fieldset within the main fieldset
  // Note: All fields MUST stay within the 'submitted' fieldset
  $form['submitted']['newfieldset'] = array(
    '#type' => 'fieldset'
  );
  
  // Move the form field labeled "email" to the new fieldset
  $form['submitted']['newfieldset']['email'] = $form['submitted']['email'];
  unset($form['submitted']['email']);
  pring drupal_render($form);
?>

- All webform forms have 2 main fieldsets: "submitted", and "details". Although
  you may move things around as you wish, keep all your components within the
  "submitted" fieldset. Only the "submitted" fieldset is displayed and webform
  depends on the other two to operate properly, so don't mess with them unless
  you have good reason to do so (like you're forwarding your webform to a custom
  PHP or PERL script).


$Id: THEMING.txt,v 1.8.2.4 2008-01-19 01:50:50 quicksketch Exp $