ncstatebrandingbar.module

<?php
/***************************************************************************
 *
 * Module Name:  NC State Brand Bar
 * Plugin URI:   http://drupal.ncsu.edu
 * Description:  Creates an NC State Brand bar for integration into a Drupal site
 *
 * @todo - Replace all ? with appropriate documentation
 * 
 **************************************************************************/


/**
 * Create branding bar here, then call it later to generate a specific version
 *
 * @param string $color - Branding bar color selection
 * @param bool $center - Whether or not to center the bar
 * @param string $searchUrl - URL for local searching.  Blank if no local search.
 *
 * @return string
 */
function getBrandingBar($color, $center)
{
    
    $bb = new Ncstate_Brand_Bar();
     
    $options = array(
          'color'     => $color,
          'centered'  => ($center == 'yes'),
    	  'secure'	  => variable_get('ncstatebrandingbar_secure', 0),
          'siteUrl'   => variable_get('ncstatebrandingbar_siteUrl', ''),
    
    );
    
    $bb->setOptions($options);
    
    // commented out in Drupal 6, which does not support external stylesheets as part of drupal_add_css
    // actual css code has been added temporarily to ncstatebrandingbar.css
    //drupal_add_css($bb->getStylesheetUrl(), 'module', 'all', true);
     
    return $bb->getIframeHtml();
     
} 


/**
 * Gets the key delimiter when separating the color with the alignment in the
 * key for the form fields.
 *
 * @return string
 */
function getBrandingBarKeyDelimiter()
{
    return '__';
}

/**
 * Returns the available options for the implementation of the brand bar
 * 
 * @param boolean $withDescription - Whether or not to include the description
 * 
 * @return array 
 */
function getBrandingBarSelections($withDescription = true)
{
    		
    	$libraryPath = '/library/php-ncstate/Ncstate/Brand/Bar.php';	
	    $includePath = drupal_get_path('module', 'ncsuphplibrary');	
	    
	    // required during updates as the path isn't available yet to call 'new Ncstate_Brand_Bar()'
	    include_once($includePath . $libraryPath);
    		
	    $bb = new Ncstate_Brand_Bar();
	    $colorOptions = $bb->getColorOptions();
	
	    $description = 'NC State Brand Bar';
	
	    $selections = array();
	    $selections['none'] = 'None';
	
	    $delimiter = getBrandingBarKeyDelimiter();
	
	    // One option each for left and centered
	    foreach ($colorOptions as $key => $value) {
	        $selections[$key . $delimiter . 'left']     = (($withDescription) ? $description . ': ' : '') . $value;
	        $selections[$key . $delimiter . 'centered'] = (($withDescription) ? $description . ': ' : '') . $value . ' (centered)';
	    }
	
	    return $selections;

}


/**
 * Initialize settings for the module
 *
 */
function ncstatebrandingbar_init()
{ 
    
    $path = drupal_get_path('module', 'ncstatebrandingbar');

    // Performance: Defer execution.
    drupal_add_css($path . '/ncstatebrandingbar.css', 'module', 'all', true);
    drupal_add_js($path . '/ncstatebrandingbar.js', 'module', 'header', true);

    // pass variables to javascript so they can use the base path and theme path
    $js = "var ncstatebrandingbar_append_to_tag = '" . variable_get('ncstatebrandingbar_append_to_tag', 'body') . "';";
    drupal_add_js($js, 'inline');
    
}


/**
 * Preprocess page to add brand bar to closure, which is the last piece of
 * the rendered page inside the body tag.
 * 
 * Preprocess variables for page.tpl.php
 * http://api.drupal.org/api/drupal/includes--theme.inc/function/template_preprocess_page/6
 *
 * @param ? $vars - ?
 */
function ncstatebrandingbar_preprocess_page(&$vars)
{
    $selectedBrandingBar = variable_get('ncstatebrandingbar_select_version', 1);

    $block = module_invoke('ncstatebrandingbar', 'block', 'view', $selectedBrandingBar);
    $block = (!empty($block)) ? (object)$block : new stdClass();

    $vars['closure'] .= '<div id="ncstate-branding-bar-module">';
    $vars['closure'] .= '<h2>NC State Brand Bar</h2>';
    $vars['closure'] .= theme('block',$block);
    $vars['closure'] .= '</div>';
}


/**
 * Provide help and additional information about our module by implementing Drupal's hook_help().
 * Because of the use of the .info file that exists, this hook is now optional.
 * However, it is a best practice to implement it.
 * http://drupal.org/node/206756
 * http://api.drupal.org/api/drupal/developer--hooks--core.php/function/hook_help/6
 *
 * @param string $path - ?
 * @param ? $arg - ?
 * @return string
 */
function ncstatebrandingbar_help($path, $arg)
{
    $output = '';
    
    if ($path == "admin/help#ncstatebrandingbar") {
        $output .= '<p>'.  t("This module allows you to put a branding bar at the top of a drupal site, or select a different brand bar for different sections of the site using blocks.") .'</p>';
        $output .= '<p>'.  t("You can then assign a branding bar to different sections of the via each block's configuration page.") .'</p>';
        $output .= '<p>'.  t("<strong>For Example:</strong>") .'</p>';
        $output .= '<p>'.  t("You could display the \"Black\" branding bar on one particular page, but the \"Red\" branding bar on all other pages.") .'</p>';
        $output .= '<p>'.  t("NOTE: Using the brand bar blocks and the overall brand bar on the same page could cause problems.") .'</p>';
     }

     return $output;
}


