You are here

Home » API reference » Block Refresh 5

block_refresh.module in Block Refresh 5

Same filename and directory in other branches
  1. 8 block_refresh.module
  2. 6 block_refresh.module
  3. 7.2 block_refresh.module
  4. 7 block_refresh.module

File

block_refresh.module
View source 
<?php

define('BLOCK_REFRESH_AUTOREFRESH_DEFAULT_ENABLE', FALSE);

// autorefresh disabled by default
define('BLOCK_REFRESH_AUTOREFRESH_DEFAULT_MANUAL', FALSE);

// manual refresh disabled by default
define('BLOCK_REFRESH_AUTOREFRESH_DEFAULT_TIMER', 120);

// default refreshes every two minutes, if enabled

/**
 *  Add a 'Block Refresh' settings fieldset to the block admin form
 */
function block_refresh_form_alter($form_id, &$form) {
  if ($form_id == 'block_admin_configure') {
    $settings = variable_get('block_refresh_settings', array());
    $form['#submit']['block_refresh_submit'] = array();
    $form['block_refresh'] = array(
      '#type' => 'fieldset',
      '#title' => t('Block refresh settings'),
      '#collapsible' => true,
      '#weight' => -5,
    );
    $form['block_refresh']['block_refresh_enable'] = array(
      '#type' => 'checkbox',
      '#title' => t('Enable block autorefresh'),
      '#description' => t('If checked, then the content of this block may be autorefreshed automatically on a timer.'),
      '#default_value' => isset($settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['enabled']) ? $settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['enabled'] : variable_get('block_refresh_autorefresh_default_enable', BLOCK_REFRESH_AUTOREFRESH_DEFAULT_ENABLE),
    );
    $form['block_refresh']['block_refresh_manual'] = array(
      '#type' => 'checkbox',
      '#title' => t('Enable block manual refresh'),
      '#description' => t('If checked, then the content of this block may be refreshed manually by the user, by clicking on a provided (themeable) button in the block\'s subject header.'),
      '#default_value' => isset($settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['manual']) ? $settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['manual'] : variable_get('block_refresh_manual_refresh_default_enable', BLOCK_REFRESH_AUTOREFRESH_DEFAULT_MANUAL),
    );
    $form['block_refresh']['block_refresh_group'] = array(
      '#type' => 'checkbox',
      '#title' => t('Group with other refreshing blocks'),
      '#description' => t('If checked, then this block will be refreshed with other blocks. If also set to autorefresh, then the timer setting will be ignored, instead using the global setting of @seconds.', array(
        '@seconds' => format_plural(variable_get('block_refresh_group_auto_timer', BLOCK_REFRESH_AUTOREFRESH_DEFAULT_TIMER), '1 second', '@count seconds'),
      )),
      '#default_value' => isset($settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['group']) ? $settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['group'] : variable_get('block_refresh_group_auto', TRUE),
    );
    $form['block_refresh']['block_refresh_timer'] = array(
      '#type' => 'textfield',
      '#title' => t('Block refresh timer'),
      '#description' => t('Assuming that Blox Autorefresh is enabled, then the content of this block will refresh itself periodically, every number of seconds equal to this setting. If this block is grouped to refresh with other blocks, then this setting will be ignored, instaed using the global setting of @seconds.', array(
        '@seconds' => format_plural(variable_get('block_refresh_group_auto_timer', BLOCK_REFRESH_AUTOREFRESH_DEFAULT_TIMER), '1 second', '@count seconds'),
      )),
      '#default_value' => $settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['timer'] ? $settings['block-' . $form['module']['#value'] . '-' . $form['delta']['#value']]['timer'] : variable_get('block_refresh_autorefresh_default_timer', BLOCK_REFRESH_AUTOREFRESH_DEFAULT_TIMER),
    );
  }
}

/**
 *  handle submission of block refresh form on block settings page
 */
function block_refresh_submit($form_id, $edit) {
  $settings = variable_get('block_refresh_settings', array());
  $settings['block-' . $edit['module'] . '-' . $edit['delta']]['enabled'] = $edit['block_refresh_enable'];
  $settings['block-' . $edit['module'] . '-' . $edit['delta']]['manual'] = $edit['block_refresh_manual'];
  $settings['block-' . $edit['module'] . '-' . $edit['delta']]['group'] = $edit['block_refresh_group'];
  $settings['block-' . $edit['module'] . '-' . $edit['delta']]['timer'] = $edit['block_refresh_timer'];
  $settings['block-' . $edit['module'] . '-' . $edit['delta']]['block'] = array(
    'block' => $edit['module'],
    'delta' => $edit['delta'],
  );
  variable_set('block_refresh_settings', $settings);
}

