brush up base field

tripal_chado/includes/TripalFields/data__sequence_features/data__sequence_features.inc

@@ -2,83 +2,28 @@
 
 /**
  * @class
- * Purpose:
+ * Purpose: Follows the feature relationships of a given feature,
+ * and stores information about all child features.
  *
- * Data:
- * Assumptions:
  */
 class data__sequence_features extends ChadoField {
 
-  // --------------------------------------------------------------------------
-  //                     EDITABLE STATIC CONSTANTS
-  //
-  // The following constants SHOULD be set for each descendant class.  They are
-  // used by the static functions to provide information to Drupal about
-  // the field and it's default widget and formatter.
-  // --------------------------------------------------------------------------.
-  /**
-   * The default label for this field.
-   */
   public static $default_label = 'Child Features';
-
-  /**
-   * The default description for this field.
-   */
   public static $default_description = 'Gathers information about all subfeatures (mRNA, CDS, proteins) associated with a top-level feature (gene)';
-
-  /**
-   * The default widget for this field.
-   */
   public static $default_widget = 'data__sequence_features_widget';
-
-  /**
-   * The default formatter for this field.
-   */
   public static $default_formatter = 'data__sequence_features_formatter';
+  public static $module = 'tripal_chado';
 
-  // The module that manages this field.
-  // If no module manages the field (IE it's added via libraries)
-  /**
-   * Set this to 'tripal_chado'.
-   */
-  public static $module = 'tripal_manage_analyses';
-
-  // A list of global settings. These can be accessed within the
-  // globalSettingsForm.  When the globalSettingsForm is submitted then
-  // Drupal will automatically change these settings for all fields.
-  // Once instances exist for a field type then these settings cannot be.
-  /**
-   * Changed.
-   */
   public static $default_settings = array(
     'storage' => 'field_chado_storage',
-     // It is expected that all fields set a 'value' in the load() function.
-     // In many cases, the value may be an associative array of key/value pairs.
-     // In order for Tripal to provide context for all data, the keys should
-     // be a controlled vocabulary term (e.g. rdfs:type). Keys in the load()
-     // function that are supported by the query() function should be
-     // listed here.
     'searchable_keys' => array(),
   );
 
-  // Indicates the download formats for this field.  The list must be the.
-  /**
-   * Name of a child class of the TripalFieldDownloader.
-   */
-  public static $download_formatters = array(
-    'TripalTabDownloader',
-    'TripalCSVDownloader',
-  );
+//  public static $download_formatters = array(
+//    'TripalTabDownloader',
+//    'TripalCSVDownloader',
+//  );
 
-  // Provide a list of instance specific settings. These can be access within
-  // the instanceSettingsForm.  When the instanceSettingsForm is submitted
-  // then Drupal with automatically change these settings for the instance.
-  // It is recommended to put settings at the instance level whenever possible.
-  // If you override this variable in a child class be sure to replicate the
-  // term_name, term_vocab, term_accession and term_fixed keys as these are.
-  /**
-   * Required for all TripalFields.
-   */
   public static $default_instance_settings = array(
     // The DATABASE name, as it appears in chado.db.  This also builds the link-out url.  In most cases this will simply be the CV name.  In some cases (EDAM) this will be the SUBONTOLOGY.
     'term_vocabulary' => 'data',
@@ -103,20 +48,8 @@ class data__sequence_features extends ChadoField {
     'base_table' => '',
   );
 
-  // A boolean specifying that users should not be allowed to create
-  // fields and instances of this field type through the UI. Such
-  // fields can only be created programmatically with field_create_field()
-  /**
-   * And field_create_instance().
-   */
-  public static $no_ui = FALSE;
 
-  // A boolean specifying that the field will not contain any data. This
-  // should exclude the field from web services or downloads.  An example
-  // could be a quick search field that appears on the page that redirects.
-  /**
-   * The user but otherwise provides no data.
-   */
+  public static $no_ui = FALSE;
   public static $no_data = FALSE;
 
   /**
@@ -126,18 +59,16 @@ class data__sequence_features extends ChadoField {
    */
   public function load($entity) {
 
-    // ChadoFields automatically load the chado column specified in the
-    // default settings above. If that is all you need then you don't even
-    // need to implement this function. However, if you need to add any
-    // additional data to be used in the display, you should add it here.
     parent::load($entity);
-
     $field = get_class($this);
 
     $parent = $entity->chado_record->feature_id;
 
     $children = $this->findChildFeatures($parent);
-
+    if (empty($children)) {
+      unset($entity->{$field});
+      return;
+    }
     $i = 0;
     foreach ($children as $child_id => $child) {
       $entity->{$field}['und'][$i]['value'] = $child;
@@ -196,11 +127,12 @@ class data__sequence_features extends ChadoField {
       ->condition('object_id', $feature_id)
       ->execute()
       ->fetchAll();
+    chado_set_active($prev_db);
 
     foreach ($query as $child) {
       $child_id = $child->subject_id;
-
-      // Expand var on this.
+      // If any additional fields want to use this
+      // field's data, expand the desired table below.
       $feature = chado_generate_var('feature', ['feature_id' => $child_id]);
       $feature = chado_expand_var($feature, 'field', 'feature.residues');
       $feature = chado_expand_var($feature, 'table', 'featureloc');
@@ -214,7 +146,6 @@ class data__sequence_features extends ChadoField {
         $this_children[$child_id]['children'] = $grand_children;
       }
     }
-    chado_set_active($prev_db);
     return $this_children;
   }
 

tripal_chado/includes/TripalFields/data__sequence_features/data__sequence_features_formatter.inc

@@ -2,48 +2,44 @@
 
 /**
  * @class
- * Purpose:
+ * Purpose: Displays all child features recursively via a featureviewer drawing.
  *
  * Display:
  * Configuration:
  */
 class data__sequence_features_formatter extends ChadoFieldFormatter {
 
-  /**
-   * The default label for this field.
-   */
   public static $default_label = 'Transcript Information';
-
-  /**
-   * The list of field types for which this formatter is appropriate.
-   */
   public static $field_types = ['data__sequence_features'];
-
-  /**
-   * The list of default settings for this formatter.
-   */
   public static $default_settings = [
     'setting1' => 'default_value',
   ];
 
-
   /**
-   * Featureloc start rel to parent.
+   * Featureloc start relative to parent.
+   *
+   * @var int
    */
   private $parent_start;
 
   /**
    * Featureloc stop rel to parent.
+   *
+   * @var int
    */
   private $parent_stop;
 
   /**
    * Featureloc strand rel to parent.
+   *
+   * @var string
    */
   private $parent_strand;
 
   /**
    * Holds converted featureloc information for the feature viewer drawing.
+   *
+   * @var array
    */
   private $feature_coords;
 
@@ -61,7 +57,6 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
 
     // Get the settings.
     $settings = $display['settings'];
-
     $parent = $entity->chado_record->feature_id;
 
     drupal_add_js("https://cdn.rawgit.com/calipho-sib/feature-viewer/v1.0.0/dist/feature-viewer.bundle.js", [
@@ -76,21 +71,22 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
     $sequence = $entity->data__sequence['und'][0]['value'];
 
     if (!$sequence) {
-      // TODO: We cant draw without a sequence.
-      // Now what?
+      // We can't draw without a sequence unfortunately.
+      return;
     }
 
     $coordinates = $entity->data__sequence_coordinates['und'][0]['value'];
-
+    // Featureloc stores location relative to some parent feature, ie a contig.
+    // We want the drawing to be relative to the gene feature.
     $this->parent_start = $coordinates['local:fmin'];
     $this->parent_stop = $coordinates['local:fmax'];
     $this->parent_strand = $coordinates['data:0853'];
-
     $child_draw['residues'] = $sequence;
 
     foreach ($entity->{'data__sequence_features'}['und'] as $i => $data) {
+      // The direct child of the entity feature.
+      // If the entity is a gene, this is an mRNA/transcript.
       $child = $data['value'];
-
       $info = $child['info'];
       $name = $info->uniquename;
 
@@ -103,18 +99,17 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
             'collapsed',
           ],
         ],
-        // see: https://www.drupal.org/forum/support/module-development-and-code-questions/2012-02-07/drupal-render-fieldset-element
+        // JS to render collapsible fieldsets properly.
         '#attached' => ['js' => ['misc/collapse.js', 'misc/form.js']],
       ];
+      // The featureviewer drawing div.
       $element[$i]['drawing'] = [
         '#type' => 'item',
-        '#title' => t('Drawing'),
-        '#prefix' => '<div id="tripal_manage_expression_featureloc_viewer_' . $i . '">',
+        '#prefix' => '<div id="tripal_sequence_features_featureloc_viewer_' . $i . '">',
         '#suffix' => '</div>',
       ];
 
       $rows = $this->buildChildTable($child);
-
       $this->build_featureviewer_data($i, $child);
 
       if (empty($rows)) {
@@ -130,24 +125,28 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
       $element[$i][$i . 'table'] = ['#markup' => $output];
 
       unset($rows);
-
     }
 
     // Un-collapse the first fieldset.
+    // TODO: should we allow a property to specify which transcript is primary?
+    // Is there any example GFF?
     $element[0]['#attributes']['class'] = ['collapsible'];
-
     $child_draw['children'] = $this->feature_coords;
-    // Pass in the needed JS info.
     drupal_add_js([
       'children_draw_info' => $child_draw,
     ], 'setting');
 
-    drupal_add_js(drupal_get_path('module', 'tripal_manage_analyses') . "/theme/js/tripal_manage_analyses_featureloc.js");
+    drupal_add_js(drupal_get_path('module', 'tripal_chado') . "/theme/js/tripal_chado_data_sequence_features_featureloc.js");
 
   }
 
   /**
+   * Builds the featureviewer drawing for a given child feature.
    *
+   * @param int $i
+   *   Cardinal tracker.
+   * @param array $child
+   *   Child array as created by data__sequence_features field.
    */
   private function build_featureviewer_data($i, $child) {
 
@@ -155,12 +154,11 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
 
     $grand_children = $child['children'] ?? NULL;
 
-    // Set base info
     // All child features will be drawn on this one in 'data'
     // Convert and store the coordinates for hte feature viewer.
-    $this->convertFeatureCoords($i, $info->feature_id, $info);
+    $this->convertFeatureCoords($i, $info);
 
-    // Repeat for grandchildren;.
+    // Repeat recursively for grandchildren and their children etc.
     if ($grand_children) {
       foreach ($grand_children as $grand_child) {
         $this->build_featureviewer_data($i, $grand_child);
@@ -169,7 +167,7 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
   }
 
   /**
-   * Builds featureloc string for display to user.
+   * Builds featureloc string for display to user in table.
    *
    * @param $featureloc
    *   The featureloc object returned from chado_expand_var on featureloc.
@@ -179,7 +177,6 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
   private function buildFeatureString($featureloc) {
 
     $info = $featureloc->feature_id;
-
     $min = $info->fmin;
     $max = $info->fmax;
     $strand = $info->strand;
@@ -190,18 +187,18 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
     }
 
     $out = "${parent}:  ${min}-${max} (${strand})";
-
     return $out;
   }
 
   /**
    * Converts featureloc coordinates to be based on the entity.
    *
-   * @param $i
-   * @param $feature_id
-   * @param $info
+   * @param int $i
+   *   Cardinality tracker.
+   * @param object $info
+   *   The chado_expand_var object generated by the field.
    */
-  private function convertFeatureCoords($i, $feature_id, $info) {
+  private function convertFeatureCoords($i, $info) {
 
     $featureloc = $info->featureloc->feature_id;
     // TODO: what if theres no featureloc relative to a parent?
@@ -216,7 +213,7 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
     if ($strand == '+') {
 
       // It doesnt matter what strand it is, we always do this.
-      // TODO: check that assertion.
+      // TODO: check this assertion.
       $start = $min - $parent_start + 1;
       $stop = $max - $parent_start + 1;
     }
@@ -260,25 +257,31 @@ class data__sequence_features_formatter extends ChadoFieldFormatter {
 
     switch ($name) {
       case 'mRNA':
-        return '#12E09D';
+        return '#AC92EB';
 
       case 'polypeptide':
-        return '#808080';
+        return '#4FC1E8';
 
       case 'CDS':
-        return '#FF0000';
+        return '#A0D568';
 
       case 'exon':
-        return '#F4D4AD';
+        return '#FFCE54';
 
       case NULL:
-        return '#000000';
+        return '#ED5564';
     }
 
   }
 
   /**
+   * Builds a table of recursive children featurelocs.
+   *
+   * @param array $child
+   *   Child array from the base field.  Should have an info and a children key.
    *
+   * @return array
+   *   Array of rows suitable for theme_table().
    */
   private function buildChildTable($child) {