Added generic listing and pagination functions

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

6 files changed, 258 insertions, 23 deletions

diff --git a/engine/lib/elgglib.php b/engine/lib/elgglib.php
index 3670cd884..dae53daa9 100644
--- a/engine/lib/elgglib.php
+++ b/engine/lib/elgglib.php
@@ -239,6 +239,54 @@
 		}

 		

 	/**

+	 * Returns a view of a list of entities, plus navigation. It is intended that this function

+	 * be called from other wrapper functions.

+	 * 

+	 * @see list_entities

+	 * @see list_user_objects

+	 * @see list_user_friends_objects

+	 * @see list_entities_from_metadata

+	 * @see list_entities_from_metadata_multi

+	 * @see list_entities_from_relationships

+	 * @see list_site_members

+	 *

+	 * @param array $entities List of entities

+	 * @param int $count The total number of entities across all pages

+	 * @param int $offset The current indexing offset

+	 * @param int $limit The number of entities to display per page

+	 * @return string The list of entities

+	 */

+		function elgg_view_entity_list($entities, $count, $offset, $limit) {

+			

+			$count = (int) $count;

+			$offset = (int) $offset;

+			$limit = (int) $limit;

+			

+			$html = "";

+			

+			$nav = elgg_view('navigation/pagination',array(

+			

+												'baseurl' => $_SERVER['REQUEST_URI'],

+												'offset' => $offset,

+												'count' => $count,

+			

+														));

+			

+			$html .= $nav;

+														

+			if (is_array($entities) && sizeof($entities) > 0) {

+				foreach($entities as $entity) {

+					$html .= elgg_view_entity($entity, "", false);

+				}

+			}

+			

+			$html .= $nav;

+			

+			return $html;

+			

+		}

+		

+	/**

 	 * Displays an internal layout for the use of a plugin canvas.

 	 * Takes a variable number of parameters, which are made available 

 	 * in the views as $vars['area1'] .. $vars['areaN'].

diff --git a/engine/lib/entities.php b/engine/lib/entities.php
index e9f795d11..c57a13d46 100644
--- a/engine/lib/entities.php
+++ b/engine/lib/entities.php
@@ -1016,7 +1016,7 @@
 	 * @param boolean $count Set to true to get a count rather than the entities themselves (limits and offsets don't apply in this context). Defaults to false.
 	 * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites. 
 	 */
-	function get_entities($type = "", $subtype = "", $owner_guid = 0, $order_by = "time_created desc", $limit = 10, $offset = 0, $count = false, $site_guid = 0)
+	function get_entities($type = "", $subtype = "", $owner_guid = 0, $order_by = "", $limit = 10, $offset = 0, $count = false, $site_guid = 0)
 	{
 		global $CONFIG;
 		
@@ -1025,7 +1025,8 @@
 		
 		$type = sanitise_string($type);
 		$subtype = get_subtype_id($type, $subtype);
-		
+		

+		if ($order_by == "") $order_by = "time_created desc";
 		$order_by = sanitise_string($order_by);
 		$limit = (int)$limit;
 		$offset = (int)$offset;
@@ -1072,6 +1073,27 @@
 			return $total->total;
 		}
 	}
+	

+	/**

+	 * Returns a viewable list of entities

+	 *

+	 * @see elgg_view_entity_list

+	 * 

+	 * @param string $type The type of entity (eg "user", "object" etc)

+	 * @param string $subtype The arbitrary subtype of the entity

+	 * @param int $owner_guid The GUID of the owning user

+	 * @param int $limit The number of entities to display per page (default: 10)

+	 * @return string A viewable list of entities

+	 */

+	function list_entities($type= "", $subtype = "", $owner_guid = 0, $limit = 10) {

+		

+		$offset = (int) get_input('offset');

+		$count = get_entities($type, $subtype, $owner_guid, "", $limit, $offset, true);

+		$entities = get_entities($type, $subtype, $owner_guid, "", $limit, $offset);

+

+		return elgg_view_entity_list($entities, $count, $offset, $limit);

+		

+	}

 	
 	/**
 	 * Delete a given entity.
diff --git a/engine/lib/metadata.php b/engine/lib/metadata.php
index 7923039b1..d01ce0985 100644
--- a/engine/lib/metadata.php
+++ b/engine/lib/metadata.php
@@ -370,17 +370,18 @@
 	 * @param string $order_by Optional ordering.
 	 * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.
 	 */
