Refs #2907. DRY'd up and abstracted out a lot of metadata / annotation functions so I can implement #1115 with a clean conscious.

git-svn-id: http://code.elgg.org/elgg/trunk@8207 36083f99-b078-4883-b0ff-0f9b5a30f544

1 files changed, 87 insertions, 151 deletions

diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php
index a14853359..9b3b49626 100644
--- a/engine/lib/annotations.php
+++ b/engine/lib/annotations.php
@@ -23,25 +23,16 @@ function row_to_elggannotation($row) {
 }
 
 /**
- * Get a specific annotation.
+ * Get a specific annotation by its id.
+ * If you want multiple annotation objects, use
+ * {@link elgg_get_annotations()}.
  *
- * @param int $annotation_id Annotation ID
+ * @param int $id The id of the annotation object being retrieved.
  *
- * @return ElggAnnotation
+ * @return false|ElggAnnotation
  */
-function get_annotation($annotation_id) {
-	global $CONFIG;
-
-	$annotation_id = (int) $annotation_id;
-	$access = get_access_sql_suffix("a");
-
-	$query = "SELECT a.*, n.string as name, v.string as value"
-		. " from {$CONFIG->dbprefix}annotations a"
-		. " JOIN {$CONFIG->dbprefix}metastrings n on a.name_id = n.id"
-		. " JOIN {$CONFIG->dbprefix}metastrings v on a.value_id = v.id"
-		. " where a.id=$annotation_id and $access";
-
-	return row_to_elggannotation(get_data_row($query));
+function elgg_get_annotation_from_id($id) {
+	return elgg_get_metastring_based_object_by_id($id, 'annotations');
 }
 
 /**
@@ -195,29 +186,87 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu
  * @since 1.8.0
  */
 function elgg_get_annotations(array $options = array()) {
-	// map the annotation_* options to metastring_* options
-	$map = array(
-		'annotation_names' => 'metastring_names',
-		'annotation_values' => 'metastring_values',
-		'annotation_case_sensitive' => 'metastring_case_sensitive',
-		'annotation_owner_guids' => 'metastring_owner_guids',
-		'annotation_created_time_lower' => 'metastring_created_time_lower',
-		'annotation_created_time_upper' => 'metastring_created_time_upper',
-		'annotation_calculation' => 'metastring_calculation'
-	);
+	$options['metastring_type'] = 'annotations';
+	return elgg_get_metastring_based_objects($options);
+}
 
-	$singulars = array('annotation_name', 'annotation_value');
-	$options = elgg_normalise_plural_options_array($options, $singulars);
+/**
+ * Deletes annotations based on $options.
+ *
+ * @warning Unlike elgg_get_annotations() this will not accept an empty options array!
+ *
+ * @param array $options An options array. {@See elgg_get_annotations()}
+ * @return mixed
+ * @since 1.8
+ */
+function elgg_delete_annotations(array $options) {
+	if (!$options || !is_array($options)) {
+		return false;
+	}
 
-	foreach ($map as $ann => $ms) {
-		if (isset($options[$ann])) {
-			$options[$ms] = $options[$ann];
-		}
+	$options['metastring_type'] = 'annotations';
+	return elgg_batch_metastring_based_objects($options, 'elgg_batch_delete_callback');
+}
+
+/**
+ * Disables annotations based on $options.
+ *
+ * @warning Unlike elgg_get_annotations() this will not accept an empty options array!
+ *
+ * @param array $options An options array. {@See elgg_get_annotations()}
+ * @return mixed
+ * @since 1.8
+ */
+function elgg_disable_annotations(array $options) {
+	if (!$options || !is_array($options)) {
+		return false;
+	}
+
+	$options['metastrings_type'] = 'annotations';
+	return elgg_batch_metastring_based_objects($options, 'elgg_batch_disable_callback');
+}
+
+/**
+ * Enables annotations based on $options.
+ *
+ * @warning Unlike elgg_get_annotations() this will not accept an empty options array!
+ *
+ * @param array $options An options array. {@See elgg_get_annotations()}
+ * @return mixed
+ * @since 1.8
+ */
+function elgg_enable_annotations(array $options) {
+	if (!$options || !is_array($options)) {
+		return false;
 	}
 
-	return elgg_get_metastring_based_objects($options, 'annotations');
+	$options['metastring_type'] = 'annotations';
+	return elgg_batch_metastring_based_objects($options, 'elgg_batch_enable_callback');
+}
+
+/**
+ * Returns a rendered list of annotations with pagination.
+ *
+ * @param array $options Annotation getter and display options.
+ * {@see elgg_get_annotations()} and {@see elgg_list_entities()}.
+ *
+ * @return string The list of entities
+ * @since 1.8
+ */
+function elgg_list_annotations($options) {
+	$defaults = array(
+		'limit' => 25,
+		'offset' => (int) max(get_input('annoff', 0), 0),
+	);
+
+	$options = array_merge($defaults, $options);
+
+	return elgg_list_entities($options, 'elgg_get_annotations', 'elgg_view_annotation_list');
 }
 
+/**
+ * Entities interfaces
+ */
 
 /**
  * Returns entities based upon annotations.  Accepts the same values as
@@ -254,6 +303,8 @@ function elgg_get_annotations(array $options = array()) {
  *
  *  annotation_owner_guids => NULL|ARR guids for annotaiton owners
  *
+ *  annotation_ids => NULL|ARR Annotation IDs
+ *
  * @return array
  * @since 1.7.0
  */
@@ -272,6 +323,8 @@ function elgg_get_entities_from_annotations(array $options = array()) {
 
 		'annotation_owner_guids'				=>	ELGG_ENTITIES_ANY_VALUE,
 
+		'annotation_ids'						=>	ELGG_ENTITIES_ANY_VALUE,
+
 		'order_by'								=>	'maxtime desc',
 		'group_by'								=>	'a.entity_guid'
 	);
@@ -279,7 +332,7 @@ function elgg_get_entities_from_annotations(array $options = array()) {
 	$options = array_merge($defaults, $options);
 
 	$singulars = array('annotation_name', 'annotation_value',
-	'annotation_name_value_pair', 'annotation_owner_guid');
+	'annotation_name_value_pair', 'annotation_owner_guid', 'annotation_id');
 
 	$options = elgg_normalise_plural_options_array($options, $singulars);
 
@@ -317,26 +370,6 @@ function elgg_list_entities_from_annotations($options = array()) {
 }
 
 /**
- * Returns a rendered list of annotations with pagination.
- *
- * @param array $options Annotation getter and display options.
- * {@see elgg_get_annotations()} and {@see elgg_list_entities()}.
- *
- * @return string The list of entities
- * @since 1.8
- */
-function elgg_list_annotations($options) {
-	$defaults = array(
-		'limit' => 25,
-		'offset' => (int) max(get_input('annoff', 0), 0),
-	);
-
-	$options = array_merge($defaults, $options);
-
-	return elgg_list_entities($options, 'elgg_get_annotations', 'elgg_view_annotation_list');
-}
-
-/**
  * Get entities ordered by a mathematical calculation
  *
  * @param array $options An options array:
@@ -385,103 +418,6 @@ function elgg_list_entities_from_annotation_calculation($options) {
 	return elgg_list_entities($options, 'elgg_get_entities_from_annotation_calculation');
 }
 
-
-/**
- * Delete a given annotation.
- *
- * @param int $id The annotation id
- *
- * @return bool
- */
-function delete_annotation($id) {
-	global $CONFIG;
-
-	$id = (int)$id;
-
-	$access = get_access_sql_suffix();
-	$annotation = get_annotation($id);
-
-	if (elgg_trigger_event('delete', 'annotation', $annotation)) {
-		remove_from_river_by_annotation($id);
-		return delete_data("DELETE from {$CONFIG->dbprefix}annotations where id=$id and $access");
-	}
-
-	return FALSE;
-}
-
-/**
- * Clear all the annotations for a given entity, assuming you have access to that metadata.
- *
- * @param int    $guid The entity guid
- * @param string $name The name of the annotation to delete.
- *
- * @return int Number of annotations deleted or false if an error
- */
-function clear_annotations($guid, $name = "") {
-	global $CONFIG;
-
-	$guid = (int)$guid;
-
-	if (!empty($name)) {
-		$name = get_metastring_id($name);
-		if ($name === false) {
-			// name doesn't exist so 0 rows were deleted
-			return 0;
-		}
-	}
-
-	$entity_guid = (int) $guid;
-	if ($entity = get_entity($entity_guid)) {
-		if ($entity->canEdit()) {
-			$where = array();
-
-			if ($name != "") {
-				$where[] = " name_id='$name'";
-			}
-
-			$query = "DELETE from {$CONFIG->dbprefix}annotations where entity_guid=$guid ";
-			foreach ($where as $w) {
-				$query .= " and $w";
-			}
-
-			return delete_data($query);
-		}
-	}
-
-	return FALSE;
-}
-
-/**
- * Clear all annotations belonging to a given owner_guid
- *
- * @param int $owner_guid The owner
- *
- * @return int Number of annotations deleted
- */
-function clear_annotations_by_owner($owner_guid) {
-	global $CONFIG;
-
-	$owner_guid = (int)$owner_guid;
-
-	$query = "SELECT id from {$CONFIG->dbprefix}annotations WHERE owner_guid=$owner_guid";
-
-	$annotations = get_data($query);
-	$deleted = 0;
-
-	if (!$annotations) {
-		return 0;
-	}
-
-	foreach ($annotations as $id) {
-		// Is this the best way?
-		if (delete_annotation($id->id)) {
-			$deleted++;
-		}
-	}
-
-	return $deleted;
-}
-
 /**
  * Handler called by trigger_plugin_hook on the "export" event.
  *