Associates a variable and it's value to a node.

If a variable is already associated more with a node then the rank value is used to differentiate them. By default the rank is set to 0 and can be manually set by using the $rank argument. But, if left unspecified the next available rank will automatically be used.

If the variable does not exist then it will be added automatically to prevent errors. However, modules developers should always add their variables first before using. If the variable already exists then it will simply be re-used.

Parameters

$nid: The node ID.

$name: The name of the variable to associated with the node.

$value: The value of the variable.

$rank: The rank of the value. Default to zero.

Return value

TRUE|FALSE Returns TRUE if the variable was associated with the node and false if a failure occured.

File

tripal_core/api/tripal_core.tripal_variables.api.inc, line 107

Provides an application programming interface (API) for managing variables associated with Tripal managed Drupal nodes/

Code

function tripal_add_node_variable($nid, $name, $value, $rank = 0) {

  // Make sure the variable exists. To prevent unwanted errors from 
  // umet dependencies (e.g. modules using other modules' variables) the variable
  // will be created automatically if it is missing.
  $variable = tripal_get_variable($name);
  if (!$variable) {
    $variable = tripal_insert_variable($name, "Added automatically. Please describe this variable.");
  }

  // Is the variable already associated with this node? If so, then find the
  // next avilable rank. If the $update_existing variable is true then just
  // update the record.
  $values = tripal_get_node_variables($nid, $name);
  if (count($values) > 0) {
    // Get the max rank and increment the rank to the next highest value.
    $max_rank = 0;
    foreach ($values as $value) {
      // If the user has specified a rank then we want ot honor that. If the
      // rank is already used then don't continue.
      if ($rank > 0 and $rank == $value->rank) {
        tripal_report_error('tripal_core', TRIPAL_ERROR, 
        "The rank for the term, '$term', is already used for node $nid. " .
        "Cannot add the variable.", array());
        return FALSE;
      }
      if ($value->rank > $max_rank) {
        $max_rank = $value->rank;
      }
    }
    $rank = $max_rank++;
  }

  // Add the new variable.
  $node_variable_id = db_insert('tripal_node_variables')
    ->fields(array(
      'variable_id' => $variable->variable_id,
      'nid' => $nid,
      'value' => $value,
      'rank' => $rank
    ))
    ->execute();
  return $node_variable_id;
}