/core/media/class.media.template.php

<?php

/**
 * BP-MEDIA MEDIA ITEM TEMPLATE CLASS
 * Operates main loop in templates when displaying media items
 *
 * @version 0.1.9
 * @since 0.1.9
 * @package BP-Media
 * @subpackage Media Item
 * @license GPL v2.0
 * @link http://code.google.com/p/buddypress-media/
 *
 * ========================================================================================================
 */

class BPM_media_template extends BPM_db_walker {


	var $pag_links;			// Pagination links for the current page in the template object

	// ============================================================================================================ //


        /**
         * Creates a template object filled with query result objects, based on user supplied parameters
         *
         * @version 0.1.9
         * @since 0.1.9
         *
	 * @param array $args | @see BPM_db::runSelectQuery() for array structure
	 * @param array $ctrl | @see BPM_db::runSelectQuery() for array structure
         * @return int | Exception on failure. Count of items returned by the query on success.
         */

	function __construct($args=null, $ctrl=null) {


		global $bpm;

		try {
			$x_items = $bpm->config->getKeyVal("media", "mediasList", "displayGridX");
			$y_items = $bpm->config->getKeyVal("media", "mediasList", "displayGridY");
		}
				catch (BPM_exception $child) {

			throw new BPM_exception( array(
				'numeric'=>1,
				'text'=>"Error reading from config class",
				'file'=>__FILE__, 'line'=>__LINE__, 'method'=>__METHOD__,
				'child'=>$child
			));
		}

		$ctrl_default = array(

			'page' => $defaults['page'] = isset( $_REQUEST['page'] ) ? intval( $_REQUEST['page'] ) :  1,
			"per_page"=>( $x_items * $y_items )
		);

		$ctrl = wp_parse_args($ctrl, $ctrl_default);


		$ctrl['format'] = "array_object";   // Force to be array_object to prevent accidentally
						    // passing wrong results format


		// Load the class
		// =========================================================================

		// Get total number of matching items in db

		try {
			$this->total_item_count = (int) self::query($args, null, array("count"=>true, "format"=>"var") );

			// Calculate number of pages
			$this->total_pages = ceil( (int) $this->total_item_count / (int) $ctrl["per_page"] );

			// Get matching items in db, up to limit set by "per_page" arg in $ctrl array
			$db_result = self::query($args, $ctrl);

		}
		catch (BPM_exception $child) {

			throw new BPM_exception( array(
				'numeric'=>2,
				'text'=>"Error during query operation",
				'data'=>array('args'=>$args, 'ctrl'=>$ctrl),
				'file'=>__FILE__, 'line'=>__LINE__, 'method'=>__METHOD__,
				'child'=>$child
			));
		}

		// Load the database results into objects and add them to the items array
		if($db_result){

			foreach( $db_result as $row ){

				$result = new BPM_media();

				foreach( $row as $col => $val ){

					$result->{$col} = $val;
				}
				unset($col, $val);

				$this->items[] = $result;

			}
			unset($row);

		}

		$this->item_count = count($this->items);
		$this->in_the_loop = false;
		$this->current_item = 0;


	    	// Build the pagination links string
		// =========================================================================

		$this->pag_links = paginate_links( array(

			'base' => add_query_arg( 'page', '%#%' ),
			'format' => '',
			'total' => $this->total_pages,
			'current' => (int) $ctrl["page"],
			'prev_text' => '&larr;',
			'next_text' => '&rarr;',
			'mid_size' => 1
		));

		return $this->item_count;

	}