-	function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $entity_subtype = "", $limit = 10, $offset = 0, $order_by = "e.time_created desc", $site_guid = 0)
+	function find_metadata($meta_name = "", $meta_value = "", $entity_type = "", $entity_subtype = "", $limit = 10, $offset = 0, $order_by = "", $site_guid = 0)
 	{
 		global $CONFIG;
 		
 		$meta_n = get_metastring_id($meta_name);
-		$meta_v = get_metastring_id($meta_value);
-			
+		$meta_v = get_metastring_id($meta_value);

+		
 		$entity_type = sanitise_string($entity_type);
 		$entity_subtype = get_subtype_id($entity_type, $entity_subtype);
 		$limit = (int)$limit;
-		$offset = (int)$offset;
+		$offset = (int)$offset;

+		if ($order_by == "") $order_by = "e.time_created desc";
 		$order_by = sanitise_string($order_by);
 		$site_guid = (int) $site_guid;
 		if ($site_guid == 0)
@@ -419,9 +420,12 @@
 	 * @param int $limit 
 	 * @param int $offset
 	 * @param string $order_by Optional ordering.

-	 * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.
+	 * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.

+	 * @param true|false $count If set to true, returns the total number of entities rather than a list. (Default: false)

+	 * 

+	 * @return int|array A list of entities, or a count if $count is set to true
 	 */
-	function get_entities_from_metadata($meta_name, $meta_value = "", $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "e.time_created desc", $site_guid = 0)
+	function get_entities_from_metadata($meta_name, $meta_value = "", $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false)
 	{
 		global $CONFIG;
 		
@@ -431,7 +435,8 @@
 		$entity_type = sanitise_string($entity_type);
 		$entity_subtype = get_subtype_id($entity_type, $entity_subtype);
 		$limit = (int)$limit;
-		$offset = (int)$offset;
+		$offset = (int)$offset;

+		if ($order_by == "") $order_by = "e.time_created desc";
 		$order_by = sanitise_string($order_by);

 		$site_guid = (int) $site_guid;

 		$owner_guid = (int) $owner_guid;

@@ -454,14 +459,50 @@
 			$where[] = "e.site_guid = {$site_guid}";

 		if ($owner_guid > 0)

 			$where[] = "e.owner_guid = {$owner_guid}";
-		
-		$query = "SELECT distinct e.* from {$CONFIG->dbprefix}entities e JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid where";
+		

+		if (!$count) {

+			$query = "SELECT distinct e.* "; 

+		} else {

+			$query = "SELECT count(e.guid) as total ";

+		}

+			
+		$query .= "from {$CONFIG->dbprefix}entities e JOIN {$CONFIG->dbprefix}metadata m on e.guid = m.entity_guid where";
 		foreach ($where as $w)
 			$query .= " $w and ";
-		$query .= get_access_sql_suffix("e"); // Add access controls
-		$query .= " order by $order_by limit $offset, $limit"; // Add order and limit
-
-		return get_data($query, "entity_row_to_elggstar");
+		$query .= get_access_sql_suffix("e"); // Add access controls

+		

+		if (!$count) {
+			$query .= " order by $order_by limit $offset, $limit"; // Add order and limit
+			return get_data($query, "entity_row_to_elggstar");

+		} else {

+			if ($row = get_data_row($query))

+				return $row->total;

+		}

+		return false;
+	}

+	

+	/**

+	 * Return a list of entities suitable for display based on the given search criteria.

+	 * 

+	 * @see elgg_view_entity_list

+	 * 

+	 * @param mixed $meta_name Metadata name to search on

+	 * @param mixed $meta_value The value to match, optionally

+	 * @param string $entity_type The type of entity to look for, eg 'site' or 'object'

+	 * @param string $entity_subtype The subtype of the entity

+	 * @param int $limit Number of entities to display per page

+	 * 

+	 * @return string A list of entities suitable for display

+	 */

+	function list_entities_from_metadata($meta_name, $meta_value = "", $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10) {

+		

+		$offset = (int) get_input('offset');

+		$limit = (int) $limit;

+		$count = get_entities_from_metadata($meta_name, $meta_value, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", 0, true);

+		$entities = get_entities_from_metadata($meta_name, $meta_value, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", 0, false);

+		

+		return elgg_view_entity_list($entities, $count, $offset, $limit);

+		

 	}

 

 	/**

@@ -474,9 +515,10 @@
 	 * @param int $offset

 	 * @param string $order_by Optional ordering.

 	 * @param int $site_guid The site to get entities for. Leave as 0 (default) for the current site; -1 for all sites.

-	 * @return array List of ElggEntities

+	 * @param true|false $count If set to true, returns the total number of entities rather than a list. (Default: false)

+	 * @return int|array List of ElggEntities, or the total number if count is set to false

 	 */

-	function get_entities_from_metadata_multi($meta_array, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "e.time_created desc", $site_guid = 0)

+	function get_entities_from_metadata_multi($meta_array, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10, $offset = 0, $order_by = "", $site_guid = 0, $count = false)

 	{

 		global $CONFIG;

 		

@@ -503,6 +545,7 @@
 		$entity_subtype = get_subtype_id($entity_type, $entity_subtype);

 		$limit = (int)$limit;

 		$offset = (int)$offset;

+		if ($order_by == "") $order_by = "e.time_created desc";

 		$order_by = sanitise_string($order_by);

 		$owner_guid = (int) $owner_guid;

 		

@@ -521,13 +564,50 @@
 		if ($owner_guid > 0)

 			$where[] = "e.owner_guid = {$owner_guid}";

 		

-		$query = "SELECT distinct e.* from {$CONFIG->dbprefix}entities e {$join} where";

+		if ($count) {

+			$query = "SELECT count(e.guid) as total ";

+		} else {

+			$query = "SELECT distinct e.* "; 

+		}

+			

+		$query .= " from {$CONFIG->dbprefix}entities e {$join} where";

 		foreach ($where as $w)

 			$query .= " $w and ";

 		$query .= get_access_sql_suffix("e"); // Add access controls

-		$query .= " order by $order_by limit $offset, $limit"; // Add order and limit

-

-		return get_data($query, "entity_row_to_elggstar");

+		

+		if (!$count) {

+			$query .= " order by $order_by limit $offset, $limit"; // Add order and limit

+			return get_data($query, "entity_row_to_elggstar");

+		} else {

+			if ($count = get_data_row($query)) {

+				return $count->total;

+			}

+		}

+		return false;

+	}

+	

+	/**

+	 * Returns a viewable list of entities based on the given search criteria.

+	 *

+	 * @see elgg_view_entity_list

+	 * 

+	 * @param array $meta_array Array of 'name' => 'value' pairs

+	 * @param string $entity_type The type of entity to look for, eg 'site' or 'object'

+	 * @param string $entity_subtype The subtype of the entity.

+	 * @param int $limit 

+	 * @param int $offset

+	 * @param string $order_by Optional ordering.

+	 * @return string List of ElggEntities suitable for display

+	 */

+	function list_entities_from_metadata_multi($meta_array, $entity_type = "", $entity_subtype = "", $owner_guid = 0, $limit = 10) {

+		

+		$offset = (int) get_input('offset');

+		$limit = (int) $limit;

+		$count = get_entities_from_metadata_multi($meta_array, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", $site_guid, true);

+		$entities = get_entities_from_metadata_multi($meta_array, $entity_type, $entity_subtype, $owner_guid, $limit, $offset, "", $site_guid, false);

+	

+		return elgg_view_entity_list($entities, $count, $offset, $limit);

+		

 	}
 	
 	/**
diff --git a/engine/lib/relationships.php b/engine/lib/relationships.php
index ebcd1ef88..f715f4a58 100644
--- a/engine/lib/relationships.php
+++ b/engine/lib/relationships.php
@@ -485,6 +485,31 @@
 		}
 		return false;
 		
+	}

+

+	/**

+	 * Returns a viewable list of entities by relationship

+	 *

+	 * @see elgg_view_entity_list

+	 * 

+	 * @param string $relationship The relationship eg "friends_of"

+	 * @param int $relationship_guid The guid of the entity to use query

+	 * @param bool $inverse_relationship Reverse the normal function of the query to instead say "give me all entities for whome $relationship_guid is a $relationship of"

+	 * @param string $type The type of entity (eg 'object')

+	 * @param string $subtype The entity subtype

+	 * @param int $owner_guid The owner (default: all)

+	 * @param int $limit The number of entities to display on a page

+	 * @return string The viewable list of entities

+	 */

+	function list_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship = false, $type = "", $subtype = "", $owner_guid = 0, $limit = 0) {

+		

+		$limit = (int) $limit;

+		$offset = (int) get_input('offset');

+		$count = get_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship, $type, $subtype, $owner_guid, "", $limit, 0, true);

+		$entities = get_entities_from_relationship($relationship, $relationship_guid, $inverse_relationship, $type, $subtype, $owner_guid, "", $limit, 0, true);

+		

+		return elgg_view_entity_list($entities, $count, $offset, $Limit);

+		

 	}
 	
 	/**** HELPER FUNCTIONS FOR RELATIONSHIPS OF TYPE 'ATTACHED' ****/
diff --git a/engine/lib/sites.php b/engine/lib/sites.php
index c8636fdc8..9d81c7364 100644
--- a/engine/lib/sites.php
+++ b/engine/lib/sites.php
@@ -367,6 +367,24 @@
 		$offset = (int)$offset;
 		
 		return get_entities_from_relationship("member_of_site", $site_guid, true, "user", "", 0, "time_created desc", $limit, $offset);
+	}

+	

+	/**

+	 * Display a list of site members

+	 *

+	 * @param int $site_guid The GUID of the site

+	 * @param int $limit The number of members to display on a page

+	 * @return string A displayable list of members

+	 */

+	function list_site_members($site_guid, $limit = 10) {

+		

+		$offset = (int) get_input('offset');

+		$limit = (int) $limit;

+		$count = (int) get_entities_from_relationship("member_of_site", $site_guid, true, "user", "", 0, "time_created desc", $limit, $offset, true);

+		$entities = get_site_members($site_guid, $limit, $offset);

+		

+		return elgg_view_entity_list($entities, $count, $offset, $limit);

+		

 	}
 	
 	/**
@@ -415,8 +433,8 @@
 		$offset = (int)$offset;
 		
 		return get_entities_from_relationship("member_of_site", $site_guid, true, "object", $subtype, 0, "time_created desc", $limit, $offset);
-	}
-	
+	}

+	

 	/**
 	 * Add a collection to a site.
 	 * 
diff --git a/engine/lib/users.php b/engine/lib/users.php
index 5065a633a..16e7a2c5f 100644
--- a/engine/lib/users.php
+++ b/engine/lib/users.php
@@ -526,6 +526,27 @@
 		$total = get_entities('object', $subtype, $user_guid, "time_created desc", null, null, true);

 		return $total;

 	}

+

+	/**

+	 * Displays a list of user objects of a particular subtype, with navigation.

+	 *

+	 * @see elgg_view_entity_list

+	 * 

+	 * @param int $user_guid The GUID of the user

+	 * @param string $subtype The object subtype

+	 * @param int $limit The number of entities to display on a page

+	 * @return string The list in a form suitable to display

+	 */

+	function list_user_objects($user_guid, $subtype = "", $limit = 10) {

+		

+		$offset = (int) get_input('offset');

+		$limit = (int) $limit;

+		$count = (int) count_user_objects($user_guid, $subtype);

+		$entities = get_user_objects($user_guid, $subtype, $limit, $offset);

+		

+		return elgg_view_entity_list($entities, $count, $offset, $limit);

+		
+	}

 	

 /**

 	 * Obtains a list of objects owned by a user's friends

@@ -566,6 +587,27 @@
 	}

 

 	/**

+	 * Displays a list of a user's friends' objects of a particular subtype, with navigation.

+	 *

+	 * @see elgg_view_entity_list

+	 * 

+	 * @param int $user_guid The GUID of the user

+	 * @param string $subtype The object subtype

+	 * @param int $limit The number of entities to display on a page

+	 * @return string The list in a form suitable to display

+	 */

+	function list_user_friends_objects($user_guid, $subtype = "", $limit = 10) {

+		

+		$offset = (int) get_input('offset');

+		$limit = (int) $limit;

+		$count = (int) count_user_friends_objects($user_guid, $subtype);

+		$entities = get_user_friends_objects($user_guid, $subtype, $limit, $offset);

+		

+		return elgg_view_entity_list($entities, $count, $offset, $limit);

+		

+	}

+	

+	/**

 	 * Get user objects by an array of metadata

 	 *

 	 * @param int $user_guid The GUID of the owning user