loft_data_grids.module in Loft Data Grids 7

Base module file for loft_data_grids

loft_data_grids Loft Data Grids

File

loft_data_grids.module

<?php

/**
 * @file
 * Base module file for loft_data_grids
 *
 * @defgroup loft_data_grids Loft Data Grids
 * @{
 */

/**
 * Return information about external libraries.
 *
 * @return
 *   An associative array whose keys are internal names of libraries and whose
 *   values are describing each library. Each key is the directory name below
 *   the 'libraries' directory, in which the library may be found. Each value is
 *   an associative array containing:
 *   - name: The official, human-readable name of the library.
 *   - vendor url: The URL of the homepage of the library.
 *   - download url: The URL of a web page on which the library can be obtained.
 *   - path: (optional) A relative path from the directory of the library to the
 *     actual library. Only required if the extracted download package contains
 *     the actual library files in a sub-directory.
 *   - library path: (optional) The absolute path to the library directory. This
 *     should not be declared normally, as it is automatically detected, to
 *     allow for multiple possible library locations. A valid use-case is an
 *     external library, in which case the full URL to the library should be
 *     specified here.
 *   - version: (optional) The version of the library. This should not be
 *     declared normally, as it is automatically detected (see 'version
 *     callback' below) to allow for version changes of libraries without code
 *     changes of implementing modules and to support different versions of a
 *     library simultaneously (though only one version can be installed per
 *     site). A valid use-case is an external library whose version cannot be
 *     determined programatically.
 *   - version callback: (optional) The name of a function that detects and
 *     returns the full version string of the library. The first argument is
 *     always $library, an array containing all library information as described
 *     here. There are two ways to declare the version callback's additional
 *     arguments, either as a single $options parameter or as multiple
 *     parameters, which correspond to the two ways to specify the argument
 *     values (see 'version arguments'). Defaults to libraries_get_version().
 *   - version arguments: A list of arguments to pass to the version callback.
 *     Version arguments can be declared either as an associative array whose
 *     keys are the argument names or as an indexed array without specifying
 *     keys. If declared as an associative array, the arguments get passed to
 *     the version callback as a single $options parameter whose keys are the
 *     argument names (i.e. $options is identical to the specified array). If
 *     declared as an indexed array, the array values get passed to the version
 *     callback as seperate arguments in the order they were declared. The
 *     default version callback libraries_get_version() expects a single,
 *     associative array with named keys:
 *     - file: The filename to parse for the version, relative to the library
 *       path. For example: 'docs/changelog.txt'.
 *     - pattern: A string containing a regular expression (PCRE) to match the
 *       library version. For example: '@version\s+([0-9a-zA-Z\.-]+)@'. Note
 *       that the returned version is not the match of the entire pattern (i.e.
 *       '@version 1.2.3' in the above example) but the match of the first
 *       sub-pattern (i.e. '1.2.3' in the above example).
 *     - lines: (optional) The maximum number of lines to search the pattern in.
 *       Defaults to 20.
 *     - cols: (optional) The maximum number of characters per line to take into
 *       account. Defaults to 200. In case of minified or compressed files, this
 *       prevents reading the entire file into memory.
 *   - files: An associative array of library files to load. Supported keys are:
 *     - js: A list of JavaScript files to load, using the same syntax as Drupal
 *       core's hook_library().
 *     - css: A list of CSS files to load, using the same syntax as Drupal
 *       core's hook_library().
 *     - php: A list of PHP files to load.
 *   - dependencies: An array of libraries this library depends on. Similar to
 *     declaring module dependencies, the dependency declaration may contain
 *     information on the supported version. Examples of supported declarations:
 *     @code
 *     $libraries['dependencies'] = array(
 *       // Load the 'example' library, regardless of the version available:
 *       'example',
 *       // Only load the 'example' library, if version 1.2 is available:
 *       'example (1.2)',
 *       // Only load a version later than 1.3-beta2 of the 'example' library:
 *       'example (>1.3-beta2)'
 *       // Only load a version equal to or later than 1.3-beta3:
 *       'example (>=1.3-beta3)',
 *       // Only load a version earlier than 1.5:
 *       'example (<1.5)',
 *       // Only load a version equal to or earlier than 1.4:
 *       'example (<=1.4)',
 *       // Combinations of the above are allowed as well:
 *       'example (>=1.3-beta2, <1.5)',
 *     );
 *     @endcode
 *   - variants: (optional) An associative array of available library variants.
 *     For example, the top-level 'files' property may refer to a default
 *     variant that is compressed. If the library also ships with a minified and
 *     uncompressed/source variant, those can be defined here. Each key should
 *     describe the variant type, e.g. 'minified' or 'source'. Each value is an
 *     associative array of top-level properties that are entirely overridden by
 *     the variant, most often just 'files'. Additionally, each variant can
 *     contain following properties:
 *     - variant callback: (optional) The name of a function that detects the
 *       variant and returns TRUE or FALSE, depending on whether the variant is
 *       available or not. The first argument is always $library, an array
 *       containing all library information as described here. The second
 *       argument is always a string containing the variant name. There are two
 *       ways to declare the variant callback's additinal arguments, either as a
 *       single $options parameter or as multiple parameters, which correspond
 *       to the two ways to specify the argument values (see 'variant
 *       arguments'). If ommitted, the variant is expected to always be
 *       available.
 *     - variant arguments: A list of arguments to pass to the variant callback.
 *       Variant arguments can be declared either as an associative array whose
 *       keys are the argument names or as an indexed array without specifying
 *       keys. If declared as an associative array, the arguments get passed to
 *       the variant callback as a single $options parameter whose keys are the
 *       argument names (i.e. $options is identical to the specified array). If
 *       declared as an indexed array, the array values get passed to the
 *       variant callback as seperate arguments in the order they were declared.
 *     Variants can be version-specific (see 'versions').
 *   - versions: (optional) An associative array of supported library versions.
 *     Naturally, libraries evolve over time and so do their APIs. In case a
 *     library changes between versions, different 'files' may need to be
 *     loaded, different 'variants' may become available, or Drupal modules need
 *     to load different integration files adapted to the new version. Each key
 *     is a version *string* (PHP does not support floats as keys). Each value
 *     is an associative array of top-level properties that are entirely
 *     overridden by the version.
 *   - integration files: (optional) An associative array whose keys are module
 *     names and whose values are sets of files to load for the module, using
 *     the same notion as the top-level 'files' property. Each specified file
 *     should contain the path to the file relative to the module it belongs to.
 *   - callbacks: An associative array whose keys are callback groups and whose
 *     values are arrays of callbacks to apply to the library in that group.
 *     Each callback receives the following arguments:
 *     - $library: An array of library information belonging to the top-level
 *       library, a specific version, a specific variant or a specific variant
 *       of a specific version. Because library information such as the 'files'
 *       property (see above) can be declared in all these different locations
 *       of the library array, but a callback may have to act on all these
 *       different parts of the library, it is called recursively for each
 *       library with a certain part of the libraries array passed as $library
 *       each time.
 *     - $version: If the $library array belongs to a certain version (see
 *       above), a string containing the version. This argument may be empty, so
 *       NULL should be specified as the default value.
 *     - $variant: If the $library array belongs to a certain variant (see
 *       above), a string containing the variant name. This argument may be
 *       empty, so NULL should be specified as the default value.
 *     Valid callback groups are:
 *     - info: Callbacks registered in this group are applied after the library
 *       information has been retrieved via hook_libraries_info() or info files.
 *     - pre-detect: Callbacks registered in this group are applied after the
 *       library path has been determined and before the version callback is
 *       invoked. At this point the following additional information is available:
 *       - $library['library path']: The path on the file system to the library.
 *     - post-detect: Callbacks registered in this group are applied after the
 *       library has been successfully detected. At this point the library
 *       contains the version-specific information, if specified, and following
 *       additional information is available:
 *       - $library['installed']: A boolean indicating whether the library is
 *         installed or not.
 *       - $library['version']: If it could be detected, a string containing the
 *         version of the library.
 *       - $library['variants'][$variant]['installed']: For each specified
 *         variant, a boolean indicating whether the variant is installed or
 *         not.
 *       Note that in this group the 'versions' property is no longer available.
 *     - pre-load: Callbacks registered in this group are applied directly
 *       before this library is loaded. At this point the library contains
 *       variant-specific information, if specified. Note that in this group the
 *       'variants' property is no longer available.
 *     - post-load: Callbacks registered in this group are applied directly
 *       after this library is loaded. At this point, the library contains a
 *       'loaded' key, which contains the number of files that were loaded.
 *   Additional top-level properties can be registered as needed.
 *
 * @see hook_library()
 */
