tripal_bulk_loader.api.templates.inc

  1. 2.x tripal_bulk_loader/api/tripal_bulk_loader.api.templates.inc
  2. 1.x tripal_bulk_loader/api/tripal_bulk_loader.api.templates.inc

Provides functions for hooking into bulk loader functionality.

File

tripal_bulk_loader/api/tripal_bulk_loader.api.templates.inc
View source
  1. <?php
  2. /**
  3. * @file
  4. * Provides functions for hooking into bulk loader functionality.
  5. *
  6. * @ingroup tripal_bulk_loader
  7. */
  8. /**
  9. * @defgroup tripal_bulk_loader_api Tripal Bulk Loader Module API
  10. * @ingroup tripal_api
  11. * @{
  12. * All functions in this file provide an API to administrative management of bulk loader templates
  13. * @}
  14. */
  15. /**
  16. * Validates an $options array for insert or update of a bulk loader record.
  17. *
  18. * @param $val_type
  19. * The type of validation. Can be either 'insert' or 'update'.
  20. * @param $options
  21. * An array of key/value pairs containing the following keys:
  22. * 'template_name': The name of the template.
  23. * 'template_array': The JSON array representing the template.
  24. * Optional:
  25. * 'strict': If set then only JSON formatted templates are allowed.
  26. * @param $errors
  27. * An empty array where validation error messages will be set. The keys
  28. * of the array will be name of the field from the options array and the
  29. * value is the error message.
  30. * @param $warnings
  31. * An empty array where validation warning messagges will be set. The
  32. * warnings should not stop an insert or an update but should be provided
  33. * to the user as information by a drupal_set_message() if appropriate. The
  34. * keys of the array will be name of the field from the options array and the
  35. * value is the error message.
  36. *
  37. * @return
  38. * If validation failes then FALSE is returned. Any options that do not pass
  39. * validation checks will be added in the $errors array with the key being
  40. * the option and the value being the error message. If validation
  41. * is successful then TRUE is returned.
  42. *
  43. */
  44. function tripal_validate_bulk_loader_template($val_type, &$options, &$errors, &$warnings = array()) {
  45. $template_array = trim($options['template_array']);
  46. $template_name = trim($options['template_name']);
  47. $strict = array_key_exists('strict', $options) ? $options['strict'] : FALSE;
  48. // Make sure the template array is one of the supported types
  49. // DEPRECATED: A stringified version of the array (causes security issues)
  50. if (preg_match('/^array/', $template_array)) {
  51. if ($strict) {
  52. $errors['template_array'] = t('Invalid template array. Please provide
  53. a JSON formatted array');
  54. return FALSE;
  55. }
  56. else {
  57. $warnings['template_array'] = t('Please note that import of
  58. bulk loader templates as PHP arrays as a stringified array is deprecated
  59. and will be removed in future versions of Tripal. Export and import
  60. format will be JSON.');
  61. }
  62. }
  63. // DEPRECATED: A serialized PHP array
  64. elseif (preg_match('/^a:/', $template_array)) {
  65. if ($strict) {
  66. $errors['template_array'] = t('Invalid template array. Please provide
  67. a JSON formatted array');
  68. return FALSE;
  69. }
  70. else {
  71. $warnings['template_array'] = t('Please note that import of
  72. bulk loader templates as PHP serialized arrays is deprecated and will
  73. be removed in future versions of Tripal. Export and import format will
  74. be JSON.');
  75. }
  76. }
  77. // JSON FORMAT
  78. elseif (json_decode($template_array)) {
  79. // This is correct!
  80. }
  81. else {
  82. $errors['template_array'] = t('The template array must be in
  83. JSON format (although PHP strigified arrays and PHP serialized
  84. arrays are temporarily supported for backwards compatibility).');
  85. return FALSE;
  86. }
  87. // Make sure the template name is unique
  88. $name_exists = db_select('tripal_bulk_loader_template', 'tblt')
  89. ->fields('tblt', array('template_id'))
  90. ->condition('name', $template_name)
  91. ->execute()
  92. ->fetchField();
  93. if ($name_exists) {
  94. $errors['template_name'] = t('The template name already exists. Please
  95. choose another name.');
  96. return FALSE;
  97. }
  98. return TRUE;
  99. }
  100. /**
  101. * Inserts a bulk loader template record.
  102. *
  103. * This function validates the options passed prior to insertion of the record,
  104. *
  105. * @param $options
  106. * An array of key/value pairs containing the following keys:
  107. * 'template_name': The name of the template.
  108. * 'template_array': The JSON array representing the template.
  109. * Optional:
  110. * 'strict': If set then only JSON formatted templates are allowed.
  111. * @param $errors
  112. * An empty array where validation error messages will be set. The keys
  113. * of the array will be name of the field from the options array and the
  114. * value is the error message.
  115. * @param $warnings
  116. * An empty array where validation warning messagges will be set. The
  117. * warnings should not stop an insert or an update but should be provided
  118. * to the user as information by a drupal_set_message() if appropriate. The
  119. * keys of the array will be name of the field from the options array and the
  120. * value is the error message.
  121. * @return
  122. * TRUE for success and FALSE for failure.
  123. */
  124. function tripal_insert_bulk_loader_template($options, &$errors, &$warnings) {
  125. $success = tripal_validate_bulk_loader_template('insert', $options, $errors, $warnings);
  126. if (!$success) {
  127. foreach ($errors as $field => $message) {
  128. tripal_report_error('tripal_bulkldr', TRIPAL_ERROR, $message);
  129. }
  130. return FALSE;
  131. }
  132. // Insert the bulk loader template.
  133. $template_array = trim($options['template_array']);
  134. $template_name = trim($options['template_name']);
  135. // Previous version of Tripal would export the template as a PHP array.
  136. // This has security implications and is deprecated. This support should
  137. // be reomved in future versions of Tripal, but to support transfers of
  138. // templates between v1.1 and v2.x sites we support it.
  139. if (preg_match('/^array/', $template_array)) {
  140. $tarray = array();
  141. eval("\$tarray = $template_array;");
  142. $template_array = serialize($tarray);
  143. }
  144. // For a brief period, the bulk loader templates were exported as a PHP
  145. // serialized array. We have moved to exporting in JSON as JSON is more
  146. // user friendly. But we must support the serialized PHP array for
  147. // backwards compatibility of v2.0-rc1 sites and v2.x sites.
  148. elseif (preg_match('/^a:/', $template_array)) {
  149. // do nothing it's in PHP serialized format
  150. }
  151. // The typical format is JSON
  152. elseif (json_decode($template_array)) {
  153. $template_array = serialize(json_decode($template_array, TRUE));
  154. }
  155. else {
  156. $errors['template_array'] = t('Unrecognized array type.');
  157. return FALSE;
  158. }
  159. $record = array(
  160. 'name' => $template_name,
  161. 'template_array' => $template_array,
  162. 'created' => time(),
  163. 'changed' => time()
  164. );
  165. if (!drupal_write_record('tripal_bulk_loader_template', $record)) {
  166. return FALSE;
  167. }
  168. return TRUE;
  169. }
  170. /**
  171. * Meant to be called from a form_validate function to ensure a newly added bulk loader record
  172. * name is unique and not empty.
  173. *
  174. * @param $new_record_name
  175. * The record name to check for uniqueness
  176. * @param $template_id
  177. * The template_id of the template to add the record to
  178. * @param $template_array
  179. * The array describing the template. Optional -will be loaded using template_id if not provided
  180. * @param $current_priority
  181. * The priority of the already existing record -checks that the name only occurs on this particular record
  182. *
  183. * @return
  184. * TRUE if the record name is not empty and not already in the template_array; FALSE otherwise
  185. *
  186. * @ingroup tripal_bulk_loader_api
  187. */
  188. function tripal_is_bulk_loader_record_name_unique($new_record_name, $template_id, $template_array = NULL, $current_priority = NULL) {
  189. // get the template array if it's not supplied
  190. if (empty($template_array)) {
  191. $template = db_query("SELECT * FROM {tripal_bulk_loader_template} WHERE template_id=:template", array(':template' => $template_id))->fetchObject();
  192. $template_array = unserialize($template->template_array);
  193. if (!is_array($template_array)) {
  194. return TRUE;
  195. }
  196. }
  197. // Check that the new record name is not empty
  198. if (empty($new_record_name)) {
  199. return FALSE;
  200. }
  201. // Check the new record name is unique
  202. foreach ($template_array as $priority => $t) {
  203. if (strcmp($t['record_id'], $new_record_name) == 0) {
  204. if (($priority != $current_priority) AND ($current_priority !== NULL)) {
  205. return FALSE;
  206. }
  207. }
  208. }
  209. return TRUE;
  210. }
  211. /**
  212. * An API function to delete a record from a template array
  213. *
  214. * @param $delete_priority
  215. * The priority of the record to be deleted
  216. * @param $template_array
  217. * The array describing the template
  218. *
  219. * @return
  220. * The modified template array
  221. *
  222. * @ingroup tripal_bulk_loader_api
  223. */
  224. function tripal_delete_bulk_loader_record($delete_priority, $template_array) {
  225. if (empty($template_array)) {
  226. drupal_set_message("Unable to delete record with a priority of $priority since the template was not supplied",'error');
  227. return FALSE;
  228. }
  229. $new_template_array = array();
  230. $i=0;
  231. foreach ($template_array as $priority => $record) {
  232. if ($priority != $delete_priority) {
  233. $new_template_array[$i] = $record;
  234. $i++;
  235. }
  236. }
  237. return $new_template_array;
  238. }
  239. /**
  240. * An API function to delete a field from a template array
  241. *
  242. * @param $priority
  243. * The priority of the record containing the field
  244. * @param $delete_field_index
  245. * The index of the field to be deleted
  246. * @param $template_array
  247. * The array describing the template
  248. *
  249. * @return
  250. * The modified template array
  251. *
  252. * @ingroup tripal_bulk_loader_api
  253. */
  254. function tripal_delete_bulk_loader_field($priority, $delete_field_index, $template_array) {
  255. if (empty($template_array)) {
  256. drupal_set_message("Unable to delete record with a priority of $priority since the template was not supplied",'error');
  257. return FALSE;
  258. }
  259. // Re-order the remaining fields of the same record to ensure that the indicies are
  260. // 0 to size and. If this is not done, weird behaviour may result
  261. $new_template_array = $template_array;
  262. $new_template_array[$priority]['fields'] = array();
  263. $i=0;
  264. foreach ($template_array[$priority]['fields'] as $field_index => $field_details) {
  265. if ($field_index != $delete_field_index) {
  266. $new_template_array[$priority]['fields'][$i] = $field_details;
  267. $i++;
  268. }
  269. }
  270. // If this field was the only one in the current record, also delete the record
  271. if (empty($new_template_array[$priority]['fields'])) {
  272. $new_template_array = tripal_delete_bulk_loader_record($priority, $new_template_array);
  273. }
  274. return $new_template_array;
  275. }

Related topics