Chado Field: get values list for fields storing their data in the base table of the bundle and not a foreign key.

tests/tripal_chado/fields/ChadoFieldGetValuesListTest.php

@@ -0,0 +1,145 @@
+<?php
+namespace Tests\tripal_chado\fields;
+
+use StatonLab\TripalTestSuite\DBTransaction;
+use StatonLab\TripalTestSuite\TripalTestCase;
+
+/**
+ * Test ChadoField->getValueList() Method.
+ */
+class ChadoFieldGetValuesListTest extends TripalTestCase {
+  // Uncomment to auto start and rollback db transactions per test method.
+  use DBTransaction;
+
+  // Stores a list of fields to be tested including their storage method and instance info.
+  private $field_list = NULL;
+
+  /**
+   * Test for fields based on columns in the base table.
+   *
+   * @group fields
+   * @group getValueList
+   */
+  public function testBaseTableColumns() {
+    include_once(drupal_get_path('tripal_chado', 'module') . '/includes/TripalFields/ChadoField.inc');
+
+    // Retrieve a list of fields to test.
+    // Note: this list is cached to improve performance.
+    $fields = $this->retrieveFieldList();
+
+    // Only iterate through fields that store their data in chado and
+    // specifically, where the field stores it's data in the base table of the bundle
+    // and is not a foreign key.
+    foreach ($fields['field_chado_storage']['base'] as $key => $info) {
+        $field_name = $info['field_name'];
+
+        // Construct the Field instance we want the values for.
+        // Specifying "ChadoField" here ensures we are only testing our 
+        // implementation of getValueList() and not the custom version for any
+        // given field.
+        // YOU SHOULD TEST CUSTOM FIELD IMPLEMENTATIONS SEPARATELY.
+        $instance = new \ChadoField($info['field_info'], $info['instance_info']);
+
+        // Retrieve the values.
+        // $values will be an array containing the distinct set of values for this field instance.
+        $values = $instance->getValueList(array('limit' => 5));
+
+        // Ensure we have values returned!
+        $this->assertTrue(
+          is_array($values), 
+          t(
+            'No values returned for @field_name (bundle: @bundle_name, bundle base table: @bundle_base_table, chado table: @chado_table, chado column: @chado_column).',
+            array(
+              '@field_name' => $field_name, 
+              '@bundle_name' => $info['bundle_name'], 
+              '@bundle_base_table' => $info['bundle_base_table'], 
+              '@chado_table' => $info['instance_info']['settings']['chado_table'], 
+              '@chado_column' => $info['instance_info']['settings']['chado_column'],
+            )
+          )
+        );
+
+      // Ensure there are no more then 5 as specified in the limit above.
+      $this->assertLessThanOrEqual(5, sizeof($values),
+        t('Returned too many results for @field_name.', array('@field_name' => $field_name)));
+
+    }
+  }
+
+  /**
+   * Returns a list of Fields sorted by their backend, etc. for use in tests.
+   */
+  private function retrieveFieldList() {
+    if ($this->field_list === NULL) {
+
+      $this->field_list = array();
+
+      $bundles = field_info_instances('TripalEntity');
+      foreach($bundles as $bundle_name => $fields) {
+
+        $bundle = tripal_load_bundle_entity(array('name'=> $bundle_name));
+
+        foreach ($fields as $field_name => $instance_info) {
+          $bundle_base_table = $base_schema = NULL;
+          
+          // Load the field info.
+          $field_info = field_info_field($field_name);
+
+          $storage = $field_info['storage']['type'];
+
+          // If this field stores it's data in chado...
+          // Determine the relationship between this field and the bundle base table.
+          $rel = NULL;
+          if ($storage == 'field_chado_storage') {
+
+            // We need to know the table this field stores it's data in.
+            $bundle_base_table = $bundle->data_table;
+            // and the schema for that table.
+            $base_schema = chado_get_schema($bundle_base_table);
+            // and the table this field stores it's data in.
+            $field_table = $instance_info['settings']['chado_table'];
+            $field_column = $instance_info['settings']['chado_column'];
+
+            // By default we simply assume there is some relationship.
+            $rel = 'referring';
+            // If the field and bundle store their data in the same table
+            // then it's either a "base" or "foreign key" relationship
+            // based on the schema.
+            if ($bundle_base_table == $field_table) {
+
+              // We assume it's not a foreign key...
+              $rel = 'base';
+              // and then check the schema to see if we're wrong :-)
+              foreach ($base_schema['foreign keys'] as $schema_info) {
+                if (isset($schema_info['columns'][ $field_column ])) { $rel = 'foreign key'; }
+              }
+            }
+          }
+         
+          $info = array(
+            'field_name' => $field_name,
+            'bundle_name' => $bundle_name,
+            'bundle' => $bundle,
+            'bundle_base_table' => $bundle_base_table,
+            'base_schema' => $base_schema,
+            'field_info' => $field_info,
+            'instance_info' => $instance_info,
+          );
+
+          $key = $bundle_name . '--' . $field_name;
+
+          if ($rel) {
+            $this->field_list[$storage][$rel][$key] = $info;
+          }
+          else {
+            $this->field_list[$storage][$key] = $info;
+          }
+
+        }
+      }
+    }
+
+    return $this->field_list;
+  }
+
+}

