block.module

<?php
/**
 * @file
 * Provides the ability to create reusable custom blocks.
 */

/**
 * Implements hook_permission().
 */
function block_permission() {
  $permissions['administer blocks'] = array(
    'title' => t('Administer custom blocks'),
    'description' => t('Manage custom blocks and access the custom block listing page.'),
  );
  return $permissions;
}

/**
 * Implements hook_menu().
 */
function block_menu() {
  $items['admin/structure/block'] = array(
    'title' => 'Custom blocks',
    'description' => 'Create reusable blocks that can be placed in layouts.',
    'page callback' => 'block_admin_list',
    'access arguments' => array('administer blocks'),
    'file' => 'block.admin.inc',
  );
  $items['admin/structure/block/list'] = array(
    'title' => 'List custom blocks',
    'type' => MENU_DEFAULT_LOCAL_TASK,
  );
  $items['admin/structure/block/manage/%'] = array(
    'title' => 'Configure block',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('block_admin_configure', 4),
    'access arguments' => array('administer blocks'),
    'file' => 'block.admin.inc',
  );
  $items['admin/structure/block/manage/%/configure'] = array(
    'title' => 'Configure block',
    'type' => MENU_DEFAULT_LOCAL_TASK,
    'context' => MENU_CONTEXT_NONE,
  );
  $items['admin/structure/block/manage/%/delete'] = array(
    'title' => 'Delete block',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('block_custom_block_delete', 4),
    'access arguments' => array('administer blocks'),
    'type' => MENU_CALLBACK,
    'context' => MENU_CONTEXT_NONE,
    'file' => 'block.admin.inc',
  );
  $items['admin/structure/block/manage/%/translation'] = array(
    'title' => 'Translate',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('block_custom_block_translate_list', 4),
    'access callback' => 'block_custom_block_translate_access',
    'access arguments' => array(4),
    'type' => MENU_LOCAL_TASK,
    'context' => MENU_CONTEXT_NONE,
    'file' => 'block.admin.inc',
  );
  $items['admin/structure/block/manage/%/translate/%'] = array(
    'title' => 'Translate block',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('block_custom_block_translate', 4, 6),
    'access callback' => 'block_custom_block_translate_access',
    'access arguments' => array(4, 6),
    'type' => MENU_NORMAL_ITEM,
    'context' => MENU_CONTEXT_NONE,
    'file' => 'block.admin.inc',
  );
  $items['admin/structure/block/add'] = array(
    'title' => 'Add custom block',
    'page callback' => 'backdrop_get_form',
    'page arguments' => array('block_add_block_form'),
    'access arguments' => array('administer blocks'),
    'type' => MENU_LOCAL_ACTION,
    'file' => 'block.admin.inc',
  );
  return $items;
}

/**
 * Implements hook_config_info().
 */
function block_config_info() {
  $prefixes['block.custom'] = array(
    'name_key' => 'delta',
    'label_key' => 'info',
    'group' => t('Custom Blocks'),
  );
  return $prefixes;
}

/**
 * Implements hook_block_info().
 */
function block_block_info() {
  global $language;
  $langcode = $language->langcode;

  // Statically cache to prevent multiple database lookups.
  $blocks = &backdrop_static(__FUNCTION__);
  if (isset($blocks)) {
    return $blocks;
  }

  $blocks = array();
  $config_names = config_get_names_with_prefix('block.custom.');
  foreach ($config_names as $config_name) {
    $block = config_get($config_name);
    $block_info = array();
    $block_info['info'] = $block['info'];
    $block_info['description'] = !empty($block['description']) ? $block['description'] : NULL;

    // If this block has been translated, return the translated information.
    if (isset($block['translations'][$langcode])) {
      $block_info['info'] = $block['translations'][$langcode]['info'];
      $block_info['description'] = $block['translations'][$langcode]['description'];
    }
    // If no description was entered, use a generic one.
    if (empty($block_info['description'])) {
      $block_info['description'] = t('A reusable custom block.');
    }
    $blocks[$block['delta']] = $block_info;
  }

  return $blocks;
}

/**
 * Implements hook_block_configure().
 */
function block_block_configure($delta) {
  if ($delta) {
    $custom_block = block_custom_block_load($delta);
    $custom_block['delta'] = $delta;
  }
  else {
    $custom_block = array();
  }
  return block_custom_block_form($custom_block, FALSE);
}

/**
 * Implements hook_block_save().
 */
function block_block_save($delta, &$edit = array()) {
  block_custom_block_save($edit, $delta);

  // Remove values from edit to prevent them from being saved in layout config.
  unset($edit['info']);
  unset($edit['title']);
  unset($edit['body']);
}

/**
 * Implements hook_block_view().
 *
 * Generates the administrator-defined blocks for display.
 */