function loft_data_grids_libraries_info() {

  // Expected to be extracted into 'sites/all/libraries/loft_data_grids'.
  $libraries['loft_data_grids'] = array(
    'name' => 'Loft Data Grids',
    'vendor url' => 'http://www.intheloftstudios.com',
    'download url' => 'https://github.com/aklump/loft_data_grids',
    'version arguments' => array(
      'file' => 'loft_data_grids.info',
      'pattern' => '/version ?= ?([\\d.]+)/',
      'lines' => 3,
    ),
    'files' => array(
      'php' => array(
        'classes/ExportData.php',
        'classes/Exporter.php',
        'classes/HTMLExporter.php',
      ),
    ),
    'callbacks' => array(
      'info' => array(),
      'pre-detect' => array(),
      'post-detect' => array(),
      'pre-load' => array(),
      'post-load' => array(),
    ),
  );
  return $libraries;
}

/**
 * Return an array of all possible Exporter classnames
 *
 * @return array
 */
function _loft_data_get_possible_exporters() {
  $classes = array(
    'CSVExporter',
    'TabTextExporter',
    'XLSXExporter',
    'FlatTextExporter',
    'XMLExporter',
    'JSONExporter',
    'YAMLExporter',
    'TextListExporter',
    'MarkdownExporter',
  );
  foreach ($classes as $key => $class) {
    if (!class_exists($class)) {
      unset($classes[$key]);
    }
  }
  return $classes;
}