tripal/includes/TripalFields/TripalField.inc

@@ -745,4 +745,25 @@ class TripalField {
   public function queryOrder($query, $order) {
 
   }
+
+  /**
+   * Used to retrieve a distinct list of values already used for the current field instance.
+   *
+   * @param $keyword
+   *   A string option used to filter the distinct list. This is used when creating an
+   *   autocomplete. For all distinct values, set this to NULL.
+   * @param $options
+   *   An array where options for how to generate this list can be specified. 
+   *   Supported options include:
+   *     - limit: how many results to limit to (Default: 25)
+   *     - label_string: a string with tokens that should be used to generate the
+   *         human-readable values in the returned list.
+   *
+   * @return
+   *   An array of values.
+   */
+  public function getValueList($options = array(), $keyword = NULL) {
+  
+  }
+
 }

tripal_chado/includes/TripalFields/ChadoField.inc

@@ -149,6 +149,183 @@ class ChadoField extends TripalField {
     }
   }
 
+  /**
+   * Used to retrieve a distinct list of values already used for the current field instance.
+   *
+   * @param $keyword
+   *   A string option used to filter the distinct list. This is used when creating an
+   *   autocomplete. For all distinct values, set this to NULL.
+   * @param $options
+   *   An array where options for how to generate this list can be specified. 
+   *   Supported options include:
+   *     - limit: how many results to limit to (Default: 25)
+   *     - label_string: a string with tokens that should be used to generate the
+   *         human-readable values in the returned list.
+   *
+   * The following example shows you how to pull all the value list for a specific instance 
+   * of a field.
+   * @code
+      // In this example we want the values for the obi__organism field
+      // attached to the Tripal Content Type with a machine name of bio_data_17:
+      $field_name = 'obi__organism';
+      $bundle_name = 'bio_data_17';
+
+      // The following two calls get information about the field we want the values for.
+      $field_info = field_info_field($field_name);
+      $instance_info = field_info_instance('TripalEntity', $field_name, $bundle_name);
+      // Construct the Field instance we want the values for.
+      $instance = new ChadoField($field_info, $instance_info);
+
+      // Retrieve the values.
+      // $values will be an array containing the distinct set of values for this field instance.
+      $values = $instance->getValueList();
+   * @endcode
+   *
+   * @return
+   *   An array of values.
+   */
+  public function getValueList($options = array(), $keyword = NULL) {
+    $values = array();
+
+    // Set some defaults.
+    $options['limit'] = (isset($options['limit'])) ? $options['limit'] : 25;
+    $options['label_string'] = (isset($options['label_string'])) ? $options['label_string'] : '';
+
+    // Make sure we know the chado table and column.
+    // If not, we can't give them a list *shrugs*.
+    if (!isset($this->instance['settings']['chado_table']) OR !isset($this->instance['settings']['chado_column'])) {
+      tripal_report_error(
+        'TripalField',
+        TRIPAL_WARNING,
+        'Values List: Unable to generate a values list for %field_name since we don\'t know it\'s chado table/column.',
+        array('%field_name' => $this->instance['field_name'])
+      );
+      return FALSE;
+    }
+
+    // First get some important info about the chado table.column this field is attached to.
+    $chado_table = $this->instance['settings']['chado_table'];
+    $chado_column = $this->instance['settings']['chado_column'];
+    $base_table = $this->instance['settings']['base_table'];
+    $bschema = chado_get_schema($base_table);
+
+    // Now build the distinct query.
+    if ($chado_table == $base_table) {
+
+      // Is the current column a foreign key to another table?
+      $is_fk = FALSE;
+      $fk_table = $fk_column = NULL;
+      foreach ($bschema['foreign keys'] as $k => $v) {
+        if (isset($v['columns'][$chado_column])) {
+          $is_fk = TRUE;
+          $fk_table = $v['table'];
+          $fk_column = $v['columns'][$chado_column];
+        }
+      }
+
+      // Check if this column is a foreign key to another one.
+      // If so we would like to travel through the relationship
+      // to capture a better human-readable option.
+      if ($is_fk) {
+/*
+    dpm(array(
+      'chado table' => $chado_table,
+      'chado column' => $chado_column,
+      'base table' => $base_table,
+      'base schema' => $bschema,
+      'Is foreign key?' => $is_fk,
+      'Foreign Table' => $fk_table,
+      'Foreign column' => $fk_column,
+    ), 'info');
+*/
+        // Determine the query.
+        $sql = "SELECT base.$chado_column as id, fk.*
+                FROM {".$chado_table."} base
+                LEFT JOIN {".$fk_table."} fk ON base.$chado_column=fk.$fk_column
+                GROUP BY base.$chado_column, fk.$fk_column
+                LIMIT ".$options['limit'];
+
+        // Choose a default label string, if needed.
+        if (empty($options['label_string'])) {
+          $fkschema = chado_get_schema($fk_table);
+          if (isset($fkschema['fields']['name'])) {
+            $options['label_string'] = '[name]';
+          }
+          elseif (isset($fkschema['fields']['uniquename'])) {
+            $options['label_string'] = '[uniquename]';
+          }
+          elseif ($fk_table == 'organism') {
+            $options['label_string'] = '[genus] [species]';
+          }
+          else {
+            tripal_report_error(
+              'TripalField',
+              TRIPAL_WARNING,
+              'Values List: Unable to generate a default human-readable label for %field_name since there is no name/uniquename column. Please set the options[label_string].',
+              array('%field_name' => $this->instance['field_name'])
+            );
+            return FALSE;
+          }
+        }
+      }
+      // Not a foreign key, so just make the key and value from the base table.
+      else {
+        $sql = "SELECT $chado_column as id, $chado_column
+                FROM {".$chado_table."} base
+                GROUP BY $chado_column
+                LIMIT ".$options['limit'];
+
+        // Choose a default label string, if needed.
+        if (empty($options['label_string'])) {
+          $options['label_string'] = '[' . $chado_column . ']';
+        }
+      }
+    }
+    else {
+      tripal_report_error(
+        'TripalField',
+        TRIPAL_WARNING,
+        'Unable to retrieve a values list for %field_name since it is not a direct column in %base',
+        array('%field_name' => $this->instance['field_name'], '%base' => $base_table)
+      );
+      return FALSE;
+    }
+
+/*
+    dpm(array(
+      'chado table' => $chado_table,
+      'chado column' => $chado_column,
+      'base table' => $base_table,
+      'base schema' => $bschema,
+      'Is foreign key?' => $is_fk,
+      'Foreign Table' => $fk_table,
+      'Foreign column' => $fk_column,
+    ), 'info');
+*/
+    $results = chado_query($sql);
+
+    // Pre-process the label string for better performance.
+    // Each token is enclosed in square brackets and should be the name of a chado column.
+    preg_match_all('/\[(\w+)\]/', $options['label_string'], $matches);
+    $tokens = $matches[1];
+
+    foreach ($results as $r) {
+      // Determine the label using the label_string option.
+      $label = $options['label_string'];
+      $replace = array();
+      foreach ($tokens as $column) {
+        if (isset($r->{$column})) {
+          $replace[ "[$column]" ] = $r->{$column};
+        }
+      }
+
+      // Set the value.
+      $values[$r->id] = strtr($options['label_string'], $replace);
+    }
+
+    return $values;
+  }
+
   /**
    * @see TripalField::instanceSettingsForm()
    */