Extra db_query() and data presentation examples from X-ray module

  • In addition to the data-gathering functions and the theme functions that turn the data into descriptive paragraphs (shown immediately below), seeing X-ray's summary data require implementations of hook_theme(), hook_menu(), and hook_help(), shown below the functions handling the queries and presentation.

    <?php
    /**
     * Summary data for People section (admin/people).
     */
    function xray_people_summary() {
     
    $data = array();
     
    // Fetch the number of enabled and disabled (blocked) users.
     
    $data['users'] = db_query("SELECT status, COUNT(*) as num FROM {users} WHERE uid <> 0 GROUP BY status")->fetchAllKeyed();
     
    // @TODO roles, permissions
     
    return $data;
    }

    /**
     * Returns HTML text summary of People section (admin/people) data.
     *
     * @param $attributes
     *   (optional) An associative array of HTML tag attributes, suitable for
     *   flattening by drupal_attributes().
     * @param $variables
     *   An associative array containing:
     *   - data: result of xray_people_summary().
     *
     * @ingroup themeable
     */
    function theme_xray_people_summary($variables) {
     
    $data = $variables['data'];
     
    // Collapse attributes for paragraph tag to a string.
     
    $attr = drupal_attributes($variables['attributes']);

     

    $output = '';
     
    $output .= "<p $attr>";
     
    // No isset check: if you have no active user, you have a bigger problem than
      // an undefined index.
     
    $output .= format_plural($data['users'][1],
       
    'The site has <strong>one active user</strong>',
       
    'The site has <strong>@count active users</strong>');
      if (isset(
    $data['users'][0])) {
       
    $output .= format_plural($data['users'][0],
         
    ' and one blocked user.',
         
    ' and @count blocked users.');
       
    $output .= '</p>';
      }
      else {
       
    $output .= t(' and no blocked users.');
      }
      return
    $output;
    }

    /**
     * Summary data for Modules section (admin/modules).
     */
    function xray_modules_summary() {
     
    $data = array();
     
    $result = db_query("SELECT status, COUNT(*) FROM {system} WHERE type = 'module' GROUP BY status")
        ->
    fetchAllKeyed();
     
    $data['modules_by_status'] = $result;
      return
    $data;
    }

    /**
     * Returns HTML text summary of Modules section (admin/modules) data.
     *
     * @param $attributes
     *   (optional) An associative array of HTML tag attributes, suitable for
     *   flattening by drupal_attributes().
     * @param $variables
     *   An associative array containing:
     *   - data: result of xray_modules_summary().
     *
     * @ingroup themeable
     */
    function theme_xray_modules_summary($variables) {
     
    $data = $variables['data'];
     
    // Collapse attributes for paragraph tag to a string.
     
    $attr = drupal_attributes($variables['attributes']);

     

    $output = '';
     
    $output .= "<p $attr>";
     
    $output .= t('This site has <strong>@enabled_count enabled modules</strong> (and an additional @disabled_count modules present but not enabled).',
        array(
    '@enabled_count' => $data['modules_by_status'][1],
             
    '@disabled_count' => $data['modules_by_status'][0])
      );
     
    $output .= '</p>';
      return
    $output;
    }
    ?>

    The theme functions above need the implementation of hook_theme() below in order to function, and the data and theme combinations need this implementation of hook_help() to print X-ray's information in the respective administration sections and the implementation of hook_menu() and its callback to show up on the admin/reports/xray page. All of that is in this code:

    <?php
    /**
     * Implements hook_help().
     */
    function xray_help($path, $arg) {
     
    $help = '';
     
    // Display in a help message the function which provides the current page.
     
    $help .= xray_show_page_callback($path);
      switch (
    $path) {
       
    // Summaries for main administrative sections.
       
    case 'admin/content':
         
    $variables = array('data' => xray_content_summary());
          return
    $help . theme('xray_content_summary__help', $variables);
        case
    'admin/structure':
         
    $variables = array('data' => xray_structure_summary());
          return
    $help . theme('xray_structure_summary__help', $variables);
        case
    'admin/appearance':
         
    $variables = array('data' => xray_appearance_summary());
          return
    $help . theme('xray_appearance_summary__help', $variables);
        case
    'admin/people':
         
    $variables = array('data' => xray_people_summary());
          return
    $help . theme('xray_people_summary__help', $variables);
        case
    'admin/modules':
         
    $variables = array('data' => xray_modules_summary());
          return
    $help . theme('xray_modules_summary__help', $variables);
       
    // The main help page for the module itself.
       
    case 'admin/help#xray':
         
    // This is shown as a regular page; do not include the
          // xray_show_page_callback $help or it is shown twice.
         
    return _xray_help_page();
        default:
          return
    $help;
      }
    }

    /**
     * Implements hook_menu().
     */
    function xray_menu() {
     
    $items = array();
     
    $items['admin/reports/xray'] = array(
       
    'title' => 'X-ray technical site overview',
       
    'description' => 'See the internal structure of this site.',
       
    'page callback' => 'xray_overview_page',
       
    'access arguments' => array('access site reports'),
      );
     
    $items['admin/reports/xray/overview'] = array(
       
    'title' => 'Overview',
       
    'type' => MENU_DEFAULT_LOCAL_TASK,
       
    'weight' => -10,
      );
     
    $items['admin/reports/xray/permissions'] = array(
       
    'title' => 'Permissions',
       
    'page callback' => 'xray_permission_names_page',
       
    'type' => MENU_LOCAL_TASK,
       
    'weight' => 10,
       
    'access arguments' => array('access site reports'),
      );
     
    $items['admin/reports/xray/hooks'] = array(
       
    'title' => 'Hooks',
       
    'page callback' => 'xray_hook_implementations_page',
       
    'type' => MENU_LOCAL_TASK,
       
    'weight' => 20,
       
    'access arguments' => array('access site reports'),
      );
     
    $items['admin/reports/xray/conf'] = array(
       
    'title' => 'Configuration variables',
       
    'page callback' => 'xray_reports_conf_vars_page',
       
    'type' => MENU_LOCAL_TASK,
       
    'weight' => 20,
       
    'access arguments' => array('access site reports'),
      );
     
    // Administration page.
     
    $items['admin/config/development/xray'] = array(
       
    'title' => 'X-ray configuration',
       
    'description' => 'Configure which elements of internal site structure will be shown.',
       
    'page callback' => 'drupal_get_form',
       
    'page arguments' => array('xray_admin_settings'),
       
    'access arguments' => array('administer site configuration'),
       
    'file' => 'xray.admin.inc',
      );
      return
    $items;
    }

    /**
     * Implements hook_theme().
     */
    function xray_theme() {
      return array(
       
    'xray_show_page_callback' => array(
         
    'variables' => array(
           
    'page_callback' => NULL,
           
    'include_file' => NULL,
           
    'page_arguments' => NULL,
           
    'extra' => '',
          ),
        ),
       
    'xray_appearance_summary' => array(
         
    'variables' => array(
           
    'data' => array(),
           
    'attributes' => array('class' => 'xray-help'),
          ),
        ),
       
    'xray_content_summary' => array(
         
    'variables' => array(
           
    'data' => array(),
           
    'attributes' => array('class' => 'xray-help'),
          ),
        ),
       
    'xray_structure_summary' => array(
         
    'variables' => array(
           
    'data' => array(),
           
    'attributes' => array('class' => 'xray-help'),
          ),
        ),
       
    'xray_people_summary' => array(
         
    'variables' => array(
           
    'data' => array(),
           
    'attributes' => array('class' => 'xray-help'),
          ),
        ),
       
    'xray_modules_summary' => array(
         
    'variables' => array(
           
    'data' => array(),
           
    'attributes' => array('class' => 'xray-help'),
          ),
        ),
      );
    }

    /**
     * Overview page with summaries of site internal data.
     */
    function xray_overview_page() {
     
    $build = array();
     
    $build['intro'] = array(
       
    '#markup' => '<p>' . t("Technical overview of the site's internals.  These summaries also appear / can be configured to appear on main administration section.") . '</p>',
      );
     
    // Repeat each summary from the top of each administrative section.
     
    $build['admin_content_title'] = array(
       
    '#theme' => 'html_tag',
       
    '#tag' => 'h3',
       
    '#attributes' => array('class' => 'xray-section-title'),
       
    '#value' => t('Content summary'),
      );
     
    $data = xray_content_summary();
     
    $build['content_summary'] = array(
       
    '#theme' => 'xray_content_summary__reports',
       
    '#data' => $data,
       
    '#attributes' => array('class' => 'xray-report'),
      );

     

    $build['structure_title'] = array(
       
    '#theme' => 'html_tag',
       
    '#tag' => 'h3',
       
    '#attributes' => array('class' => 'xray-section-title'),
       
    '#value' => t('Structure summary'),
      );
     
    $data = xray_structure_summary();
     
    $build['structure_summary'] = array(
       
    '#theme' => 'xray_structure_summary__reports',
       
    '#data' => $data,
       
    '#attributes' => array('class' => 'xray-report'),
      );

     

    $build['appearance_title'] = array(
       
    '#theme' => 'html_tag',
       
    '#tag' => 'h3',
       
    '#attributes' => array('class' => 'xray-section-title'),
       
    '#value' => t('Appearance summary'),
      );
     
    $data = xray_appearance_summary();
     
    $build['appearance_summary'] = array(
       
    '#theme' => 'xray_appearance_summary__reports',
       
    '#data' => $data,
       
    '#attributes' => array('class' => 'xray-report'),
      );

     

    $build['people_title'] = array(
       
    '#theme' => 'html_tag',
       
    '#tag' => 'h3',
       
    '#attributes' => array('class' => 'xray-section-title'),
       
    '#value' => t('People summary'),
      );
     
    $data = xray_people_summary();
     
    $build['people_summary'] = array(
       
    '#theme' => 'xray_people_summary__reports',
       
    '#data' => $data,
       
    '#attributes' => array('class' => 'xray-report'),
      );

     

    $build['modules_title'] = array(
       
    '#theme' => 'html_tag',
       
    '#tag' => 'h3',
       
    '#attributes' => array('class' => 'xray-section-title'),
       
    '#value' => t('Modules summary'),
      );
     
    $data = xray_modules_summary();
     
    $build['modules_summary'] = array(
       
    '#theme' => 'xray_modules_summary__reports',
       
    '#data' => $data,
       
    '#attributes' => array('class' => 'xray-report'),
      );
      return
    $build;
    }
    ?>