/**
 * Return info about the export formats available
 *
 * @param type $string
 *   description
 *
 * @return array
 *   tbd
 */
function loft_data_grids_export_info() {
  $info =& drupal_static(__FUNCTION__, array());
  if (empty($info) && ($library = libraries_load('loft_data_grids')) && $library['loaded']) {
    if (module_exists('phpexcel')) {
      libraries_load('PHPExcel');
    }
    $info = array();
    $data = new ExportData();
    $classnames = _loft_data_get_possible_exporters();
    $classes = array();
    foreach ($classnames as $classname) {
      $object = loft_data_grids_exporter($data, $classname);
      if ($object->dependencies) {
        $info[$classname] = array(
          'id' => $classname,
        ) + $object
          ->getInfo();
      }
    }
    drupal_alter('loft_data_grids_export_info', $info);
  }
  return $info;
}

/**
 * Instantiate a new ExportData object
 *
 * @param mixed $page_id
 *   (Optional) Defaults to 0.
 */
function loft_data_grids_export_data($page_id = 0, $class = 'ExportData') {
  libraries_load('loft_data_grids');
  if (class_exists($class)) {
    return new $class($page_id);
  }
  return FALSE;
}

/**
* Instantiate a new ExportData object
*
* This wrapper should be used for compatability issues with multiple library
  locations such as PHPExcel
*
* @param ExportDataInterface $data
* @param string $class
*   The name of any of the various Exporter classes
* @param string $filename
*   (Optional) Defaults to ''.
*/
function loft_data_grids_exporter(ExportDataInterface $data, $class, $filename = '') {
  libraries_load('loft_data_grids');
  if (class_exists($class)) {
    $object = new $class($data, $filename);

    // Support for PHPExcel through the drupal module rather than
    // loft_data_grids vendor directory
    if (!$object->dependencies && $class === 'XLSXExporter' && module_exists('phpexcel')) {
      libraries_load('PHPExcel');
    }
    return $object;
  }
  return FALSE;
}

Functions

Name	Description
loft_data_grids_exporter	Instantiate a new ExportData object
loft_data_grids_export_data	Instantiate a new ExportData object
loft_data_grids_export_info	Return info about the export formats available
loft_data_grids_libraries_info	Return information about external libraries.
_loft_data_get_possible_exporters	Return an array of all possible Exporter classnames