diff options
Diffstat (limited to 'engine/lib/annotations.php')
| -rw-r--r-- | engine/lib/annotations.php | 734 |
1 files changed, 249 insertions, 485 deletions
diff --git a/engine/lib/annotations.php b/engine/lib/annotations.php index d61173ef6..5e9b530de 100644 --- a/engine/lib/annotations.php +++ b/engine/lib/annotations.php @@ -13,9 +13,11 @@ * @param stdClass $row Db row result object * * @return ElggAnnotation + * @access private */ function row_to_elggannotation($row) { if (!($row instanceof stdClass)) { + // @todo should throw in this case? return $row; } @@ -23,25 +25,30 @@ 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 ElggAnnotation|false */ -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"; +function elgg_get_annotation_from_id($id) { + return elgg_get_metastring_based_object_from_id($id, 'annotations'); +} - return row_to_elggannotation(get_data_row($query)); +/** + * Deletes an annotation using its ID. + * + * @param int $id The annotation ID to delete. + * @return bool + */ +function elgg_delete_annotation_by_id($id) { + $annotation = elgg_get_annotation_from_id($id); + if (!$annotation) { + return false; + } + return $annotation->delete(); } /** @@ -50,14 +57,14 @@ function get_annotation($annotation_id) { * @param int $entity_guid Entity Guid * @param string $name Name of annotation * @param string $value Value of annotation - * @param string $value_type Type of value - * @param int $owner_guid Owner of annotation + * @param string $value_type Type of value (default is auto detection) + * @param int $owner_guid Owner of annotation (default is logged in user) * @param int $access_id Access level of annotation * * @return int|bool id on success or false on failure */ -function create_annotation($entity_guid, $name, $value, $value_type, -$owner_guid, $access_id = ACCESS_PRIVATE) { +function create_annotation($entity_guid, $name, $value, $value_type = '', +$owner_guid = 0, $access_id = ACCESS_PRIVATE) { global $CONFIG; $result = false; @@ -89,20 +96,18 @@ $owner_guid, $access_id = ACCESS_PRIVATE) { $entity = get_entity($entity_guid); if (elgg_trigger_event('annotate', $entity->type, $entity)) { - system_log($entity, 'annotate'); - // If ok then add it $result = insert_data("INSERT into {$CONFIG->dbprefix}annotations (entity_guid, name_id, value_id, value_type, owner_guid, time_created, access_id) VALUES ($entity_guid,'$name',$value,'$value_type', $owner_guid, $time, $access_id)"); if ($result !== false) { - $obj = get_annotation($result); + $obj = elgg_get_annotation_from_id($result); if (elgg_trigger_event('create', 'annotation', $obj)) { return $result; } else { // plugin returned false to reject annotation - delete_annotation($result); + elgg_delete_annotation_by_id($result); return FALSE; } } @@ -153,17 +158,13 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu // If ok then add it $result = update_data("UPDATE {$CONFIG->dbprefix}annotations - set value_id='$value', value_type='$value_type', access_id=$access_id, owner_guid=$owner_guid - where id=$annotation_id and name_id='$name' and $access"); + set name_id='$name', value_id='$value', value_type='$value_type', access_id=$access_id, owner_guid=$owner_guid + where id=$annotation_id and $access"); if ($result !== false) { - $obj = get_annotation($annotation_id); - if (elgg_trigger_event('update', 'annotation', $obj)) { - return true; - } else { - // @todo add plugin hook that sends old and new annotation information before db access - delete_annotation($annotation_id); - } + // @todo add plugin hook that sends old and new annotation information before db access + $obj = elgg_get_annotation_from_id($annotation_id); + elgg_trigger_event('update', 'annotation', $obj); } return $result; @@ -177,328 +178,138 @@ function update_annotation($annotation_id, $name, $value, $value_type, $owner_gu * * @param array $options Array in format: * - * annotation_names => NULL|ARR Annotation names - * - * annotation_values => NULL|ARR Annotation values - * - * annotation_case_sensitive => BOOL Overall Case sensitive - * - * annotation_owner_guids => NULL|ARR guids for metadata owners - * - * annotation_created_time_lower => INT Lower limit for created time. - * - * annotation_created_time_upper => INT Upper limit for created time. - * - * annotation_calculation => STR Perform the MySQL function on the annotation values returned. - * - * @return array + * annotation_names => NULL|ARR Annotation names + * annotation_values => NULL|ARR Annotation values + * annotation_ids => NULL|ARR annotation ids + * annotation_case_sensitive => BOOL Overall Case sensitive + * annotation_owner_guids => NULL|ARR guids for annotation owners + * annotation_created_time_lower => INT Lower limit for created time. + * annotation_created_time_upper => INT Upper limit for created time. + * annotation_calculation => STR Perform the MySQL function on the annotation values returned. + * Do not confuse this "annotation_calculation" option with the + * "calculation" option to elgg_get_entities_from_annotation_calculation(). + * The "annotation_calculation" option causes this function to + * return the result of performing a mathematical calculation on + * all annotations that match the query instead of ElggAnnotation + * objects. + * See the docs for elgg_get_entities_from_annotation_calculation() + * for the proper use of the "calculation" option. + * + * + * @return ElggAnnotation[]|mixed * @since 1.8.0 */ -function elgg_get_annotations($options = array()) { - $defaults = array( - // entities - 'types' => ELGG_ENTITIES_ANY_VALUE, - 'subtypes' => ELGG_ENTITIES_ANY_VALUE, - 'type_subtype_pairs' => ELGG_ENTITIES_ANY_VALUE, - - 'guids' => ELGG_ENTITIES_ANY_VALUE, - 'owner_guids' => ELGG_ENTITIES_ANY_VALUE, - 'container_guids' => ELGG_ENTITIES_ANY_VALUE, - 'site_guids' => get_config('site_guid'), - - 'modified_time_lower' => ELGG_ENTITIES_ANY_VALUE, - 'modified_time_upper' => ELGG_ENTITIES_ANY_VALUE, - 'created_time_lower' => ELGG_ENTITIES_ANY_VALUE, - 'created_time_upper' => ELGG_ENTITIES_ANY_VALUE, - - // annotations - // options are normalized to the plural in case we ever add support for them. - 'annotation_names' => ELGG_ENTITIES_ANY_VALUE, - 'annotation_values' => ELGG_ENTITIES_ANY_VALUE, - //'annotation_name_value_pairs' => ELGG_ENTITIES_ANY_VALUE, - //'annotation_name_value_pairs_operator' => 'AND', - - 'annotation_case_sensitive' => TRUE, - //'order_by_annotation' => array(), - 'annotation_calculation' => ELGG_ENTITIES_NO_VALUE, - - 'annotation_created_time_lower' => ELGG_ENTITIES_ANY_VALUE, - 'annotation_created_time_upper' => ELGG_ENTITIES_ANY_VALUE, - - 'annotation_owner_guids' => ELGG_ENTITIES_ANY_VALUE, - - // sql - 'order_by' => 'a.time_created asc', - 'limit' => 10, - 'offset' => 0, - 'count' => FALSE, - 'selects' => array(), - 'wheres' => array(), - 'joins' => array(), - - 'callback' => 'row_to_elggannotation', - ); - - $options = array_merge($defaults, $options); - - // can't use helper function with type_subtype_pair because - // it's already an array...just need to merge it - if (isset($options['type_subtype_pair'])) { - if (isset($options['type_subtype_pairs'])) { - $options['type_subtype_pairs'] = array_merge($options['type_subtype_pairs'], - $options['type_subtype_pair']); - } else { - $options['type_subtype_pairs'] = $options['type_subtype_pair']; - } - } - - $singulars = array('type', 'subtype', 'guid', 'owner_guid', 'container_guid', 'site_guid', - 'annotation_name', 'annotation_value' - ); - $options = elgg_normalise_plural_options_array($options, $singulars); - - if (!$options) { - return false; - } - - $db_prefix = elgg_get_config('dbprefix'); - - // evaluate where clauses - if (!is_array($options['wheres'])) { - $options['wheres'] = array($options['wheres']); - } - - $wheres = $options['wheres']; - - // entities - $wheres[] = elgg_get_entity_type_subtype_where_sql('e', $options['types'], - $options['subtypes'], $options['type_subtype_pairs']); - - $wheres[] = elgg_get_guid_based_where_sql('e.guid', $options['guids']); - $wheres[] = elgg_get_guid_based_where_sql('e.owner_guid', $options['owner_guids']); - $wheres[] = elgg_get_guid_based_where_sql('e.container_guid', $options['container_guids']); - $wheres[] = elgg_get_guid_based_where_sql('e.site_guid', $options['site_guids']); - - $wheres[] = elgg_get_entity_time_where_sql('e', $options['created_time_upper'], - $options['created_time_lower'], $options['modified_time_upper'], $options['modified_time_lower']); - - // annotations - $annotation_clauses = elgg_get_annotation_sql('a', $options['annotation_names'], - $options['annotation_values'], $options['annotation_case_sensitive']); - - $wheres = array_merge($wheres, $annotation_clauses['wheres']); - - $wheres[] = elgg_get_entity_time_where_sql('a', $options['annotation_created_time_upper'], - $options['annotation_created_time_lower'], null, null); - - $wheres[] = elgg_get_guid_based_where_sql('a.owner_guid', $options['annotation_owner_guids']); - - // remove identical where clauses - $wheres = array_unique($wheres); - - // see if any functions failed - // remove empty strings on successful functions - foreach ($wheres as $i => $where) { - if ($where === FALSE) { - return FALSE; - } elseif (empty($where)) { - unset($wheres[$i]); - } - } - - // evaluate join clauses - if (!is_array($options['joins'])) { - $options['joins'] = array($options['joins']); - } - - $joins = $options['joins']; - - $joins = array_merge($joins, $annotation_clauses['joins']); - $joins[] = "JOIN {$db_prefix}entities e ON a.entity_guid = e.guid"; - $joins[] = "JOIN {$db_prefix}metastrings n on a.name_id = n.id"; - $joins[] = "JOIN {$db_prefix}metastrings v on a.value_id = v.id"; - +function elgg_get_annotations(array $options = array()) { - // remove identical join clauses - $joins = array_unique($joins); - - foreach ($joins as $i => $join) { - if ($join === FALSE) { - return FALSE; - } elseif (empty($join)) { - unset($joins[$i]); - } - } - - // evalutate selects - if ($options['selects']) { - $selects = ''; - foreach ($options['selects'] as $select) { - $selects .= ", $select"; - } + // @todo remove support for count shortcut - see #4393 + if (isset($options['__egefac']) && $options['__egefac']) { + unset($options['__egefac']); } else { - $selects = ''; - } - - // check for calculations - if ($options['count']) { - $options['annotation_calculation'] = 'count'; - } - - if ($options['annotation_calculation'] === ELGG_ENTITIES_NO_VALUE) { - $query = "SELECT DISTINCT a.*, n.string as name, v.string as value FROM {$db_prefix}annotations a"; - } else { - $query = "SELECT DISTINCT v.string as value, {$options['annotation_calculation']}(v.string) as calculation FROM {$db_prefix}annotations a"; - } + // support shortcut of 'count' => true for 'annotation_calculation' => 'count' + if (isset($options['count']) && $options['count']) { + $options['annotation_calculation'] = 'count'; + unset($options['count']); + } + } + + $options['metastring_type'] = 'annotations'; + return elgg_get_metastring_based_objects($options); +} - // add joins - foreach ($joins as $j) { - $query .= " $j "; +/** + * Deletes annotations based on $options. + * + * @warning Unlike elgg_get_annotations() this will not accept an empty options array! + * This requires at least one constraint: annotation_owner_guid(s), + * annotation_name(s), annotation_value(s), or guid(s) must be set. + * + * @param array $options An options array. {@See elgg_get_annotations()} + * @return bool|null true on success, false on failure, null if no annotations to delete. + * @since 1.8.0 + */ +function elgg_delete_annotations(array $options) { + if (!elgg_is_valid_options_for_batch_operation($options, 'annotations')) { + return false; } - // add wheres - $query .= ' WHERE '; + $options['metastring_type'] = 'annotations'; + return elgg_batch_metastring_based_objects($options, 'elgg_batch_delete_callback', false); +} - foreach ($wheres as $w) { - $query .= " $w AND "; +/** + * 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 bool|null true on success, false on failure, null if no annotations disabled. + * @since 1.8.0 + */ +function elgg_disable_annotations(array $options) { + if (!elgg_is_valid_options_for_batch_operation($options, 'annotations')) { + return false; } + + // if we can see hidden (disabled) we need to use the offset + // otherwise we risk an infinite loop if there are more than 50 + $inc_offset = access_get_show_hidden_status(); - // Add access controls - $query .= get_access_sql_suffix('e'); - if ($options['annotation_calculation'] === ELGG_ENTITIES_NO_VALUE) { - if ($options['group_by'] = sanitise_string($options['group_by'])) { - $query .= " GROUP BY {$options['group_by']}"; - } - - if ($options['order_by'] = sanitise_string($options['order_by'])) { - $query .= " ORDER BY {$options['order_by']}"; - } - - if ($options['limit']) { - $limit = sanitise_int($options['limit']); - $offset = sanitise_int($options['offset']); - $query .= " LIMIT $offset, $limit"; - } - - $dt = get_data($query, $options['callback']); - return $dt; - } else { - $result = get_data_row($query); - return $result->calculation; - } + $options['metastring_type'] = 'annotations'; + return elgg_batch_metastring_based_objects($options, 'elgg_batch_disable_callback', $inc_offset); } /** - * Returns an array of joins and wheres for use in annotations. + * Enables annotations based on $options. * - * @note The $pairs is reserved for name/value pairs if we want to implement those. + * @warning Unlike elgg_get_annotations() this will not accept an empty options array! * - * @param string $table The annotation table name or alias - * @param array $names An array of names - * @param array $values An array of values - * @param array $pairs Name / value pairs. Not currently used. - * @param bool $case_sensitive Should name and values be case sensitive? + * @warning In order to enable annotations, you must first use + * {@link access_show_hidden_entities()}. * - * @return array + * @param array $options An options array. {@See elgg_get_annotations()} + * @return bool|null true on success, false on failure, null if no metadata enabled. + * @since 1.8.0 */ -function elgg_get_annotation_sql($table, $names = null, $values = null, - $pairs = null, $case_sensitive = false) { - - if ((!$names && $names !== 0) - && (!$values && $values !== 0) - && (!$pairs && $pairs !== 0)) { - - return ''; +function elgg_enable_annotations(array $options) { + if (!$options || !is_array($options)) { + return false; } - $db_prefix = elgg_get_config('dbprefix'); - - // join counter for incremental joins. - $i = 1; - - // binary forces byte-to-byte comparision of strings, making - // it case- and diacritical-mark- sensitive. - // only supported on values. - $binary = ($case_sensitive) ? ' BINARY ' : ''; - - $access = get_access_sql_suffix($table); + $options['metastring_type'] = 'annotations'; + return elgg_batch_metastring_based_objects($options, 'elgg_batch_enable_callback'); +} - $return = array ( - 'joins' => array (), - 'wheres' => 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.0 + */ +function elgg_list_annotations($options) { + $defaults = array( + 'limit' => 25, + 'offset' => (int) max(get_input('annoff', 0), 0), ); - $wheres = array(); - - // get names wheres and joins - $names_where = ''; - if ($names !== NULL) { - if (!is_array($names)) { - $names = array($names); - } - - $sanitised_names = array(); - foreach ($names as $name) { - // normalise to 0. - if (!$name) { - $name = '0'; - } - $sanitised_names[] = '\'' . sanitise_string($name) . '\''; - } - - if ($names_str = implode(',', $sanitised_names)) { - $return['joins'][] = "JOIN {$db_prefix}metastrings msn on $table.name_id = msn.id"; - $names_where = "(msn.string IN ($names_str))"; - } - } - - // get values wheres and joins - $values_where = ''; - if ($values !== NULL) { - if (!is_array($values)) { - $values = array($values); - } - - $sanitised_values = array(); - foreach ($values as $value) { - // normalize to 0 - if (!$value) { - $value = 0; - } - $sanitised_values[] = '\'' . sanitise_string($value) . '\''; - } - - if ($values_str = implode(',', $sanitised_values)) { - $return['joins'][] = "JOIN {$db_prefix}metastrings msv on $table.value_id = msv.id"; - $values_where = "({$binary}msv.string IN ($values_str))"; - } - } - - if ($names_where && $values_where) { - $wheres[] = "($names_where AND $values_where AND $access)"; - } elseif ($names_where) { - $wheres[] = "($names_where AND $access)"; - } elseif ($values_where) { - $wheres[] = "($values_where AND $access)"; - } - - if ($where = implode(' AND ', $wheres)) { - $return['wheres'][] = "($where)"; - } + $options = array_merge($defaults, $options); - return $return; + return elgg_list_entities($options, 'elgg_get_annotations', 'elgg_view_annotation_list'); } +/** + * Entities interfaces + */ /** - * Returns entities based upon annotations. Accepts the same values as - * elgg_get_entities_from_metadata() but uses the annotations table. + * Returns entities based upon annotations. Also accepts all options available + * to elgg_get_entities() and elgg_get_entities_from_metadata(). * - * NB: Entity creation time is selected as max_time. To sort based upon + * Entity creation time is selected as maxtime. To sort based upon * this, pass 'order_by' => 'maxtime asc' || 'maxtime desc' * - * time_created in this case will be the time the annotation was created. - * * @see elgg_get_entities * @see elgg_get_entities_from_metadata * @@ -525,7 +336,7 @@ function elgg_get_annotation_sql($table, $names = null, $values = null, * * annotation_owner_guids => NULL|ARR guids for annotaiton owners * - * @return array + * @return mixed If count, int. If not count, array. false on errors. * @since 1.7.0 */ function elgg_get_entities_from_annotations(array $options = array()) { @@ -553,9 +364,10 @@ function elgg_get_entities_from_annotations(array $options = array()) { 'annotation_name_value_pair', 'annotation_owner_guid'); $options = elgg_normalise_plural_options_array($options, $singulars); + $options = elgg_entities_get_metastrings_options('annotation', $options); - if (!$options = elgg_entities_get_metastrings_options('annotation', $options)) { - return FALSE; + if (!$options) { + return false; } // special sorting for annotations @@ -581,66 +393,62 @@ function elgg_get_entities_from_annotations(array $options = array()) { * @see elgg_get_entities_from_annotations() * @see elgg_list_entities() * - * @return str + * @return string */ function elgg_list_entities_from_annotations($options = array()) { return elgg_list_entities($options, 'elgg_get_entities_from_annotations'); } /** - * 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 + * Get entities ordered by a mathematical calculation on annotation values * * @param array $options An options array: - * 'calculation' => The calculation to use. Must be a valid MySQL function. - * Defaults to sum. Result selected as 'calculated'. - * 'order_by' => The order for the sorting. Defaults to 'calculated desc'. - * - * @return mixed + * 'calculation' => The calculation to use. Must be a valid MySQL function. + * Defaults to sum. Result selected as 'annotation_calculation'. + * Don't confuse this "calculation" option with the + * "annotation_calculation" option to elgg_get_annotations(). + * This "calculation" option is applied to each entity's set of + * annotations and is selected as annotation_calculation for that row. + * See the docs for elgg_get_annotations() for proper use of the + * "annotation_calculation" option. + * 'order_by' => The order for the sorting. Defaults to 'annotation_calculation desc'. + * 'annotation_names' => The names of annotations on the entity. + * 'annotation_values' => The values of annotations on the entity. + * + * 'metadata_names' => The name of metadata on the entity. + * 'metadata_values' => The value of metadata on the entitiy. + * + * @return mixed If count, int. If not count, array. false on errors. */ function elgg_get_entities_from_annotation_calculation($options) { - global $CONFIG; - + $db_prefix = elgg_get_config('dbprefix'); $defaults = array( - 'calculation' => 'sum', - 'order_by' => 'calculated desc', + 'calculation' => 'sum', + 'order_by' => 'annotation_calculation desc' ); $options = array_merge($defaults, $options); - $function = sanitize_string(elgg_get_array_value('calculation', $options, 'sum', false)); + $function = sanitize_string(elgg_extract('calculation', $options, 'sum', false)); // you must cast this as an int or it sorts wrong. - $options['selects'][] = "$function(cast(msv.string as signed)) as calculated"; - $options['selects'][] = "msn.string as value"; - $options['order_by'] = 'calculated desc'; + $options['selects'][] = 'e.*'; + $options['selects'][] = "$function(cast(a_msv.string as signed)) as annotation_calculation"; + + // need our own join to get the values because the lower level functions don't + // add all the joins if it's a different callback. + $options['joins'][] = "JOIN {$db_prefix}metastrings a_msv ON n_table.value_id = a_msv.id"; + + // don't need access control because it's taken care of by elgg_get_annotations. + $options['group_by'] = 'n_table.entity_guid'; + + $options['callback'] = 'entity_row_to_elggstar'; - // need our own join to get the values. - $db_prefix = get_config('dbprefix'); - $options['joins'][] = "JOIN {$db_prefix}annotations calc_table on e.guid = calc_table.entity_guid"; - $options['joins'][] = "JOIN {$db_prefix}metastrings msv on calc_table.value_id = msv.id"; - $options['wheres'][] = "calc_table.name_id = n_table.name_id"; + // see #4393 + // @todo remove after the 'count' shortcut is removed from elgg_get_annotations() + $options['__egefac'] = true; - return elgg_get_entities_from_annotations($options); + return elgg_get_annotations($options); } /** @@ -653,119 +461,30 @@ function elgg_get_entities_from_annotation_calculation($options) { * @return string */ 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++; - } - } + $defaults = array( + 'calculation' => 'sum', + 'order_by' => 'annotation_calculation desc' + ); + $options = array_merge($defaults, $options); - return $deleted; + return elgg_list_entities($options, 'elgg_get_entities_from_annotation_calculation'); } /** - * Handler called by trigger_plugin_hook on the "export" event. + * Export the annotations for the specified entity * * @param string $hook 'export' - * @param string $entity_type 'all' + * @param string $type 'all' * @param mixed $returnvalue Default return value - * @param mixed $params List of params to export + * @param mixed $params Parameters determining what annotations to export * * @elgg_plugin_hook export all * - * @return mixed + * @return array + * @throws InvalidParameterException + * @access private */ -function export_annotation_plugin_hook($hook, $entity_type, $returnvalue, $params) { +function export_annotation_plugin_hook($hook, $type, $returnvalue, $params) { // Sanity check values if ((!is_array($params)) && (!isset($params['guid']))) { throw new InvalidParameterException(elgg_echo('InvalidParameterException:GUIDNotForExport')); @@ -776,9 +495,12 @@ function export_annotation_plugin_hook($hook, $entity_type, $returnvalue, $param } $guid = (int)$params['guid']; - $name = $params['name']; + $options = array('guid' => $guid, 'limit' => 0); + if (isset($params['name'])) { + $options['annotation_name'] = $params['name']; + } - $result = get_annotations($guid); + $result = elgg_get_annotations($options); if ($result) { foreach ($result as $r) { @@ -800,7 +522,7 @@ function export_annotation_plugin_hook($hook, $entity_type, $returnvalue, $param function get_annotation_url($id) { $id = (int)$id; - if ($extender = get_annotation($id)) { + if ($extender = elgg_get_annotation_from_id($id)) { return get_extender_url($extender); } return false; @@ -823,15 +545,16 @@ function elgg_annotation_exists($entity_guid, $annotation_type, $owner_guid = NU return FALSE; } - $entity_guid = (int)$entity_guid; - $annotation_type = sanitise_string($annotation_type); + $entity_guid = sanitize_int($entity_guid); + $owner_guid = sanitize_int($owner_guid); + $annotation_type = sanitize_string($annotation_type); - $sql = "select a.id" . - " FROM {$CONFIG->dbprefix}annotations a, {$CONFIG->dbprefix}metastrings m " . - " WHERE a.owner_guid={$owner_guid} AND a.entity_guid={$entity_guid} " . - " AND a.name_id=m.id AND m.string='{$annotation_type}'"; + $sql = "SELECT a.id FROM {$CONFIG->dbprefix}annotations a" . + " JOIN {$CONFIG->dbprefix}metastrings m ON a.name_id = m.id" . + " WHERE a.owner_guid = $owner_guid AND a.entity_guid = $entity_guid" . + " AND m.string = '$annotation_type'"; - if ($check_annotation = get_data_row($sql)) { + if (get_data_row($sql)) { return TRUE; } @@ -839,16 +562,57 @@ function elgg_annotation_exists($entity_guid, $annotation_type, $owner_guid = NU } /** + * Return the URL for a comment + * + * @param ElggAnnotation $comment The comment object + * @return string + * @access private + */ +function elgg_comment_url_handler(ElggAnnotation $comment) { + $entity = $comment->getEntity(); + if ($entity) { + return $entity->getURL() . '#item-annotation-' . $comment->id; + } + return ""; +} + +/** * Register an annotation url handler. * - * @param string $function_name The function. * @param string $extender_name The name, default 'all'. + * @param string $function_name The function. * * @return string */ -function register_annotation_url_handler($function_name, $extender_name = "all") { - return register_extender_url_handler($function_name, 'annotation', $extender_name); +function elgg_register_annotation_url_handler($extender_name = "all", $function_name) { + return elgg_register_extender_url_handler('annotation', $extender_name, $function_name); +} + +/** + * Register annotation unit tests + * + * @param string $hook + * @param string $type + * @param array $value + * @param array $params + * @return array + * @access private + */ +function annotations_test($hook, $type, $value, $params) { + global $CONFIG; + $value[] = $CONFIG->path . 'engine/tests/api/annotations.php'; + return $value; +} + +/** + * Initialize the annotation library + * @access private + */ +function elgg_annotations_init() { + elgg_register_annotation_url_handler('generic_comment', 'elgg_comment_url_handler'); + + elgg_register_plugin_hook_handler("export", "all", "export_annotation_plugin_hook", 2); + elgg_register_plugin_hook_handler('unit_test', 'system', 'annotations_test'); } -/** Register the hook */ -elgg_register_plugin_hook_handler("export", "all", "export_annotation_plugin_hook", 2); +elgg_register_event_handler('init', 'system', 'elgg_annotations_init'); |