Drupal example source code file (summaries.inc)

This example Drupal source code file (summaries.inc) is included in the DevDaily.com "Drupal Source Code Warehouse" project. The intent of this project is to help you "Learn Drupal by Example".

PHP - Drupal tags/keywords

array, callback, default_value, false, form, function, if, key, output, php, result, return, summary, title

The summaries.inc Drupal example source code

<?php
// $Id: summaries.inc,v 1.1.2.12 2010/07/12 22:51:30 tr Exp $

/**
 * @file
 * Provides summaries of forms and fieldsets to give "at-a-glance" settings
 * information.
 */

/**
 * Summarizes the elements in a form array, recursively building summaries of
 * items nested in fieldsets if applicable.
 *
 * @param $form
 *   The form array to summarize.
 * @return
 *   An array of summary information, structured for theme_item_list().
 */
function summarize_form($form) {
  $items = array();

  // Loop through each element in $form.
  foreach (element_children($form) as $key) {
    // Set the callback for the summary to the default if not specified.
    if (!isset($form[$key]['#summary callback'])) {
      // Default filter forms to have no summary.
      if (in_array('filter_form_validate', (array) $form[$key]['#element_validate'])) {
        $form[$key]['#summary callback'] = 'summarize_null';
      }
      else {
        $form[$key]['#summary callback'] = 'summarize_element';
      }
    }

    // Setup the arguments array, always passing in the form array.
    $args = array($form[$key]);

    // Append the arguments specified by the element.
    if (isset($form[$key]['#summary arguments'])) {
      $args = array_merge($args, $form[$key]['#summary arguments']);
    }

    // Fetch the result from the summary callback.
    $result = call_user_func_array($form[$key]['#summary callback'], $args);

    // Check the type of the result...
    if (is_array($result)) {
      // Arrays get merged in so summaries can include multiple items.
      $items = array_merge($items, $result);
    }
    elseif (!empty($result)) {
      // Otherwise add a non-empty result to the array as a new value.
      $items[] = $result;
    }
  }

  return $items;
}

/**
 * Summarize an individual element using its specified #summary if possible.
 *
 * @param $form
 *   The element's array in the form array.
 * @param $title
 *   TRUE or FALSE indicating whether or not to include the element's #title in
 *     the summary text.
 * @return
 *   A summary string for the element or a summary array for a fieldset.
 */
function summarize_element($form, $title = FALSE) {
  // Check to see if the form array contained a #summary.
  if (isset($form['#summary'])) {
    // If so, decide whether to display it with or without the element's #title.
    if ($title) {
      return t('!title: !summary', array('!title' => $form['#title'], '!summary' => $form['#summary']));
    }
    else {
      return $form['#summary'];
    }
  }
  else {
    // Otherwise, use a sensible default based on the field type.
    switch ($form['#type']) {
      case 'fieldset':
        return array(
          array(
            'data' => $form['#title'] .':',
            'children' => summarize_form($form),
          ),
        );

      case 'textfield':
        return $form['#title'] .': '. check_plain($form['#default_value']);

      case 'select':
        if (!empty($form['#multiple']) and is_array($form['#default_value'])) {
          $options = array();
          foreach ($form['#default_value'] as $value) {
            if (isset($form['#options'][$value])) {
              $options[] = $form['#options'][$value];
            }
          }
          // Return an item list of the selected options.
          return array(array(
            'data' => $form['#title'].':',
            'children' => $options,
          ));
        }
        // Else, fall through.
      case 'radios':
        return $form['#title'] .': '. $form['#options'][$form['#default_value']];

      case 'checkbox':
        if ($form['#default_value']) {
          return $form['#title'];
        }
        else {
          return;
        }
    }

    // If we didn't have a default action, check for a callback.
    $callback = 'summarize_'. $form['#type'];

    if (function_exists($callback)) {
      return $callback($form);
    }
  }
}

/**
 * Return an empty summary string.
 */
function summarize_null($form) {
  return array();
}

