tripal/tripal_api/DEPRECATED/tripal-2.0_pre-release.inc

<?php

/**
 * @file
 * Wrappers for functions created for Tripal 2 whose names were changed before release
 */

/**
 * This function is a wrapper for adding fields to an existing form for managing properties.
 * Many of the chado tables have a corresponding 'prop' table (e.g. analysisprop, contactprop,
 * organismprop, etc) and those prop tables all have the same schema.  Use this function
 * to add all the necessary components to a form for allowing the user to add/edit properties to
 * a given record.  To retreive properties in hook_insert or hook_update of a node form use
 * use the function tripal_core_properties_form_retreive().
 *
 * @param $form
 *   The Drupal form array into which the properties elements will be added
 * @param $form_state
 *   The corresponding form_state array for the form
 * @param $prop_table
 *   The name of the property table (e.g. anlaysisprop, contactprop)
 * @param $id_field
 *   The name of the ID field in the property table (e.g. analysis_id, contact_id)
 * @param $cv_name
 *   The name of the controlled vocabulary that these properties are derived from
 * @param $available_props
 *   An array of properties to inclde in the properties drop down.  This array should
 *   have cvterm_id's as the key and the cvterm name as the value
 * @param $id
 *   The current base table ID.  For example, if the property table is analysisprop then the
 *   value should be that of the analysis_id.  If the property table is contactprop then the
 *   value should be that of the contact_id.  This is the record from which currently assigned
 *   properties will be retrieved.
 * @param $exclude
 *   An optional array of cvterms to exclude when retreiving terms already saved in the database.
 *   Use this array when properties are present but should be handled elsewhere.
 *   For example, for contacts, the description field is stored as a property because
 *   the actual field is only 255 characters. The 'contact_description' therefore should
 *   not be shown in the list of properties, even if present, because it is handled by
 *   a different form element.
 * @param $include
 *   An optional array of terms to pre-populate in the form.  This argument can be used to
 *   add a default set of pre-populated properties regardless if they exist in the database
 *   or not.  The array should be of the following form:
 *     array(
 *       array('cvterm' => $obj1, 'value' => $val1),
 *       array('cvterm' => $obj2, 'value' => $val2),
 *       ... etc
 *     );
 *   The 'cvterm' key should have as a value an object with these properties: 'name', 'cvterm_id', 'definition'.
 * @param $instructions
 *   An optional additional set of instructions for the form properties.
 * @param $fset_title
 *   A title for the property field set.  The default is 'Additional Details'.
 * @ingroup tripal_properties_api
 */
function tripal_core_properties_form(&$form, &$form_state, $prop_table, $id_field, $cv_name,
    $available_props, $id = NULL, $exclude = array(), $include = array(), $instructions = '',
    $fset_title = 'Additional Details') {

    // $available_props is now created by the form based on the cv
    // $exclude and $include are not yet supported

    $details = array(
    'property_table' => $prop_table,
    'base_foreign_key' => $id_field,
    'base_key_value' => $id,
    'cv_name' => $cv_name,
    'fieldset_title' => $fset_title,
    'additional_instructions' => $instructions
  );
  tripal_api_chado_node_properties_form($form, $form_state, $details);

}

/**
 * This function is used in a hook_insert, hook_update for a node form
 * when the properties form has been added to the form.  It retrieves all of the properties
 * and returns them in an array of the format:
 *
 *   $properties[<property name>][<rank>] = <value>
 *
 * This array can then be used for inserting or updating properties using the API call
 * tripal_hook_insert_property()
 *
 * @param $node
 * @param $cvname
 *   The name of the controlled vocabulary that the properties belong to
 *
 * @return
 *   A properties array
 *
 * @ingroup tripal_properties_api
 */
function tripal_core_properties_form_retreive($node, $cv_name) {
  return tripal_api_chado_node_properties_form_retreive($node);
}

/**
 * Retrieve a property for a given base table record
 *
 * @param $basetable
 *   The base table for which the property should be retrieved. Thus to retrieve a property
 *   for a feature the basetable=feature and property is retrieved from featureprop
 * @param $record_id
 *   The foriegn key field of the base table. This should be in integer.
 * @param $property
 *   The cvterm name describing the type of properties to be retrieved
 * @param $cv_name
 *   The name of the cv that the above cvterm is part of
 *
 * @return
 *   An array in the same format as that generated by the function
 *   tripal_core_generate_chado_var().  If only one record is returned it
 *   is a single object.  If more than one record is returned then it is an array
 *   of objects
 *
 * @ingroup tripal_properties_api
 */
function tripal_core_get_property($basetable, $record_id, $property, $cv_name) {
  return tripal_api_chado_get_property($basetable, $record_id, $property, $cv_name);
}

