Provides a form for adding to BASE_dbxref and dbxref tables

Parameters

$form: The Drupal form array into which the dbxref elements will be added

$form_state: The corresponding form_state array for the form

$details: An array defining details needed by this form. Required Keys are:

• linking_table: the name of the dbxref linking table (ie: feature_dbxref)
• base_foreign_key: the name of the foreign key linking this table to the non-dbxref table (ie: feature_id)
• base_key_value: the value of the base_foreign_key for the current form (ie: 999 if the feature_id=999)

Optional keys include:

• fieldset_title: the non-translated title for this fieldset
• additional_instructions: a non-translated string providing additional instructions
• select_options: must be an array where the [key] is a valid db_id and the [value] is the human-readable name of the option. This includes all databases in the chado db table by default

Related topics

File

tripal_core/api/tripal_core.chado_nodes.dbxrefs.api.inc, line 125

API to manage the chado _dbxref table for various Tripal Node Types

Code

function chado_add_node_form_dbxrefs(&$form, &$form_state, $details) {

  // Set defaults for optional fields
  $details['fieldset_title'] = 'External References';
  $details['additional_instructions'] = '';

  // Get the list of databases to display in the dropdown.
  if (isset($details['select_options'])) {
    // the callee has provided a list
    $db_options = $details['select_options'];
  }
  else {
    // get the list of databases from the db table
    $db_options = array(0 => 'Select a Database');
    $options = array('order_by' => array('name' => 'ASC'));
    $select = chado_select_record('db', array('db_id', 'name'), array(), $options);
    foreach ($select as $db) {
      $db_options[$db->db_id] = $db->name;
    }
  }

  // Determine the node type using the name of the foreign key.
  $details['nodetype'] = str_replace('_id', '', $details['base_foreign_key']);

  // Tell tripal administrators how to add terms to the property types drop down.
  $importance = (empty($db_options)) ? TRIPAL_WARNING : TRIPAL_INFO;
  $tripal_message = tripal_set_message(
  t('To add databases to the drop down list, you need to <a href="@dblink">add
      an external database reference</a>.', 
  array(
    '@dblink' => url('admin/tripal/chado/tripal_db/add')
  )
  ), 
  $importance, 
  array('return_html' => TRUE)
  );

  // Group all of the chado node api fieldsets into vertical tabs.
  $form['chado_node_api'] = array(
    '#type' => 'vertical_tabs',
    '#attached' => array(
      'css' => array(
        'chado-node-api' => drupal_get_path('module', 'tripal_core') . '/theme/css/chado_node_api.css',
      ),
    ),
  );

  // the fieldset of the dbxref elements
  $instructions = 'To add an external reference, select the database you want to reference from the 
    drop-down below. Then enter the name/accession (as it is shown in the external database) of this 
    particular %nodetype into the text box before clicking "Add". The version can be used to 
    indicate the version of the external database or the version of the reference 
    depending upon what is available. To remove incorrect references, click the 
    "Remove" button. Note: you cannot edit previously added references but instead 
    need to remove and re-add them.';
  $form['addtl_dbxrefs'] = array(
    '#type' => 'fieldset',
    '#title' => t($details['fieldset_title']),
    '#description' => t('<p><strong>Indicate that this %nodetype either originates from 
      or is present in another database.</strong></p><p>' . $instructions . $details['additional_instructions'] . '</p>', 
    array('%nodetype' => $details['nodetype'])),
    '#collapsible' => TRUE,
    '#collapsed' => TRUE,
    '#group' => 'chado_node_api',
    '#weight' => 9,
    '#attributes' => array('class' => array('chado-node-api', 'dbxrefs')),
    '#attached' => array(
      'js' => array(
        'chado-node-api-vertical-tabs' => drupal_get_path('module', 'tripal_core') . '/theme/js/chadoNodeApi_updateVerticalTabSummary.js',
      ),
    ),
  );

  // this form element is a tree, so that we don't puke all of the values into then node variable
  // it is set as a tree, and keeps them in the $form_state['values']['dbxref_table'] heading.
  $form['addtl_dbxrefs']['dbxref_table'] = array(
    '#type' => 'markup',
    '#tree' => TRUE,
    '#prefix' => '<div id="tripal-generic-edit-addtl_dbxrefs-table">',
    '#suffix' => '</div>',
    '#theme' => 'chado_node_additional_dbxrefs_form_table'
  );

  // We need to provide feedback to the user that changes made
  // are not saved until the node is saved.
  $form['addtl_dbxrefs']['dbxref_table']['save_warning'] = array(
    '#type' => 'markup',
    '#prefix' => '<div id="dbxref-save-warning" class="messages warning" style="display:none;">',
    '#suffix' => '</div>',
    '#markup' => '* The changes to these references will not be saved until the "Save" button at the bottom of this form is clicked. <span class="specific-changes"></span>',
    '#attached' => array(
      'js' => array(
        'chado-node-api-unsaved' => drupal_get_path('module', 'tripal_core') . '/theme/js/chadoNodeApi_unsavedNotify.js',
      ),
    ),
  );

  /* DBxrefs can come to us in two ways:
   *
   * 1) In the form state in the $form_state['chado_additional_dbxrefs']. Data is in this field
   *    when an AJAX call updates the form state or a validation error.
   *
   * 2) Directly from the database if the record already has dbxref's associated.  This
   *    data is only used the first time the form is loaded. On AJAX calls or validation
   *    errors the fields on the form are populated from the $form_state['chado_additional_dbxrefs']
   *    entry.
   */
  if (isset($form_state['chado_additional_dbxrefs'])) {
    $existing_dbxrefs = $form_state['chado_additional_dbxrefs'];
  }
  else {
    $existing_dbxrefs = chado_query(
    "SELECT
         db.name as db_name, 
         db.db_id as db_id,
         dbxref.dbxref_id, 
         dbxref.accession as accession,
         dbxref.description as description, 
         dbxref.version
       FROM {dbxref} dbxref
         LEFT JOIN {db} db ON db.db_id = dbxref.db_id
         LEFT JOIN {" . $details['linking_table'] . "} linking_table ON linking_table.dbxref_id = dbxref.dbxref_id
       WHERE linking_table." . $details['base_foreign_key'] . "= :base_key_value
       ORDER BY db.name ASC, dbxref.version ASC", 
    array(':base_key_value' => $details['base_key_value'])
    );
  }
  /* The format of the $existing_dbxref's array is either:
   *
   * From the chado_additional_dbxrefs array:
   * $form_state['chado_additional_dbxrefs'] = array(
   *   '[db_id]-[version]' => array(
   *     'db_id' => [the db.db_id value]
   *     'db_name' => [the db.name value]
   *     'dbxref_id' => [the dbxref.dbxref_id value, or temporary value if it doesn't yet exists],
   *     'version' => [the dbxref.version value],
   *     'accession' => [the dbxref.accession value],
   *   ),
   * );
   *
   * OR
   * Populated from the database:
   * $existing_dbxref = array(
   *   0 => array(
   *     'dbxref_id' => [the dbxref.dbxref_id value],
   *     'db_name' => [the db.name value],
   *     'db_id' => [the db.db_id value],
   *     'accession' => [the dbxref.accession value],
   *     'description' => [the dbxref.description value],
   *     'version' => [the dbxref.versiion value],
   *   ),
   * );
   *
   * NOTE: The main difference is the key
   *
   * Loop on the array elements of the $existing_dbxrefs array and add
   * an element to the form for each one.
   */
  $num_dbxrefs = 0;
  foreach ($existing_dbxrefs as $dbxref) {
    if (array_key_exists($dbxref->db_id, $db_options)) {
      $num_dbxrefs++;

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id]['#type'] = 'markup';
      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id]['#value'] = '';

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['#type'] = 'markup';
      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['#value'] = '';
      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['#attributes'] = array(
        'class' => array('dbxref', 'saved')
      );

      // Determine whether this dbxref is unsaved or not.
      // We can tell this by looking at the dbxref_id: if it's not
      // saved yet we will have entered a TEMP###.
      if (preg_match('/^TEMP/', $dbxref->dbxref_id)) {
        $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['#attributes'] = array(
          'class' => array('dbxref', 'unsaved')
        );
      }

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['db_id'] = array(
        '#type' => 'hidden',
        '#value' => $dbxref->db_id
      );

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['accession'] = array(
        '#type' => 'hidden',
        '#value' => $dbxref->accession
      );

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['version'] = array(
        '#type' => 'hidden',
        '#value' => $dbxref->version,
      );

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['dbxref_id'] = array(
        '#type' => 'hidden',
        '#value' => $dbxref->dbxref_id
      );

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['db'] = array(
        '#type' => 'markup',
        '#markup' => $dbxref->db_name,
        '#prefix' => '<span class="row-unsaved-warning"></span>'
      );

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['dbxref_version'] = array(
        '#type' => 'markup',
        '#markup' => $dbxref->version,
      );

      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['dbxref_accession'] = array(
        '#type' => 'markup',
        '#markup' => $dbxref->accession
      );
      // remove button
      $form['addtl_dbxrefs']['dbxref_table'][$dbxref->db_id][$dbxref->dbxref_id]['dbxref_action'] = array(
        '#type' => 'submit',
        '#value' => t('Remove'),
        '#name' => "dbxrefs_remove-" . $dbxref->db_id . '-' . $dbxref->dbxref_id,
        '#ajax' => array(
          'callback' => "chado_add_node_form_subtable_ajax_update",
          'wrapper' => 'tripal-generic-edit-addtl_dbxrefs-table',
          'effect' => 'fade',
          'method' => 'replace',
          'prevent' => 'click'
        ),
        // When this button is clicked, the form will be validated and submitted.
        // Therefore, we set custom submit and validate functions to override the
        // default node form submit.  In the validate function we validate only the
        // additional dbxref fields and in the submit we remove the indicated dbxref
        // from the chado_additional_dbxrefs array. In order to keep validate errors
        // from the node form validate and Drupal required errors for non-dbxref fields
        // preventing the user from removing dbxrefs we set the #limit_validation_errors below
        '#validate' => array('chado_add_node_form_subtables_remove_button_validate'),
        '#submit' => array('chado_add_node_form_subtables_remove_button_submit'),
        // Limit the validation of the form upon clicking this button to the dbxref_table tree
        // No other fields will be validated (ie: no fields from the main form or any other api
        // added form).
        '#limit_validation_errors' => array(
          array('dbxref_table') // Validate all fields within $form_state['values']['dbxref_table']
        )
      );
    }
  }

  // Quickly add a hidden field stating how many dbxrefs are currently added.
  $form['addtl_dbxrefs']['num_dbxrefs'] = array(
    '#type' => 'hidden',
    '#value' => $num_dbxrefs,
    '#attributes' => array('class' => 'num-dbxrefs')
  );

  // Form elements for adding a new dbxref
  //---------------------------------------------
  $form['addtl_dbxrefs']['dbxref_table']['new'] = array(
    '#type' => 'markup',
    '#prefix' => '<span class="addtl-dbxrefs-add-new-dbxref">',
    '#suffix' => '</span>'
  );

  // add in the existing databases
  $form['addtl_dbxrefs']['dbxref_table']['new']['db'] = array(
    '#type' => 'select',
    '#options' => $db_options,
  );

  $form['addtl_dbxrefs']['dbxref_table']['new']['dbxref_accession'] = array(
    '#type' => 'textfield',
  );

  $form['addtl_dbxrefs']['dbxref_table']['new']['dbxref_version'] = array(
    '#type' => 'textfield',
    '#size' => 10,
  );

  // add button
  $form['addtl_dbxrefs']['dbxref_table']['new']['dbxref_action'] = array(
    '#type' => 'submit',
    '#value' => t('Add'),
    '#name' => "dbxrefs-add",
    '#ajax' => array(
      'callback' => "chado_add_node_form_subtable_ajax_update",
      'wrapper' => 'tripal-generic-edit-addtl_dbxrefs-table',
      'effect' => 'fade',
      'method' => 'replace',
      'prevent' => 'click'
    ),
    // When this button is clicked, the form will be validated and submitted.
    // Therefore, we set custom submit and validate functions to override the
    // default node form submit.  In the validate function we validate only the
    // additional dbxref fields and in the submit we add them to the chado_additional_dbxrefs
    // array. In order to keep validate errors from the node form validate and Drupal
    // required errors for non-dbxref fields preventing the user from adding dbxrefs we
    // set the #limit_validation_errors below
    '#validate' => array('chado_add_node_form_subtables_add_button_validate'),
    '#submit' => array('chado_add_node_form_subtables_add_button_submit'),
    // Limit the validation of the form upon clicking this button to the dbxref_table tree
    // No other fields will be validated (ie: no fields from the main form or any other api
    // added form).
    '#limit_validation_errors' => array(
      array('dbxref_table') // Validate all fields within $form_state['values']['dbxref_table']
    )
  );

  $form['addtl_dbxrefs']['admin_message'] = array(
    '#type' => 'markup',
    '#markup' => $tripal_message
  );
}