        /**
         * Returns an array of Media Item data structures based on user supplied parameters
         *
         * @version 0.1.9
         * @since 0.1.9
         *
         * @param int $max | The maximum number of results to return from the database
         * @param string $owner_type | The system role of the member that uploaded the media
         * @param int $page | Used to set current page when traversing a multi-page data set
         * @param int $per_page | Number of objects to return per page when transversing multi-page data set
         *
         * @param int $privacy  | Sets the privacy level of the media item
         * @param bool $priv_override  | Makes system ignore privacy level when returning results
         *
         * @param string $ordersort  | Sets sort order of the returned data set
         * @param string $orderkey  | Sets which parameter to order the returned results by
         *
         * @param int array $owner_include | Only show items owned by member ID provided. For multiple ID's, pass as an array.
         * @param int array $owner_exclude | Only show items NOT owned by member ID provided. For multiple ID's, pass as an array.
         *
         * @param int array $member_include | Only show items the member ID provided has been tagged in. For multiple ID's, pass as an array.
         * @param int array $member_exclude | Only show items the member ID provided has NOT been tagget in. For multiple ID's, pass as an array.
         *
         * @param int $time_start | Only show items created after this timestamp. gmdate() format.
         * @param int $time_end | Only show items created before this timestamp. gmdate() format.
         *
         * @param string array $tag_include | Only show items tagged with the keyword provided. For multiple keywords, pass as an array.
         * @param string array $tag_exclude | Only show items NOT tagged with the keyword provided. For multiple keywords, pass as an array.
         *
         * @return int/array | Exception on failure. Int on count. Array of media item objects on success.
         *
         *
         *  In future releases, you'll be able to run geographic searches like:
         *  "Find all the items tagged with [keyword] within [distance] of [specific place]"
         *
         *  Bounding Box
         *  ------------
         *  Because finding all items within a *round* area is extremely CPU intensive, we use a bounding box
         *  to set the area to search in. When you run a query like "Find all [single females] within [5km] of
         *  [specific place] in [London]" you first set the bounding box to surround London, then run the radial
         *  search inside it. We'll provide an example in a future release.
         *
         *  @param float $geo_bound_lat_a | Bounding box upper left corner latitude.
         *  @param float $geo_bound_lon_a | Bounding box upper left corner longitude.
         *  @param float $geo_bound_lat_a | Bounding box lower right corner latitude.
         *  @param float $geo_bound_lon_a | Bounding box lower right corner longitude.
         *
         *  Datum
         *  -----
         *  This is the point you want to search outwards from. Obviously, it has to be inside the bounding
         *  box or you'll get zero results.
         *
         *  @param float $geo_datum_lat | Datum latitude.
         *  @param float $geo_datum_lon | Datum longitude.
         *
         *  Radius
         *  ------
         *  Radius from the datum, in kilometers, to search for items in.
         *
         *  @param float $geo_radius | Datum latitude.
         *
         */