/**
 * Insert a property for a given base table.  By default if the property already
 * exists a new property is added with the next available rank.  If
 * $update_if_present argument is specified then the record will be updated if it
 * exists rather than adding a new property.
 *
 * @param $basetable
 *   The base table for which the property should be inserted. Thus to insert a property
 *   for a feature the basetable=feature and property is inserted into featureprop
 * @param $record_id
 *   The foriegn key value of the base table. This should be in integer.
 * @param $property
 *   The cvterm name describing the type of properties to be inserted
 * @param $cv_name
 *   The name of the cv that the above cvterm is part of
 * @param $value
 *   The value of the property to be inserted (can be empty)
 * @param $update_if_present
 *   A boolean indicating whether an existing record should be updated. If the
 *   property already exists and this value is not specified or is zero then
 *   a new property will be added with the next largest rank.
 *
 * @return
 *   Return True on Insert/Update and False otherwise
 *
 * @ingroup tripal_properties_api
 */
function tripal_core_insert_property($basetable, $record_id, $property,
$cv_name, $value, $update_if_present = 0) {

  return tripal_api_chado_insert_property($basetable, $record_id, $property,
$cv_name, $value, $update_if_present);
}

/**
 * Update a property for a given base table record and property name.  This
 * function should be used only if one record of the property will be present.
 * If the property name can have multiple entries (with increasing rank) then
 * use the function named tripal_core_update_property_by_id
 *
 * @param $basetable
 *   The base table for which the property should be updated. The property table
 *   is constructed using  a combination of the base table name and the suffix
 *   'prop' (e.g. basetable = feature then property tabie is featureprop).
 * @param $record_id
 *   The foreign key of the basetable to update a property for. This should be in integer.
 *   For example, if the basetable is 'feature' then the $record_id should be the feature_id
 * @param $property
 *   The cvterm name of property to be updated
 * @param $cv_name
 *   The name of the cv that the above cvterm is part of
 * @param $value
 *   The value of the property to be inserted (can be empty)
 * @param $insert_if_missing
 *   A boolean indicating whether a record should be inserted if one doesn't exist to update
 *
 * Note: The property to be updated is select via the unique combination of $record_id and
 * $property and then it is updated with the supplied value
 *
 * @return
 *   Return True on Update/Insert and False otherwise
 *
 * @ingroup tripal_properties_api
 */
function tripal_core_update_property($basetable, $record_id, $property,
$cv_name, $value, $insert_if_missing = 0) {

  return tripal_api_chado_update_property($basetable, $record_id, $property,
$cv_name, $value, $insert_if_missing);
}

/**
 * Update a property for a given base table record.  This function should be
 * used if multiple records of the same property will be present. Also, use this
 * function to change the property name of an existing property.
 *
 * @param $basetable
 *   The base table for which the property should be updated. The property table
 *   is constructed using  a combination of the base table name and the suffix
 *   'prop' (e.g. basetable = feature then property tabie is featureprop).
 * @param $record_id
 *   The primary key of the base table. This should be in integer.
 *   For example, if the basetable is 'feature' then the $record_id should be the featureprop_id
 * @param $property
 *   The cvterm name of property to be updated
 * @param $cv_name
 *   The name of the cv that the above cvterm is part of
 * @param $value
 *   The value of the property to be inserted (can be empty)
 *
 * @return
 *   Return True on Update/Insert and False otherwise
 *
 * @ingroup tripal_properties_api
 */
function tripal_core_update_property_by_id($basetable, $record_id, $property,
$cv_name, $value) {

  return tripal_api_chado_update_property_by_id($basetable, $record_id, $property,
$cv_name, $value);
}

/**
 * Deletes a property for a given base table record using the property name
 *
 * @param $basetable
 *   The base table for which the property should be deleted. Thus to deleted a property
 *   for a feature the basetable=feature and property is deleted from featureprop
 * @param $record_id
 *   The primary key of the basetable to delete a property for. This should be in integer.
 * @param $property
 *   The cvterm name describing the type of property to be deleted
 * @param $cv_name
 *   The name of the cv that the above cvterm is part of
 *
 * Note: The property to be deleted is select via the unique combination of $record_id and $property
 *
 * @return
 *   Return True on Delete and False otherwise
 *
 * @ingroup tripal_properties_api
 */
function tripal_core_delete_property($basetable, $record_id, $property, $cv_name) {
  return tripal_api_chado_delete_property($basetable, $record_id, $property, $cv_name);
}

/**
 * Deletes a property using the property ID
 *
 * @param $basetable
 *   The base table for which the property should be deleted. Thus to deleted a property
 *   for a feature the basetable=feature and property is deleted from featureprop
 * @param $record_id
 *   The primary key of the basetable to delete a property for. This should be in integer.
 *
 * @return
 *   Return True on Delete and False otherwise
 *
 * @ingroup tripal_properties_api
 */
function tripal_core_delete_property_by_id($basetable, $record_id) {
  return tripal_api_chado_delete_property_by_id($basetable, $record_id);
}


/**
 * @section Database References API
 */

