<?php
/**
 * Piwik - Open source web analytics
 * 
 * @link http://piwik.org
 * @license http://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
 * @version $Id: BeautifyRangeLabels.php 6353 2012-05-28 17:29:23Z SteveG $
 * 
 * @category Piwik
 * @package Piwik
 */

/**
 * A DataTable filter that replaces range label columns with prettier,
 * human-friendlier versions.
 *
 * When reports that summarize data over a set of ranges (such as the
 * reports in the VisitorInterest plugin) are archived, they are
 * archived with labels that read as: '$min-$max' or '$min+'. These labels
 * have no units and can look like '1-1'.
 *
 * This filter can be used to clean up and add units those range labels. To
 * do this, you supply a string to use when the range specifies only
 * one unit (ie '1-1') and another format string when the range specifies
 * more than one unit (ie '2-2', '3-5' or '6+').
 *
 * This filter can also be extended to beautify ranges differently based
 * on the range values.
 */
class Piwik_DataTable_Filter_BeautifyRangeLabels extends Piwik_DataTable_Filter_ColumnCallbackReplace
{
	/**
	 * The string to use when the range being beautified is between 1-1 units.
	 * @var string
	 */
	protected $labelSingular;

	/**
	 * The format string to use when the range being beautified references more than
	 * one unit.
	 * @var string
	 */
	protected $labelPlural;

	/**
	 * Constructor.
	 *
	 * @param Piwik_DataTable  $table          The DataTable that will be filtered.
	 * @param string           $labelSingular  The string to use when the range being beautified
	 *                                         is equal to '1-1 units'.
	 * @param string           $labelPlural    The string to use when the range being beautified
	 *                                         references more than one unit. This must be a format
	 *                                         string that takes one string parameter.
	 */
	public function __construct( $table, $labelSingular, $labelPlural )
	{
		parent::__construct($table, 'label', array($this, 'beautify'), array());
		
		$this->labelSingular = $labelSingular;
		$this->labelPlural = $labelPlural;
	}

	/**
	 * Beautifies a range label and returns the pretty result.
	 *
	 * @param string  $value  The range string. This must be in either a '$min-$max' format
	 *                        a '$min+' format.
	 * @return string  The pretty range label.
	 */
	public function beautify( $value )
	{
		// if there's more than one element, handle as a range w/ an upper bound
		if (strpos($value, "-") !== false)
		{
			// get the range
			sscanf($value, "%d - %d", $lowerBound, $upperBound);
			
			// if the lower bound is the same as the upper bound make sure the singular label
			// is used
			if ($lowerBound == $upperBound)
			{
				return $this->getSingleUnitLabel($value, $lowerBound);
			}
			else
			{
				return $this->getRangeLabel($value, $lowerBound, $upperBound);
			}
		}
		// if there's one element, handle as a range w/ no upper bound
		else
		{
			// get the lower bound
			sscanf($value, "%d", $lowerBound);
		
			if ($lowerBound !== NULL)
			{
				$plusEncoded = urlencode('+');
				$plusLen = strlen($plusEncoded);
				$len = strlen($value);

				// if the label doesn't end with a '+', append it
				if ($len < $plusLen || substr($value, $len - $plusLen) != $plusEncoded)
				{
					$value .= $plusEncoded;
				}
			
				return $this->getUnboundedLabel($value, $lowerBound);
			}
			else
			{
				// if no lower bound can be found, this isn't a valid range. in this case
				// we assume its a translation key and try to translate it.
				return Piwik_Translate(trim($value));
			}
		}
	}

	/**
	 * Beautifies and returns a range label whose range spans over one unit, ie
	 * 1-1, 2-2 or 3-3.
	 *
	 * This function can be overridden in derived types to customize beautifcation
	 * behavior based on the range values.
	 *
	 * @param string  $oldLabel    The original label value.
	 * @param int     $lowerBound  The lower bound of the range.
	 * @return string  The pretty range label.
	 */
	public function getSingleUnitLabel( $oldLabel, $lowerBound )
	{
		if ($lowerBound == 1)
		{
			return $this->labelSingular;
		}
		else
		{
			return sprintf($this->labelPlural, $lowerBound);
		}
	}

	/**
	 * Beautifies and returns a range label whose range is bounded and spans over
	 * more than one unit, ie 1-5, 5-10 but NOT 11+.
	 *
	 * This function can be overridden in derived types to customize beautifcation
	 * behavior based on the range values.
	 * 
	 * @param string  $oldLabel    The original label value.
	 * @param int     $lowerBound  The lower bound of the range.
	 * @param int     $upperBound  The upper bound of the range.
	 * @return string  The pretty range label.
	 */
	public function getRangeLabel( $oldLabel, $lowerBound, $upperBound )
	{
		return sprintf($this->labelPlural, $oldLabel);
	}
	
	/**
	 * Beautifies and returns a range label whose range is unbounded, ie
	 * 5+, 10+, etc.
	 *
	 * This function can be overridden in derived types to customize beautifcation
	 * behavior based on the range values.
	 * 
	 * @param string  $oldLabel    The original label value.
	 * @param int     $lowerBound  The lower bound of the range.
	 * @return string  The pretty range label.
	 */
	public function getUnboundedLabel( $oldLabel, $lowerBound )
	{
		return sprintf($this->labelPlural, $oldLabel);
	}
}