function block_block_view($delta = '') {
  global $language;
  $block = block_custom_block_load($delta, $language->langcode);
  if (!$block) {
    return array();
  }
  $data['subject'] = strlen($block['title']) ? check_plain($block['title']) : NULL;
  $data['content'] = check_markup($block['body']['value'], $block['body']['format'], '', TRUE);
  return $data;
}

/**
 * Returns information from configuration about a user-created (custom) block.
 *
 * @param $delta
 *   ID of the block to get information for.
 * @param $langcode
 *   The language code for loading the block.
 *
 * @return array
 *   Associative array of information stored in configuration for this block, or FALSE if it doesn't exist
 *   Array keys:
 *   - delta: Block ID.
 *   - info: Block description.
 *   - body: Block contents.
 *   - format: Filter ID of the filter format for the body.
 */
function block_custom_block_load($delta, $langcode = LANGUAGE_NONE) {
  // Statically cache each translation to prevent multiple database lookups.
  $blocks = &backdrop_static(__FUNCTION__, array());
  if (isset($blocks[$delta][$langcode])) {
    return $blocks[$delta][$langcode];
  }

  $block = config_get('block.custom.' . $delta);
  if (!$block) {
    return FALSE;
  }

  // Ensure all expected keys are present.
  $block += array(
    'info' => '',
    'title' => '',
    'body' => '',
    'description' => '',
    'default_langcode' => LANGUAGE_NONE,
  );

  // If a translation is available, load it in to the main values.
  if ($langcode !== LANGUAGE_NONE && $langcode !== $block['default_langcode'] && isset($block['translations'])) {
    $block['langcode'] = $langcode;
    foreach (array('info', 'description', 'title', 'body') as $key) {
      if (isset($block['translations'][$langcode][$key])) {
        $block[$key] = $block['translations'][$langcode][$key];
      }
    }
    // Remove the translations from this copy to save on load bloat. Only the
    // source or non-translated load included all translations.
    unset($block['translations']);
  }

  $blocks[$delta][$langcode] = $block;
  return $blocks[$delta][$langcode];
}

/**
 * Form constructor for the custom block form.
 *
 * @param $edit
 *   (optional) An associative array of information retrieved by
 *   block_custom_get_block() if an existing block is being edited, or an empty
 *   array otherwise. Defaults to array().
 * @param $stand_alone
 *   (optional) Set to FALSE if this form is used when displaying as part of a
 *   form within the Layout UI. The default value of TRUE should be used if this
 *   is a stand-alone form, such as when editing a block at it's own URL.
 *
 * @ingroup forms
 */
function block_custom_block_form($edit = array(), $stand_alone = TRUE) {
  $edit += array(
    'delta' => NULL,
    'info' => '',
    'title' => '',
    'description' => '',
    'body' => array('value' => '', 'format' => NULL),
    'default_langcode' => LANGUAGE_NONE,
  );
  // If the description is the default from hook_block_info(), leave blank.
  if ($edit['description'] === t('A reusable custom block.')) {
    $edit['description'] = '';
  }

  $form['info'] = array(
    '#type' => 'textfield',
    '#title' => t('Admin label'),
    '#default_value' => $edit['info'],
    '#maxlength' => 64,
    '#description' => t('This text is used only in administrative interfaces. It will not be shown to site visitors.'),
    '#required' => TRUE,
    '#id' => 'block-info',
  );
  $form['delta'] = array(
    '#type' => 'machine_name',
    '#default_value' => $edit['delta'],
    '#maxlength' => 128,
    '#machine_name' => array(
      'exists' => 'block_custom_block_load',
      'source' => array('info'),
    ),
    '#description' => t('A unique machine-readable name for this Block. It must only contain lowercase letters, numbers, and underscores.'),
    '#disabled' => isset($edit['delta']),
  );
  $form['description'] = array(
    '#type' => 'textfield',
    '#title' => t('Admin description'),
    '#default_value' => $edit['description'],
    '#maxlength' => 128,
    '#description' => t('This text is used only in administrative interfaces. It will not be shown to site visitors.<br />Allowed HTML tags: @tags', array('@tags' => _filter_xss_display_allowed_tags())),
    '#id' => 'block-description',
  );
  $form['title'] = array(
    '#type' => 'textfield',
    '#title' => t('Display title'),
    '#default_value' => $edit['title'],
    '#maxlength' => 255,
    '#description' => t('The title of the block as shown to the user. This will affect all places where this block is used.'),
  );
  $form['body'] = array(
    '#type' => 'text_format',
    '#title' => t('Block content'),
    '#default_value' => $edit['body']['value'],
    '#format' => $edit['body']['format'],
    '#editor_uploads' => TRUE,
    '#rows' => 8,
    '#required' => TRUE,
  );

  // Add default language select dropdown on the stand-alone config form only.
  // Not shown on the translation forms at all.
  if ($stand_alone && module_exists('locale') && empty($edit['langcode'])) {
    $language_options = array(LANGUAGE_NONE => t('- None -'));
    $language_options += language_list(TRUE, TRUE);

    $form['default_langcode'] = array(
      '#type' => 'select',
      '#title' => t('Language'),
      '#description' => 'If assigned a language, options will be shown to translate this block into other languages.',
      '#options' => $language_options,
      '#default_value' => $edit['default_langcode'],
    );
  }

  // When displaying as part of the Layout UI.
  if (!$stand_alone) {
    // The Layout UI may show the translated block admin title and description,
    // but this form will only show the source translation contents. Notify
    // the user that they may be about to edit something they weren't expecting.
    if (!empty($edit['translations'])) {
      $form['translation_help'] = array(
        '#type' => 'help',
        '#markup' => '<strong>' . t('Translation notice') . ':</strong> ' . t('The settings in this form are for the source translation only. Translations may be modified on the <a href="!url">block\'s translation settings page</a>.', array('!url' => url('admin/structure/block/manage/' . $edit['delta'] . '/translation'))),
        '#weight' => -99,
      );
    }

    $form['title']['#states'] = array(
      'visible' => array(
        '[name=title_display]' => array('value' => LAYOUT_TITLE_DEFAULT),
      ),
    );
    $form['reusable'] = array(
      '#type' => 'checkbox',
      '#title' => t('Make this block reusable'),
      '#description' => t('This option may not be unchecked once enabled. You may configure or delete this reusable block from the !block_link page.', array('!block_link' => l(t('Custom blocks'), 'admin/structure/block'))),
      '#weight' => 4,
      '#default_value' => TRUE,
      '#disabled' => TRUE,
    );
    $form['info']['#weight'] = 5;
    $form['delta']['#weight'] = 6;
    $form['delta']['#machine_name']['source'] = array('block_settings', 'info');
    $form['description']['#weight'] = 7;
  }

  return $form;
}