	public function query($args=null, $columns=null, $ctrl=null) {


		global $bpm;

		// Default Args
		// ==============================================

		$args_default = array();

		    $args_default['owner_include'] = null;
		    $args_default['owner_exclude'] = null; // used to remove OWN uploads when viewing latest ones on site

		    $args_default['member_include'] = null;
		    $args_default['member_exclude'] = null; // used to remove OWN tag when viewing latest ones on site

		    $args_default['time_start'] = null;
		    $args_default['time_end'] = null;

		    $args_default['tag_include'] = null;
		    $args_default['tag_exclude'] = null;

		    $args_default['geo_bound_lat_a'] = null;
		    $args_default['geo_bound_lon_a'] = null;
		    $args_default['geo_bound_lat_b'] = null;
		    $args_default['geo_bound_lon_b'] = null;
		    $args_default['geo_datum_lat'] = null;
		    $args_default['geo_datum_lon'] = null;
		    $args_default['geo_radius'] = null;

		$args = wp_parse_args($args, $args_default);


		// Default Ctrl
		// ==============================================

		$ctrl_default = array();

		try {
			$x_items = $bpm->config->getKeyVal("media", "mediasList", "displayGridX");
			$y_items = $bpm->config->getKeyVal("media", "mediasList", "displayGridY");
		}
				catch (BPM_exception $child) {

			throw new BPM_exception( array(
				'numeric'=>1,
				'text'=>"Error reading from config class",
				'file'=>__FILE__, 'line'=>__LINE__, 'method'=>__METHOD__,
				'child'=>$child
			));
		}

                $ctrl_default['page'] = 1;
                $ctrl_default['per_page'] = ($x_items * $y_items);
                $ctrl_default['format'] = "array_object";

		$ctrl = wp_parse_args($ctrl, $ctrl_default);


		// Primary class options
		// #######################################################################

		$query_args = array();

		// Owner id passed to the function (used for showing a single member's
		// latest uploads, or the member's friends uploads)
                // =======================================================================
		if($args['owner_include']){

			$query_args[] = array("col"=>"owner_id", "op"=>"=", "val"=>$args['owner_include']);
		}

		if($args['owner_exclude']){

			$query_args[] = array("col"=>"owner_id", "op"=>"!=", "val"=>$args['owner_exclude']);
		}


                // Start time / end time passed to function. Note isset() is used because
		// datetime zenith (01-01-1970) == '0'
                // =======================================================================
                if( isset($args['time_start']) ){

			$query_args[] = array("col"=>"date_created", "op"=>">", "val"=>gmdate( "Y-m-d H:i:s", $args['time_start'] ) );

                }

                if( isset($args['time_end']) ){

			$query_args[] = array("col"=>"date_created", "op"=>"<", "val"=>gmdate( "Y-m-d H:i:s", $args['time_end'] ) );
                }


		// Joined class options
		// #######################################################################

		$join = array();


                // Member tag passed to the function (used for showing uploads tagged with
		// a member, or the member's friends)
                // =======================================================================
		if( $args['member_include'] || $args['member_exclude']){

			$join["BPM_mTag"] = array(
					    "on"=>array("pri"=>"id", "op"=>"=", "sec"=>"tagged_id"),
					    "args"=>array(
						    array("col"=>"status", "op"=>"=", "val"=>3)	// Tag is approved
					    )
			);

			// Include member tags
			if($args['member_include']){
				$join["BPM_mTag"]["args"][] = array("col"=>"tagged_id", "op"=>"=", "val"=>$args['member_include']);
			}

			// Exclude member tags
			if($args['member_exclude']){
				$join["BPM_mTag"]["args"][] = array("col"=>"tagged_id", "op"=>"!=", "val"=>$args['member_exclude']);
			}

                }


                // Keyword tag passed to the function (used for showing uploads tagged
		// with a member, or the member's friends)
                // =======================================================================
		if( $args['tag_include'] || $args['tag_exclude']){

			$join["BPM_keyword"] = array(
					    "on"=>array("pri"=>"id", "op"=>"=", "sec"=>"media_id"),
					    "args"=>array(
						    array("col"=>"status", "op"=>"=", "val"=>2)	// Tag is approved
					    )
			);

			// Include keyword tags
			if($args['tag_include']){
				$join["BPM_keyword"]["args"][] = array("col"=>"keyword", "op"=>"=", "val"=>$args['tag_include']);
			}

			// Exclude keyword tags
			if($args['tag_exclude']){
				$join["BPM_keyword"]["args"][] = array("col"=>"keyword", "op"=>"!=", "val"=>$args['tag_exclude']);
			}

                }

		// Query
		// #######################################################################

		$db = new BPM_db();

		if($join){

			$primary = array(
				    "class"=>BPM_media::_struct(),
				    "args"=>$query_args
			);

			try {
			$result = $db->runSelectQueryJoin($primary, $join, $columns, $ctrl);
		}
					catch (BPM_exception $child) {

				throw new BPM_exception( array(
					'numeric'=>2,
					'text'=>"Error during query operation",
					'data'=>array('primary'=>$primary, 'join'=>$join, 'columns'=>$columns, 'ctrl'=>$ctrl),
					'file'=>__FILE__, 'line'=>__LINE__, 'method'=>__METHOD__,
					'child'=>$child
				));
			}
		}
		else {

			try {
				$result = $db->runSelectQuery( BPM_media::_struct(), $query_args, $columns, $ctrl);
			}
			catch (BPM_exception $child) {

				throw new BPM_exception( array(
					'numeric'=>3,
					'text'=>"Error during query operation",
					'data'=>array('args'=>$query_args, 'columns'=>$columns, 'ctrl'=>$ctrl),
					'file'=>__FILE__, 'line'=>__LINE__, 'method'=>__METHOD__,
					'child'=>$child
				));
			}
		}

		return $result;

	}



} // End of class BPM_media_template

?>