<?php

/**
 * @file
 * The help module for Archibald.
 *
 * The Archibald Help module provides contextual information and help for
 * editors that manage LOM descriptions.
 */

/**
 * Implements hook_ctools_plugin_api().
 */
function archibald_help_ctools_plugin_api($module, $api) {
  if ($module == 'qtip' && $api == 'qtip_default') {
    return array(
      'version' => 1,
    );
  }
}

/**
 * Implements hook_help().
 *
 * Warning: this is actually an implementation on behalf of the Archibald
 * module, and not Archibald Help itself!
 */
function archibald_help($path, $arg) {
  switch ($path) {
    case 'admin/help#archibald':
      $output = '<h3>' . t("About") . '</h3>';
      $output .= '<p>' . t("Archibald is a tool for creating and maintaining LOM-CH <em>descriptions</em>. A LOM description is a set of meta-data that describes a learning resource. A learning resource could be a website, a mobile application, a video, etc. Finalized descriptions are then published to a <em>catalog</em>. This can be a <em>private</em> catalog (one only usable by certain institutions, known as <em>partners</em>), or the <em>national catalog</em>, which is available for all participating institutions.") . '</p>';
      $output .= '<p>' . t("<em>LOM-CH</em> is a superset of the international <em>LOM</em> standard (<em>Learning Object Metadata</em>). LOM-CH is mostly compatible with LOM, but introduces a few changes to adapt to the Swiss educational system(s). At this time, Archibald is compatible with the version 1.2 of the LOM-CH standard. More information about the LOM-CH standard can be found <a href='@link'>here</a>.", array(
        '@link' => 'http://biblio.educa.ch/de/gesamtarchitektur',
      )) . '</p>';
      $output .= '<p>' . t("<em>dsb</em> stands for <em>Digitale Schulbibliothek</em>, and represents the project of the <em>Swiss Digital School Library</em>. This project maintains a central repository of meta-data, describing educational content. This repository is known as the <em>National Catalog</em>. This National Catalog, in turn, can be accessed via a REST API, which is simple known as the <em>dsb REST API</em>. More information can be found <a href='@link'>here</a>.", array(
        '@link' => 'http://biblio.educa.ch/de/gesamtarchitektur',
      )) . '</p>';
      $output .= '<h3>' . t("Uses") . '</h3>';
      $output .= '<dl>';
      $output .= '<dt>' . t("Managing LOM-CH descriptions") . '</dt>';
      $output .= '<dd>' . t("Archibald provides a custom content type which represents a LOM-CH description. This content type can be revisioned, validated with the dsb REST API, translated, etc.") . '</dd>';
      $output .= '<dt>' . t("Managing VCards") . '</dt>';
      $output .= '<dd>' . t("Descriptions contain information about the institutions or people who participated in the elaboration of the educational resource (authors, publishers, etc), as well as the people who created the description itself (the <em>node</em> authors). These institutions or people are represented by VCards, which are custom entities. A VCard can be attached to Drupal user accounts. These VCards will then be used in the LOM-CH <em>metaMetadata.contribute</em> field. VCard entities can be managed <a href='@VCards'>here</a>.", array(
        '@VCards' => url('admin/archibald/vcard'),
      )) . '</dd>';
      $output .= '<dt>' . t("Managing Partners") . '</dt>';
      $output .= '<dd>' . t("Partners are institutions that can interact with the dsb REST API. Partners take responsibility for certain descriptions, which they publish in their own name. Archibald can manage several partner credentials at once, and assign descriptions to certain partners. When a finalized description is published, it will belong to this partner, and be marked as such in the catalog. Partners are custom entities, and can be managed <a href='@Partners'>here</a>.", array(
        '@Partners' => url('admin/archibald/partner'),
      )) . '</dd>';
      $output .= '</dl>';

      return $output;
  }
}

/**
 * Implements hook_form_FORM_ID_alter() for archibald_lomch_description_node_form.
 */