/**
 * Saves a user-created block in a config file.
 *
 * @param array $edit
 *   Associative array of fields to save. Array keys:
 *   - delta: The machine name for the block
 *   - info: The administrative title for the block.
 *   - description: The administrative description for the block.
 *   - title: The block title (optional, since layouts have their own title field)
 *   - body: Associative array of body value and format. Array keys:
 *     - value: Block contents.
 *     - format: Filter ID of the filter format for the body.
 *   - default_langcode: The source translation language code string.
 *   - langcode: If specified, the values for info, description, title, and
 *     body will be saved as a translation of the source language.
 * @param string|NULL $delta
 *   Machine name of the block to save, comprised of lower-case letters,
 *   numbers, and underscores. Note: NULL values are still accepted when
 *   creating new nodes to maintain API contiguity.
 * @param $langcode
 *   The language code for the block. If set, only the translation is saved.
 */
function block_custom_block_save(array $edit, $delta = NULL, $langcode = NULL) {
  $delta = $delta ? $delta : preg_replace('/[^a-z0-9_]+/', '_', strtolower($edit['info']));
  $block = block_custom_block_load($delta);
  if (!$block) {
    $block = array(
      'delta' => $delta,
      'info' => '',
      'title' => '',
      'description' => '',
      'body' => array('value' => '', 'format' => ''),
      'default_langcode' => LANGUAGE_NONE,
    );
  }

  // If langcode is NULL or the default (source) language code, save into the
  // main configuration array.
  if ($langcode === NULL || $langcode === $block['default_langcode']) {
    // Clean up any copies of the translation, in the event the source had
    // changed.
    if ($langcode && isset($block['translations'][$langcode])) {
      unset($block['translations'][$langcode]);
    }
    // Store the main block configuration.
    foreach (array('info', 'description', 'title', 'body', 'default_langcode') as $key) {
      if (isset($edit[$key])) {
        $block[$key] = $edit[$key];
      }
    }
  }
  // Store the translation values.
  elseif ($langcode) {
    foreach (array('info', 'description', 'title', 'body') as $key) {
      $block['translations'][$langcode][$key] = $edit[$key];
    }
  }

  $config = config('block.custom.' . $delta);
  $config->setData($block);
  $config->save();

  // Save each file as permanent, preventing it from being deleted. The same
  // process is used in Layout::save(), but that only applies to non-reusable
  // blocks (BlockText objects). If a block has been marked reusable, the files
  // are immediately marked as permanent.
  // File usages are not currently removed for custom blocks.
  // See https://github.com/backdrop/backdrop-issues/issues/2137.
  $fids = filter_parse_file_fids($edit['body']['value']);
  $files = file_load_multiple($fids);
  foreach ($files as $fid => $file) {
    if ((int) ($file && $file->status) !== FILE_STATUS_PERMANENT) {
      // This makes the file "self-referencing", so it will never be deleted.
      file_usage_add($file, 'file', 'file', $file->fid);
    }
  }

  // Reset the static cache on the block list so this block is picked up.
  backdrop_static_reset('block_block_info');
}