/**
 * Utility method to get the absolute url of a reason page
 * 
 * Provide an entity when possible for a slight performance boost
 *
 * @author Nathan White
 * @param mixed entity or entity_id corresponding to a page or site
 * @return mixed string absolute url if successful; else null
 */
function reason_get_page_url($page_entity_or_id)
{
    static $builder;
    // lets use a singleton builder instance
    if (!isset($builder)) {
        $builder = new reasonPageUrl();
    }
    if (is_object($page_entity_or_id)) {
        $builder->set_id($page_entity_or_id->id());
        $builder->provide_page_entity($page_entity_or_id);
    } elseif (is_numeric($page_entity_or_id)) {
        $builder->set_id($page_entity_or_id);
    } else {
        trigger_error('reason_get_page_url was passed a parameter that is not an object or integer - a url cannot be generated');
        return null;
    }
    return $builder->get_url();
}
	/**
	 * Accepts a news item by reference and adds the url and site name
	 *
	 */
	function augment_entity(&$news_item_entity, &$valid_page_types)
	{
		static $url_builder;
		$site_id = $news_item_entity->get_value('site_id');
		$site = new entity($site_id);
		$site_unique_name = $site->get_value('unique_name');
		if (isset($this->augment_entity_handlers[$site_unique_name]))
		{
			$method_name = $this->augment_entity_handlers[$site_unique_name];
			return $this->$method_name($news_item_entity, $valid_page_types);
		}
		
		$pub_id = $news_item_entity->get_value('pub_id');
		$pub_id_array = (!is_array($pub_id)) ? array($pub_id) : $pub_id;
		
		$es = new entity_selector($site_id);
		$es->add_type(id_of('minisite_page'));
		$es->limit_tables(array('page_node'));
		$es->limit_fields(array('page_node.url_fragment'));
		$es->add_left_relationship($pub_id_array, relationship_id_of('page_to_publication'));
		$es->add_relation('page_node.custom_page IN ('.implode(",", $valid_page_types).')');
		$result = $es->run_one();
		
		if ($result)
		{
			$my_url = '';
			if (!isset($url_builder)) $url_builder = new reasonPageUrl();
			foreach ($result as $k=>$item)
			{
				$url_builder->set_id($item->id());
				$url_builder->provide_page_entity($item);
				$page_url = $url_builder->get_url_most_secure();
				if (strlen($page_url) > strlen($my_url)) $my_url = $page_url;
			}
			$parameters['story_id'] = $news_item_entity->id();
			$news_item_entity->set_value('source_name', $site->get_value('name'));
			$news_item_entity->set_value('source_url', reason_get_site_url($site));
			$news_item_entity->set_value('page_url', $my_url);
			$news_item_entity->set_value('parameters', $parameters);
			return true;
		}
		return false;
	}