tripal_contact.api.inc 4.9 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158
  1. <?php
  2. /**
  3. * @file
  4. * Provides an application programming interface (API) to manage libraries
  5. *
  6. * @defgroup tripal_contact_api contact Module API
  7. * @ingroup tripal_api
  8. */
  9. /**
  10. * Retrieve properties of a given type for a given contact
  11. *
  12. * @param $contact_id
  13. * The contact_id of the properties you would like to retrieve
  14. * @param $property
  15. * The cvterm name of the properties to retrieve
  16. *
  17. * @return
  18. * An contact chado variable with the specified properties expanded
  19. *
  20. * @ingroup tripal_contact_api
  21. */
  22. function tripal_contact_get_property($contact_id, $property) {
  23. return tripal_core_get_property('contact', $contact_id, $property, 'tripal_contact');
  24. }
  25. /**
  26. * Insert a given property
  27. *
  28. * @param $contact_id
  29. * The contact_id of the property to insert
  30. * @param $property
  31. * The cvterm name of the property to insert
  32. * @param $value
  33. * The value of the property to insert
  34. * @param $update_if_present
  35. * A boolean indicated whether to update the record if it's already present
  36. *
  37. * @return
  38. * True of success, False otherwise
  39. *
  40. * @ingroup tripal_contact_api
  41. */
  42. function tripal_contact_insert_property($contact_id, $property, $value, $update_if_present = 0) {
  43. return tripal_core_insert_property('contact', $contact_id, $property, 'tripal_contact', $value, $update_if_present);
  44. }
  45. /**
  46. * Update a given property
  47. *
  48. * @param $contact_id
  49. * The contact_id of the property to update
  50. * @param $property
  51. * The cvterm name of the property to update
  52. * @param $value
  53. * The value of the property to update
  54. * @param $insert_if_missing
  55. * A boolean indicated whether to insert the record if it's absent
  56. *
  57. * Note: The property will be identified using the unique combination of the $contact_id and $property
  58. * and then it will be updated with the supplied value
  59. *
  60. * @return
  61. * True of success, False otherwise
  62. *
  63. * @ingroup tripal_contact_api
  64. */
  65. function tripal_contact_update_property($contact_id, $property, $value, $insert_if_missing = 0) {
  66. return tripal_core_update_property('contact', $contact_id, $property, 'tripal_contact', $value, $insert_if_missing);
  67. }
  68. /**
  69. * Delete a given property
  70. *
  71. * @param $contact_id
  72. * The contact_id of the property to delete
  73. * @param $property
  74. * The cvterm name of the property to delete
  75. *
  76. * Note: The property will be identified using the unique combination of the $contact_id and $property
  77. * and then it will be deleted
  78. *
  79. * @return
  80. * True of success, False otherwise
  81. *
  82. * @ingroup tripal_contact_api
  83. */
  84. function tripal_contact_delete_property($contact_id, $property) {
  85. return tripal_core_delete_property('contact', $contact_id, $property, 'tripal_contact');
  86. }
  87. /**
  88. * Adds a contact to the Chado contact table
  89. *
  90. * @param $name
  91. * The name of the contact
  92. * @param $description
  93. * Text describing the contact
  94. * @param $type
  95. * The type of contact. Must be a term in the tripal_contact vocabulary
  96. * @param $properties
  97. * An associative array containing a list of key value pairs for the properites.
  98. * The key's must be valid terms in the tripal_contact vocabulary (e.g. Affiliation,
  99. * Address, etc).
  100. *
  101. * @return
  102. * On success, an array is returned containing the fields of the contact
  103. * record including the newly added contact_id. On failure, FALSE is
  104. * returned
  105. *
  106. * @ingroup tripal_contact_api
  107. *
  108. */
  109. function tripal_contact_add_contact($name, $description, $type, $properties) {
  110. // check to see if this contact name already exists.
  111. $values = array('name' => $name);
  112. $options = array('statement_name' => 'sel_contact_na');
  113. $contact = tripal_core_chado_select('contact', array('contact_id'), $values, $options);
  114. if (count($contact) == 0) {
  115. $cvterm = tripal_cv_get_cvterm_by_name($type, NULL, 'tripal_contact');
  116. if (!$cvterm) {
  117. watchdog('tripal_contact',"Cannot find contact type '%type'",
  118. array('%type' => $type), WATCHDOG_ERROR);
  119. return FALSE;
  120. }
  121. $values = array(
  122. 'name' => $name,
  123. 'description' => '',
  124. 'type_id' => $cvterm->cvterm_id,
  125. );
  126. $options = array('statement_name' => 'ins_contact_nadety');
  127. $contact = tripal_core_chado_insert('contact', $values, $options);
  128. if (!$contact) {
  129. watchdog('tripal_contact','Could not add the contact', array(), WATCHDOG_ERROR);
  130. return FALSE;
  131. }
  132. }
  133. else {
  134. $contact = (array) $contact[0];
  135. }
  136. // add the description property. We don't store this in the contact.description
  137. // field because it is only 255 characters long and may not be enough
  138. if ($description) {
  139. tripal_contact_insert_property($contact['contact_id'], 'contact_description', $description, TRUE);
  140. }
  141. // add in the other properties provided
  142. foreach ($properties as $key => $value) {
  143. $success = tripal_contact_insert_property($contact['contact_id'], $key,$value, TRUE);
  144. if (!$success) {
  145. watchdog('tripal_contact',"Could not add the contact property '%prop'", array('%prop' => $key), WATCHDOG_ERROR);
  146. return FALSE;
  147. }
  148. }
  149. return $contact;
  150. }