/**
 *  implements hook_menu
 */
function block_refresh_menu($may_cache) {
  $items = array();
  if ($may_cache) {
    $items[] = array(
      'path' => 'admin/settings/block_refresh',
      'title' => t('Block refresh'),
      'description' => t('Settings for automatic and manual refreshing of configured blocks.'),
      'callback' => 'drupal_get_form',
      'callback arguments' => 'block_refresh_settings',
      'access' => user_access('administer site configuration'),
    );

    // this will display the contents of a block, if it's enabled
    $items[] = array(
      'path' => 'block_refresh',
      'type' => MENU_CALLBACK,
      'access' => user_access('access block refresh content'),
      'callback' => 'block_refresh_block_content',
      'title' => t('Block refresh block content'),
    );
  }
  return $items;
}

/**
 *  implements hook_perm -- add permission for accessing auto/manually refreshed block content
 */
function block_refresh_perm() {
  return array(
    'access block refresh content',
  );
}

/**
 *  callback for admin/settings/block_refresh
 */
function block_refresh_settings() {
  $form = array();
  $form['settings'] = array(
    '#type' => 'fieldset',
    '#title' => t('Settings help'),
    '#collapsible' => TRUE,
  );
  $form['settings']['configure'] = array(
    '#type' => 'item',
    '#value' => t("Ensure that you have !configured for user roles. Adding a permission to %access will allow a block, when configured, to be refreshed automatically and/or manually.", array(
      '%access' => 'access block refresh content',
      '!configured' => l(t('configured permissions'), 'admin/user/access', array(), NULL, 'module-block_refresh'),
    )),
  );
  $form['settings']['settings'] = array(
    '#type' => 'item',
    '#value' => t("You will also need to set the appropriate settings for each block that you wish to automatically and/or manually refresh by clicking on the appropriate %configure link(s) on the !admin.", array(
      '%configure' => t('configure'),
      '!admin' => l(t('blocks administration page'), 'admin/build/block'),
    )),
  );
  $form['global'] = array(
    '#type' => 'fieldset',
    '#title' => t('Global settings'),
    '#collapsible' => TRUE,
  );
  $form['global']['block_refresh_group_auto'] = array(
    '#type' => 'checkbox',
    '#title' => t('Group block refreshes'),
    '#description' => t('If checked, then all grouped block refresh enabled blocks will be refreshed together, whether manually or using the timer settings below. To group blocks together, check the appropriate block on that block\'s configuration settings page.'),
    '#default_value' => variable_get('block_refresh_group_auto', TRUE),
  );
  $form['global']['block_refresh_group_auto_timer'] = array(
    '#type' => 'textfield',
    '#title' => t('Group block refresh timer'),
    '#description' => t('Enter the time, in seconds, that grouped blocks will refresh, when grouped and set to automatic.'),
    '#default_value' => variable_get('block_refresh_group_auto_timer', BLOCK_REFRESH_AUTOREFRESH_DEFAULT_TIMER),
  );
  return system_settings_form($form);
}

/**
 *  page callback for /block_refresh/[module]/[delta]
 *  displays the block content, without any other page information
 */
function block_refresh_block_content($block = NULL, $delta = NULL) {
  if (!isset($block) || !isset($delta) || $block != 'block_refresh' && !module_implements($block, 'block')) {
    drupal_not_found();
  }
  if ($block == 'block_refresh' && $delta == 'all') {
    $query = isset($_GET['blocks']) ? $_GET['blocks'] : '';
    $pairs = explode(',', $query);
    foreach ($pairs as $pair) {
      list($module, $delta) = explode('|', $pair);
      $block = module_invoke($module, 'block', 'view', $delta);
      $output .= '<div id="block-refresh-data-' . $module . '-' . $delta . '">' . $block['content'] . '</div>';
    }
    if ($output) {
      print '<div id="block-refresh-data-all" class="block-refresh-hidden">' . $output . '</div>';
    }
    exit;
  }
  $settings = variable_get('block_refresh_settings', array());
  if (!$settings['block-' . $block . '-' . $delta]['enabled'] && !$settings['block-' . $block . '-' . $delta]['manual']) {
    drupal_not_found();
  }
  $block = module_invoke($block, 'block', 'view', $delta);
  print $block['content'];
  exit;
}

/**
 *  implements hook_footer
 *  calls the jquery to refresh blocks automatically, but only if the blocks exist on the current page and are enabled
 */