/**
 * Return the correct summary string for a checkbox element based on its
 *   current value.
 *
 * @param $true
 *   The summary string to use if the checkbox has been checked.
 * @param $false
 *   The summary string to use if the checkbox has not been checked.
 * @return
 *   The correct supplied string based on the current value of the checkbox.
 */
function summarize_checkbox($form, $true, $false) {
  if ($form['#default_value']) {
    return $true;
  }
  else {
    return $false;
  }
}

/**
 * Summarize the form pages that are children of the specified path.
 *
 * @param $path
 *   The menu path to start from when checking for children forms.
 * @param $trim
 *   When set to TRUE, summary data will only be included in the return array
 *   when the summary actually has items.
 * @param $only_parent
 *   When set to TRUE, forms will only be included from the given $path,
 *   no recursion will be done
 * @return
 *   An array of data representing a form page summary including keys for the
 *   page's 'path', and edit 'href', a summary 'title' and 'items'.
 */
function summarize_child_form_pages($path, $trim = FALSE, $only_parent = FALSE) {
  $summaries = array();

  // Fetch and loop through any child menu items from the database.
  $accessor = "LIKE '%s/%%'";

  // If no_recur is TRUE, only look for the parent
  if ($only_parent) {
    $accessor = "= '%s'";
  }

  $result = db_query("SELECT path FROM {menu_router} WHERE path ". $accessor ." ORDER BY weight", $path);

  while ($row = db_fetch_array($result)) {
    $item = menu_get_item($row['path']);
    // Only allow items the user can access.
    if ($item['access'] === FALSE) {
      continue;
    }

    if ($item['page_callback'] == 'drupal_get_form') {
      if ($item['type'] == MENU_DEFAULT_LOCAL_TASK) {
        $parent = menu_get_item($item['tab_parent']);
        $href = $parent['href'];
      }
      else {
        $href = $item['href'];
      }

      $form_id = $item['page_arguments'][0];

      if (!function_exists($form_id)) {
        require_once($item['file']);
      }

      $form_state = array('storage' => NULL, 'submitted' => FALSE);
      $form = drupal_retrieve_form($form_id, $form_state);
      drupal_prepare_form($form_id, $form, $form_state);

      $summary_items = summarize_form($form);

      if (!$trim || $trim && count($summary_items) > 0) {
        $summaries[] = array(
          'path' => url($item['path']),
          'href' => $href,
          'title' => $item['title'],
          'items' => $summary_items,
        );
      }
    }
  }

  return $summaries;
}

/**
 * Theme a summaries array into a handy div for use with some JS enhancement.
 *
 * @param $summaries
 *   An array of summary arrays each containing the following keys:
 *   - path - the path of the settings form the array is summarizing.
 *   - title - the title of the settings form.
 *   - href - the actual URL of the summary's form page.
 *   - items - an array of items formatted for theme_item_list().
 * @param $link
 *   TRUE or FALSE indicating whether or not to display an edit icon linking to
 *     the settings form the summary represents.
 * @return
 *   The HTML output of the summary.
 * @ingroup themeable
 */
function theme_summary_overview($summaries, $link = TRUE) {
  // Add some Ubercart specific JS for modifying summaries.
  drupal_add_js(drupal_get_path('module', 'uc_store') .'/includes/summaries.js');
  drupal_add_js(array('editIconPath' => base_path() . drupal_get_path('module', 'uc_store') .'/images/order_edit.gif'), 'setting');

  $output = '';

  foreach ($summaries as $summary) {
    // Add a containing div for the summary overview.
    $output .= '<div id="'. $summary['path'] .'" class="summary-overview">';

    // Add a div for the header containing the title and edit link.
    $output .= '<div class="summary-header"><span class="summary-title">'
             . check_plain($summary['title']) .': </span>';

    if ($link) {
      $output .= ' <span class="summary-link">'. l(t('edit'), $summary['href'])
                .'</span>';
    }

    $output .= '</div>';

    // Add in the list for the summary items.
    $output .= theme('item_list', $summary['items']);

    // Close out the summary overview div.
    $output .= '</div>';
  }

  return $output;
}