/**
 * Provides a form for adding to BASE_dbxref and dbxref tables
 *
 * @param $form
 *   The Drupal form array into which the dbxref elements will be added
 * @param $form_state
 *   The corresponding form_state array for the form
 * @param $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
 */
function tripal_core_additional_dbxrefs_form(&$form, &$form_state, $details) {
  tripal_api_chado_node_additional_dbxrefs_form($form, $form_state, $details);
}

/**
 * Function to theme the add/remove dbxrefs form into a table
 */
function theme_tripal_core_additional_dbxrefs_form_table($variables) {
  return theme_tripal_api_chado_node_additional_dbxrefs_form_table($variables);
}

/**
 * This function is used in a hook_insert, hook_update for a node form
 * when the additional_dbxrefs form has been added to the form.  It retrieves all of the dbxrefs
 * and returns them in an array of the format:
 *
 *   $dbxefs[<db_id>][<version>][<dbxref_id>] = <accession>
 *
 * This array can then be used for inserting or updating dbxrefs using the API call
 * tripal_hook_insert_dbxref()
 *
 * @param $node
 *
 * @return
 *   A dbxref array
 *
 * @ingroup tripal_databaserefernce_api
 */
function tripal_core_additional_dbxrefs_form_retreive($node) {
  return tripal_api_chado_node_additional_dbxrefs_form_retreive($node);
}

/**
 * This function is used in hook_insert or hook_update and handles inserting of any new
 * dbxrefs and creation of links between those dbxrefs and node content
 *
 * @param $node
 *    The node passed into hook_insert & hook_update
 * @param $linking_table
 *    The name of the _dbxref linking table (ie: feature_dbxref)
 * @param $foreignkey_name
 *    The name of the foreign key used to link to the node content (ie: feature_id)
 * @param $foreignkey_value
 *    The value of the foreign key (ie: 445, if there exists a feature where feature_id=445)
 */
function tripal_core_additional_dbxrefs_form_update_dbxrefs($node, $linking_table, $foreignkey_name, $foreignkey_value) {
  tripal_api_chado_node_additional_dbxrefs_form_update_dbxrefs($node, $linking_table, $foreignkey_name, $foreignkey_value);
}

/**
 * @section Relationships API
 */

/**
 * Provides a form for adding to BASE_relationship and relationship tables
 *
 * @param $form
 *   The Drupal form array into which the relationship elements will be added
 * @param $form_state
 *   The corresponding form_state array for the form
 * @param $details
 *   An array defining details needed by this form. Required Keys are:
 *     - relationship_table: the name of the relationship table (ie: feature_relationship)
 *     - base_table: the name of the base table (ie: feature)
 *     - base_foreign_key: the name of the foreign key linking this table to the non-relationship 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)
 *     - nodetype: the non-translated singular title of this node type
 *   One of the following:
 *     - cv_id: the id of the ontology to supply terms for the type dropdown
 *     - cv_name: the name of the ontology to supply terms for the type dropdown
 *   Optional keys include:
 *     - fieldset_title: the non-translated title for this fieldset
 *     - additional_instructions: a non-translated string providing additional instructions
 *     - nodetype_plural: the non-translated plural title of this node type
 *
 * @ingroup tripal_relationships_api
 */
function tripal_core_relationships_form(&$form, &$form_state, $details) {
  tripal_api_chado_node_relationships_form($form, $form_state, $details);
}

/**
 * Function to theme the add/remove relationships form into a table
 *
 * @ingroup tripal_relationships_api
 */
function theme_tripal_core_relationships_form_table($variables) {
  return theme_tripal_api_chado_node_relationships_form_table($variables);
}

/**
 * This function is used in a hook_insert, hook_update for a node form
 * when the relationships form has been added to the form.  It retrieves all of the relationships
 * and returns them in an array of the format:
 *
 *   $relationships[<type_id>][<rank>] = array(
 *         'subject_id' => <subject_id>,
 *         'object_id'  => <object_id>,
 *   );
 *
 * This array can then be used for inserting or updating relationships manually
 *
 * @param $node
 *
 * @return
 *   A relationship array
 *
 * @ingroup tripal_relationships_api
 */
function tripal_core_relationships_form_retreive($node) {
  tripal_api_chado_node_relationships_form_retreive($node);
}

/**
 * This function is used in hook_insert or hook_update and handles inserting of
 * relationships between the current nodetype and other memebers of the same nodetype
 *
 * @param $node
 *    The node passed into hook_insert & hook_update
 * @param $relationship_table
 *    The name of the _relationship linking table (ie: feature_relationship)
 * @param $current_id
 *    The value of the foreign key (ie: 445, if there exists a feature where feature_id=445)
 *
 * @ingroup tripal_relationships_api
 */
function tripal_core_relationships_form_update_relationships($node, $relationship_table, $current_id) {
  tripal_api_chado_node_relationships_form_update_relationships($node, $relationship_table, $current_id);
}