function archibald_help_form_archibald_lomch_description_node_form_alter(&$form, $form_state) {
  module_load_include('inc', 'archibald', 'includes/archibald.entities');

  // Add our CSS and JS.
  $path = drupal_get_path('module', 'archibald_help');
  $form['#attached']['css'][] = $path . '/css/archibald_help.node_form.css';
  $form['#attached']['js'][] = $path . '/js/archibald_help.node_form.js';

  foreach (array_keys(archibald_archibald_lomch_description_fields()) as $field_name) {
    _archibald_help_add_tooltip($form, $field_name);
  }

  // The title field is not part of the list. Handle this one ourselves.
  _archibald_help_add_tooltip($form, 'title_field', array(
    'help' => t("Insert a short title, which describes the resource in a distinct and accurate way. If the resource itself has a title, it should be used here.<br />Some examples:<ul><li>Inner-workings of a lock</li><li>Life in the Middle-Ages - castles</li></ul>"),
  ));
}

/**
 * Helper function to add a tooltip to a field.
 *
 * This function extracts information from
 * archibald_archibald_lomch_description_fields(), and adds help information
 * accordingly.
 *
 * @param array &$form
 *    The form object.
 * @param string $field_name
 *    The name of the field to add the tooltip to.
 * @param array $help_info
 *    (optional) If the field information provides no help text, or if this
 *    text is to be overridden, provide it here. Can have 2 keys:
 *    - label: (optional) The label to use for the tooltip. Defaults to the
 *      field label.
 *    - help: (required) The help text itself. Can contain HTML.
 */
function _archibald_help_add_tooltip(&$form, $field_name, $help_info = NULL) {
  module_load_include('inc', 'archibald', 'includes/archibald.entities');

  $field = $form[$field_name];
  if (empty($field)) {
    return;
  }

  $field_info = archibald_archibald_lomch_description_fields();
  $field_info = isset($field_info[$field_name]) ? $field_info[$field_name] : NULL;

  // Try to figure out where to place the tooltip. This varies based on the
  // field type, field settings, or even for specific field.
  if (!empty($field_info) && !empty($field_info['api_name'])) {
    // Fetch the help text, if necessary.
    if (!empty($field_info['api_help']) && empty($help_info)) {
      $help_info = $field_info['api_help'];
    }

    // Fetch the "API name", which represents the "path" to the field in
    // LOM, like "general.description". Some have multiple paths to cater
    // for multiple LOM variants. We handle LOM-CHv1.2.
    if (is_array($field_info['api_name'])) {
      $api_name = $field_info['api_name']['LOM-CHv1.2'];
    }
    else {
      $api_name = $field_info['api_name'];
    }

    // Add a help icon to the field label, containing the help text. If the
    // field is a multi-valued field, we must add it to the top-most parent.
    // If not, we must add it to the first occurrence, but some occurrences are
    // a bit special.
    if (
      preg_match('/(\[\]|\*)$/', $api_name) ||
      in_array($field_info['widget']['type'], array(
        'options_select',
        'options_buttons',
        'taxonomy_autocomplete',
      )) ||
      (
        in_array($field_info['widget']['type'], array(
          'text_textfield',
        )) &&
        $field_info['cardinality'] == FIELD_CARDINALITY_UNLIMITED
      )
    ) {
      $title = &$form[$field_name][$field['#language']]['#title'];
      $value = $form[$field_name][$field['#language']]['#title'];
    }
    elseif (in_array($field_info['widget']['type'], array(
      'archibald_lomch_filesize',
      'image_image',
      'range',
    ))) {
      $title = &$form[$field_name][$field['#language']][0]['#title'];
      $value = $form[$field_name][$field['#language']][0]['#title'];
    }
    else {
      $title = &$form[$field_name][$field['#language']][0]['value']['#title'];
      $value = $form[$field_name][$field['#language']][0]['value']['#title'];
    }
  }
  else {
    $title = &$form[$field_name][$field['#language']][0]['value']['#title'];
    $value = $form[$field_name][$field['#language']][0]['value']['#title'];
  }

  // Make sure we have a help info.
  if (empty($help_info)) {
    return;
  }

  $title .= '<span class="archibald-help-tooltip qtip-link"></span>';
  $title .= theme('qtip_form', array(
    'instance' => 'archibald_help',
    'title' => !empty($help_info['label']) ?
      $help_info['label'] :
      $value,
    'tooltip' => $help_info['help'],
  ));
}
