You are here

Home » API reference » Simple Dialog 8

simple_dialog.module in Simple Dialog 8

Same filename and directory in other branches
  1. 7 simple_dialog.module

File

simple_dialog.module
View source 
<?php

use Drupal\Core\Template\Attribute;

/*****************************************************************************
* DRUPAL HOOKS
*****************************************************************************/

/**
 * Implements hook_page_build()
 */
function simple_dialog_page_build(&$page) {
  $path = drupal_get_path('module', 'simple_dialog');

  // Add JavaScript/CSS assets to all pages.
  // @see drupal_process_attached()
  $page['#attached']['css'][$path . '/css/simple_dialog.css'] = array(
    'every_page' => TRUE,
  );
  if (\Drupal::config('simple_dialog.settings')
    ->get('js_all')) {
    simple_dialog_attach_js($page, TRUE);
  }
}

/**
 * Implements hook_help().
 */
function simple_dialog_help($path, $arg) {
  switch ($path) {

    // Main module help for the block module
    case 'admin/help#simple_dialog':
      return t('<h2>SIMPLE DIALOG</h2>
      <p>This module provides a method to load pages via AJAX into a modal dialog window that will be overlaid on the screen.</p>
      <p>The module implements the jquery ui dialog plugin that is provided with Drupal 7.</p>
      <h3>CONFIGURATION</h3>
      <p>The configuration page is at admin/config/content/simple-dialog.</p>
      <ol><li>Add simple dialog javascript files to all pages.
      <p>By Default this option is selected. This option is here in case you\'re trying to limit the amount of data loaded on each page load. If you\'re not worried about that you can probably just leave this enabled. A couple things to note if you disable this setting:</p>
      <ul>
      <li>You will need to add the javascript files to the page manually if you want to implement the "simple-dialog" class method.</li>
      <li>If you are adding simple dialog links to the page using theme(\'simple_dialog\'...), the necessary javascript is added within those functions so you should be okay.</li>
      </ul>
      </li>
      <li>Additional Classes
      <p>This option allows you to specify custom classes that will also be used to launch a modal. This can be useful if you want to use a simple class like \'popup\' to launch the modal, or perhaps if you\'re upgrading a site from d6 that used the automodal module and you just want to continue using the automodal class instead of changing all your links.
      <p>A space-separated list of classes should be provided with no leading
or trailing spaces.</p>
      </li>
      <li>Default Dialog Settings
      <p>Provide some default settings for the dialog. Defaults should be formatted the same way as you would in the "rel" tag of the link (described below under HTML Implementation)</p>
      </li>
      </ol>
      <h3>JAVASCRIPT</h3>
      <p>This module doesn\'t not bring javascript files over from the target page. If your target html needs javascript to work, You will need to make sure your javascript is either inline in the html that\'s being loaded, or in the head tag of the page you are on.</p>
      <p>Additionally, there is a custom javascript event available that gets triggered after the dialog is loaded. example:</p>
      <pre>
      $(\'#simple-dialog-container\').bind(\'simpleDialogLoaded\', function (event) {
        ... do something ...
      });
      </pre>
      <h3>HTML Implementation</h3>
      <p>Add the class \'simple-dialog\' to open links in a dialog. You also need to specify \'name="{selector}"\' where the {selector} is the unique html element id of the container to load from the linked page, as well as the title attribute that will act as the title of the dialog. Any additional jquery ui dialog options can be passed through the rel tag using the format:</p>
      <p>rel="{option-name1}:{value1};{option-name2}:{value2};"</p>
      <p>NOTE: For the position option, if you want to pass in an array of xy values, use the syntax [{x},{y}] with no quotes or spaces.</p>
      <p>example:</p>
      <pre>
      &lt;a href="path/to/target/page/to/load" class="id-of-element-on-target-page-to-load" rel="width:900;resizable:false;position:[center,60]" name="content-area" title="My Dialog Title"&gt;Link&lt;/a&gt;
      </pre><p></p>
      <p>The available jquery ui dialog options can be found here:</p>
      <p><a href="http://jqueryui.com/demos/dialog" title="http://jqueryui.com/demos/dialog">http://jqueryui.com/demos/dialog</a></p>
      <h3>Theme Implementation</h3>
      <p>You can also implement a simple dialog link using the simple_dialog_link theme implementation</p>' . "\n      <pre>\n      \$element = array(\n        '#theme' => 'simple_dialog_link',\n        '#text' => 'Click Me To See The Dialog',\n        '#path' => '/simple-dialog-example/target-page',\n        '#selector' => 'load-this-element',\n        '#title' => 'My Dialog Title',\n        '#options' => array(\n          'width' => 900,\n          'resizable' => FALSE,\n          'position' => array('center', 60) // can be an array of xy values\n        ),\n        '#class' => array('my-link-class'),\n      );\n      drupal_render(\$element);\n      </pre>" . '
      <p>For the \'position\' option, the value can be a string or an array of xy values. Per the jquery ui dialog documentation at
      <a href="http://jqueryui.com/demos/dialog/#option-position:" title="http://jqueryui.com/demos/dialog/#option-position:">http://jqueryui.com/demos/dialog/#option-position:</a></p>
      <p>Specifies where the dialog should be displayed. Possible values:</p>
      <ol>
      <li>a single string representing position within viewport: "center", "left", "right", "top", "bottom". </li>
      <li>an array containing an x,y coordinate pair in pixel offset from left, top corner of viewport (e.g. array(350,100)) </li>
      <li>an array containing x,y position string values (e.g. array("right","top") for top right corner).</li>
      </ol>');
  }
}

/**
 * Implements hook_permission().
 */
function simple_dialog_permission() {
  return array(
    'administer simple dialog' => array(
      'title' => t('Administer Simple Dialog'),
    ),
  );
}

/**
 * Implements hook_theme().
 */
function simple_dialog_theme($existing, $type, $theme, $path) {
  return array(
    'simple_dialog_link' => array(
      'variables' => array(
        'text' => NULL,
        'path' => NULL,
        'selector' => NULL,
        'title' => NULL,
        'options' => array(),
        'link_options' => array(),
        'class' => array(),
      ),
      'template' => 'simple-dialog-link',
    ),
  );
}

/*****************************************************************************
* THEME PREPROCESSORS
*****************************************************************************/

/**
 * Preprocesses variables for simple dialog links
 *
 * @param $variables
 *   An associative array containing:
 *   - text: The link text for the anchor tag.
 *   - path: The URL to pull the dialog contents from.
 *   - title: The 'title' attribute of the link. Will also be used for the title
 *     of the jQuery ui dialog
 *   - selector: The css id of the element on the target page. This element and it's
 *     containing html will be loaded via AJAX into the dialog window.
 *   - attributes: An associative array of additional link attributes
 *   - class: An array of classes to add to the link. Use this argument instead
 *     of adding it to attributes[class] to avoid it being overwritten.
 *   - options: (optional) An associative array of additional jQuery ui dialog
 *     options keyed by the option name. example:
 *     @code
 *     $options =  array(
 *       'optionName' => 'optionValue', // examples:
 *       'width' => 900,
 *       'resizable' => FALSE,
 *       'position' => 'center', // Position can be a string or:
 *       'position' => array(60, 'top') // can be an array of xy values
 *     ),
 *     @endcode
 */
function template_preprocess_simple_dialog_link(&$variables) {

  // Somewhere to store our dialog options. Will be imploded at the end
  $dialog_options = array();

  // as long as there are some options and the options variable is an array
  if ($variables['options'] && is_array($variables['options'])) {
    foreach ($variables['options'] as $option_name => $value) {
      if ($option_name == 'position' && is_array($value)) {
        $dialog_options[] = $option_name . ':[' . $value[0] . ',' . $value[1] . ']';
      }
      elseif ($value) {
        $dialog_options[] = $option_name . ':' . $value;
      }
      else {
        $dialog_options[] = $option_name . ':false';
      }
    }
  }

  // Concatenate using the semi-colon
  $dialog_options = implode(';', $dialog_options);

  // Setup the default attributes
  array_unshift($variables['class'], 'simple-dialog');
  $attributes = array(
    'title' => $variables['title'],
    'name' => $variables['selector'],
    'rel' => $dialog_options,
    'class' => $variables['class'],
  );

  // We need to merge any other attributes that were provided through the
  // attributes variable
  if (!empty($variables['attributes'])) {
    $attributes = array_merge($variables['attributes'], $attributes);
  }
  $variables['attributes'] = new Attribute($attributes);
}

/*****************************************************************************
* HELPER FUNCTIONS
*****************************************************************************/

/**
 * Adds the necessary js and libraries to make the
 * dialog work. Really just adds the jquery.ui
 * library and the simple dialog javscript file
 * but if we need to add anything else down the road,
 * at least it's abstracted into an api function
 *
 * @param array $element
 *        The renderable array element to #attach the js to
 *
 * @param boolean $every_page
 *        Optional variable to specify the simple dialog code should be added
 *        to every page. Defaults to false. If you're calling this function,
 *        you likely will not need to change this as the module has settings
 *        to specify adding the js on every page
 */
function simple_dialog_attach_js(&$element, $every_page = FALSE) {
  $element['#attached']['library'][] = 'system/ui.dialog';
  $element['#attached']['js'][] = array(
    'data' => array(
      'simpleDialog' => array(
        'classes' => \Drupal::config('simple_dialog.settings')
          ->get('classes'),
        'defaults' => array(
          'settings' => \Drupal::config('simple_dialog.settings')
            ->get('defaults.settings'),
          'target_selector' => \Drupal::config('simple_dialog.settings')
            ->get('defaults.target_selector'),
          'title' => \Drupal::config('simple_dialog.settings')
            ->get('defaults.title'),
        ),
      ),
    ),
    'type' => 'setting',
  );
  $element['#attached']['js'][drupal_get_path('module', 'simple_dialog') . '/js/simple_dialog.js'] = array(
    'every_page' => $every_page,
  );
}

Functions

Namesort descending Description
simple_dialog_attach_js Adds the necessary js and libraries to make the dialog work. Really just adds the jquery.ui library and the simple dialog javscript file but if we need to add anything else down the road, at least it's abstracted into an api function
simple_dialog_help Implements hook_help().
simple_dialog_page_build Implements hook_page_build()
simple_dialog_permission Implements hook_permission().
simple_dialog_theme Implements hook_theme().
template_preprocess_simple_dialog_link Preprocesses variables for simple dialog links