function block_refresh_footer() {

  // don't bother to continue if the user can't refresh content anyway...
  if (!user_access('access block refresh content')) {
    return;
  }
  global $theme_key;
  $blocks = array();
  $regions = system_region_list($theme_key);
  foreach ($regions as $region => $value) {
    $blocks = array_merge($blocks, block_list($region));
  }
  $settings = variable_get('block_refresh_settings', array());
  foreach ($settings as $block) {
    if (isset($blocks[$block['block']['block'] . '_' . $block['block']['delta']])) {
      if ($block['enabled']) {
        $js .= theme('block_refresh_js', $block);
      }
      if ($block['manual']) {
        $js .= theme('block_manual_refresh_js', $block);
      }
    }
  }
  if ($js) {
    if (!module_invoke('jq', 'add', 'block_refresh')) {
      drupal_add_js(drupal_get_path('module', 'block_refresh') . '/js/block_refresh.js');
      drupal_add_css(drupal_get_path('module', 'block_refresh') . '/css/block_refresh.css');
    }
    drupal_add_js(theme('block_refresh_js_wrapper', $js), 'inline');
  }
}

/**
 *  call the js for an enabled block div.
 *  you might need to override $div if your blocks have different id's than the drupal standard.
 *  or you may wish to manually put this code in your block.tpl.php file for fine-tune control,
 *  although that would take some finagling to do properly.
 */
function theme_block_refresh_js($block) {

  // this is the block div css id and content class
  $div = "#block-{$block['block']['block']}-{$block['block']['delta']} .content";

  // we store seconds, but js expects milliseconds
  $timer = $block['timer'] * 1000;
  $base = base_path();
  $js .= "  _block_refresh_data['{$div}'] = new block_refresh_data({$timer}, '{$base}block_refresh/{$block['block']['block']}/{$block['block']['delta']}');\n";
  $js .= "  block_refresh_timer('{$div}');";
  return $js;
}

/**
 *  Add a manual refresh button to the header...
 */
function theme_block_manual_refresh_js($block) {

  // this is the block div css id and content class
  $div = "block-{$block['block']['block']}-{$block['block']['delta']}";
  $base = base_path();
  $url = "{$base}block_refresh/{$block['block']['block']}/{$block['block']['delta']}";
  $content_url = "#{$div} .content";
  $js .= "  block_refresh_add_button('{$div}', '{$url}', '{$content_url}');";
  return $js;
}

/**
 *  put the whole thing in a jquery ready call
 */
function theme_block_refresh_js_wrapper($js) {
  return "\$(document).ready(function() {\n{$js}\n})";
}

/**
 *  Implements hook_jq
 *  Allows optional integration with the jQ module.
 */
function block_refresh_jq($op, $plugin = NULL, $args = array(), $already_loaded = NULL) {
  switch ($op) {
    case 'info':
      $info = array();
      $info['block_refresh'] = array(
        'name' => t('Block Refresh'),
        'description' => t('Block Refresh allows an administrator to set up any block to automatically refresh its content every x seconds. Uses jQuery. Configure on individual blocks.'),
        'url' => 'http://drupal.org/project/block_refresh',
        'version' => t('1.2'),
        'files' => array(
          'js' => array(
            drupal_get_path('module', 'block_refresh') . '/js/block_refresh.js',
          ),
          'css' => array(
            drupal_get_path('module', 'block_refresh') . '/css/block_refresh.css',
          ),
        ),
      );
      return $info;
  }
}

Functions

Namesort descending Description
block_refresh_block_content page callback for /block_refresh/[module]/[delta] displays the block content, without any other page information
block_refresh_footer implements hook_footer calls the jquery to refresh blocks automatically, but only if the blocks exist on the current page and are enabled
block_refresh_form_alter Add a 'Block Refresh' settings fieldset to the block admin form
block_refresh_jq Implements hook_jq Allows optional integration with the jQ module.
block_refresh_menu implements hook_menu
block_refresh_perm implements hook_perm -- add permission for accessing auto/manually refreshed block content
block_refresh_settings callback for admin/settings/block_refresh
block_refresh_submit handle submission of block refresh form on block settings page
theme_block_manual_refresh_js Add a manual refresh button to the header...
theme_block_refresh_js call the js for an enabled block div. you might need to override $div if your blocks have different id's than the drupal standard. or you may wish to manually put this code in your block.tpl.php file for fine-tune control, although that would…
theme_block_refresh_js_wrapper put the whole thing in a jquery ready call

Constants

Namesort descending Description
BLOCK_REFRESH_AUTOREFRESH_DEFAULT_ENABLE
BLOCK_REFRESH_AUTOREFRESH_DEFAULT_MANUAL
BLOCK_REFRESH_AUTOREFRESH_DEFAULT_TIMER