/**
 * ?
 *
 * @param string $op - one of "list", "view", "save" and "configure"
 * @param int $delta - code to identify the block
 * @param array $edit - only for "save" operation
 * @return ?
 * 
 * http://api.drupal.org/api/drupal/developer--hooks--core.php/function/hook_block/6
 * http://drupal.org/node/206758
 */
function ncstatebrandingbar_block($op = 'list', $delta = 'none', $edit = array())
{
    // Gets all available selections
    $selections = getBrandingBarSelections();

    // if Drupal is just looking for a list of the blocks
    if ($op == 'list') {

        $blocks = array();

        foreach ($selections as $key => $value) {
            $blocks[$key] = array(
              'info' => t($value),
            );
        }

        return $blocks;

    } elseif ($op == 'view') {

        // Add no bar
        if ($delta == 'none') {
            return;
        }

        // Some kind of invalid key is found
        if (!isset($selections[$delta])) {
            return;
        }

        $options = explode(getBrandingBarKeyDelimiter(), $delta);
        
        $color    = $options[0];
        $centered = ($options[1] == 'centered');

        return array(
            'content' => getBrandingBar($color, $centered)
        );
    }
}


/**
 * Create a module settings/configuration page
 * 
 * @return ?
 *
 * http://drupal.org/node/206761
 */
function ncstatebrandingbar_admin()
{
    $form = array();

    $form['ncstatebrandingbar_select_version'] = array(
        '#type'          => 'select',
        '#title'         => t('Select a Brand Bar to display at the top of the website'),
        '#default_value' => variable_get('ncstatebrandingbar_select_version', 0),
        '#description'   => t("<p>If you choose a brand bar here, it will be displayed at the top of your website, just inside the <body> tag.</p><p>If you want to choose which region the brand bar should be placed in, or you want to display different branding bars on different pages, use the blocks that this module provides at ( browse to : admin/build/block ).</p>"),
        '#required'      => TRUE,
        '#options'       => array(),
    );

    $selections = getBrandingBarSelections(false);

    foreach ($selections as $key => $value) {
        $form['ncstatebrandingbar_select_version']['#options'][$key] = $value;
    }

    $form['ncstatebrandingbar_append_to_tag'] = array(
        '#type'          => 'textfield',
        '#title'         => t('Enter the HTML tag the brand bar should be appended to'),
        '#default_value' => variable_get('ncstatebrandingbar_append_to_tag', 'body'),
        '#description'   => t("<p>Use CSS selectors like &quot;#pageHeader&quot; or &quot;body&quot;</p>"),
        '#required'      => TRUE,
        '#size'          => 25,
    );
    
    $form['ncstatebrandingbar_siteUrl'] = array(
        '#type'          => 'textfield',
        '#title'         => t('Site URL for Searching via the Branding Bar'),
        '#default_value' => variable_get('ncstatebrandingbar_siteUrl', ''),
        '#description'   => t("<p>Do not include http:// or https:// in this field. <br />*Will not work when Secure URLs are enabled. Make this blank to remove on-site searching from the branding bar.</p>"),
        '#required'      => FALSE,
        '#size'          => 50,
    );
    
    $form['ncstatebrandingbar_secure'] = array(
        '#type'          => 'select',
        '#title'         => t('Use Secure URLS (https)?'),
        '#default_value' => variable_get('ncstatebrandingbar_secure', 0),
        '#description'   => t("<p>If you choose yes here, it will force the brand bar to use https instead of http.</p>"),
        '#required'      => TRUE,
        '#options'       => array(0 => 'No', 1 => 'Yes'),
    );

    return system_settings_form($form);

}


/**
 * Need to define a URL within Drupal for the module settings page
 * http://api.drupal.org/api/drupal/developer--hooks--core.php/function/hook_menu/6
 * http://drupal.org/node/206761
 *
 * @return ?
 */
function ncstatebrandingbar_menu()
{
    $items = array();

    $items['admin/settings/ncstatebrandingbar'] = array(
        'title'            => 'NC State Brand Bar',
        'description'      => 'Configure Default Branding Bar and other options',
        'page callback'    => 'drupal_get_form',
        'page arguments'   => array('ncstatebrandingbar_admin'),
        'access arguments' => array('access administration pages'),
        'type'             => MENU_NORMAL_ITEM,
    );

    return $items;

}


/**
 * Although we aren't required to validate the user input, it is nice to do so.
 * This will make sure the input from the fields are the expected types (numeric etc)
 * http://drupal.org/node/206761
 *
 * @param ? $form - ?
 * @param ? $form_state - ?
 */
function ncstatebrandingbar_admin_validate($form, &$form_state)
{
    $selectedBrandBar = $form_state['values']['ncstatebrandingbar_select_version'];

    $selections = getBrandingBarSelections();
    
    if (!isset($selections[$selectedBrandBar])) {
        form_set_error('ncstatebrandingbar_select_version', t('Only a preset option is available for this field.'));
    }
}