<?

	/**
	 * The FORMfields Library
	 * Copyright 2005-2007 Brain Book Software LLC
	 * For complete documentation, please visit http://www.formfields.com
	 */

	require_once(dirname(__FILE__) . "/FormField.php");
	require_once(dirname(__FILE__) . "/../TableSet.php");
	
	/**
	 * CheckboxGroupField is a field for editig a group of checkboxes. 
	 * This field even allows you to format the group of checkboxes 
	 * into several rows and columns to minimize the length of your form.
	 * @package FORMfields.fields
	 * @since FORMfields v3.0
	 */
	class CheckboxGroupField extends FormField 
	{
		/**
		 * An array of checkbox sub fields.
		 * @since FORMfields v3.0
		 */
		var $checkboxes;

		/**
		 * A sub field for the other choice string.
		 * @since FORMfields v3.0
		 */
		var $otherChoice;

		/**
		 * True if the other choice should displayed.
		 * @since FORMfields v3.0
		 */
		var $includeOtherChoice = false;

		/**
		 * True if this is a multiple value field.
		 * @since FORMfields v3.0
		 */
		var $multiValues = true;

		/**
		 * The number of rows into which to format the checkboxes.
		 * @since FORMfields v3.0
		 */
		var $rows = null;

		/**
		 * The number of columns into which to format the checkboxes.
		 * @since FORMfields v3.0
		 */
		var $cols = null;
		
		/**
		 * True if an empty sub field constitutes an invalid value.
		 * @since FORMfields v3.0
		 */
		var $subFieldsCannotBeEmpty = false;

		/**
		 * Creates a new CheckboxGroupField.
		 * @param string name the name of the form field. This value must not be a SQL reserved word and should follow all the standard variable naming conventions in PHP.
		 * @param string label this form field's label. The label is the printable text that is typically displayed on the left side of the field.
		 * @param int required Sets whether the field must be filled in and whether it looks like it must be filled in: FORM_FIELD_REQUIRED, FORM_FIELD_NOT_REQUIRED, FORM_FIELD_LOOKS_REQUIRED or FORM_FIELD_REQUIRED_NO_LOOK
		 * @param array options A string array of options associated with each checkbox
		 * @param int rows The number of rows used to display the radio button choices or if null is supplied each button will appear on it's own line. The rows restriction is ranked higher than the cols restriction.
		 * @param int cols The number of columns used to display the radio button choices. Defaulted to 1.
		 * @param boolean includeOtherChoice True if the other field should be displayed so that the user can enter an other string when their desired selection doesn't exist
		 * @see FORM_FIELD_REQUIRED
		 * @see FORM_FIELD_NOT_REQUIRED
		 * @see FORM_FIELD_LOOKS_REQUIRED
		 * @see FORM_FIELD_REQUIRED_NO_LOOK
		 * @since FORMfields v1.0
		 */
		function __construct($name, $label, $required, $options, $rows=null, $cols=1, $includeOtherChoice=false) 
		{
			parent::__construct($name, $label, $required);
			
			// Create the checkboxes
			$i = 0;
			foreach ($options as $option) {
				$boxName =  $name . FORM_FIELD_SEP . $i;
				$this->checkboxes[$boxName] = new CheckboxField($boxName, $option);
				$this->addSubField($this->checkboxes[$boxName]);
				$i++;
			}
			
			$this->otherChoice = new TextField($name . FF_SEP . "other", FfLH::t("Other") . ":", FORM_FIELD_NOT_REQUIRED, 40, 1, null);
			
			$this->otherBox = new CheckboxField($name . FF_SEP . "other_box", FfLH::t("Other") . ":");
			$this->otherBox->setExtraHtml("onclick=\"otherChoice=document.getElementById('" . $this->otherChoice->getId() . "');if(!this.checked)otherChoice.value='';\"");

			$this->otherChoice->setExtraHtml("onclick=\"otherBox=document.getElementById('" . $this->otherBox->getId() . "');otherBox.checked=true;\" onkeydown=\"otherBox=document.getElementById('" . $this->otherBox->getId() . "');if(this.value.length>0)otherBox.checked=true;\"");

			$this->addSubField($this->otherChoice);
			$this->addSubField($this->otherBox);
			
			$this->cols = $cols;
			if ($rows != null)
				$this->rows = $rows;
			else
				$this->rows = sizeof($this->checkboxes);
				
			$this->includeOtherChoice = $includeOtherChoice;
		}
		
		/**
		 * Creates a new CheckboxGroupField.
		 * @param string name the name of the form field. This value must not be a SQL reserved word and should follow all the standard variable naming conventions in PHP.
		 * @param string label this form field's label. The label is the printable text that is typically displayed on the left side of the field.
		 * @param int required Sets whether the field must be filled in and whether it looks like it must be filled in: FORM_FIELD_REQUIRED, FORM_FIELD_NOT_REQUIRED, FORM_FIELD_LOOKS_REQUIRED or FORM_FIELD_REQUIRED_NO_LOOK
		 * @param array options A string array of options associated with each checkbox
		 * @param int rows The number of rows used to display the radio button choices or if null is supplied each button will appear on it's own line. The rows restriction is ranked higher than the cols restriction.
		 * @param int cols The number of columns used to display the radio button choices. Defaulted to 1.
		 * @param boolean includeOtherChoice True if the other field should be displayed so that the user can enter an other string when their desired selection doesn't exist
		 * @see FORM_FIELD_REQUIRED
		 * @see FORM_FIELD_NOT_REQUIRED
		 * @see FORM_FIELD_LOOKS_REQUIRED
		 * @see FORM_FIELD_REQUIRED_NO_LOOK
		 * @since FORMfields v1.0
		 * @deprecated deprecated as this constructor syntax is not expected in PHP 5 - will be removed once PHP 5 becomes a minimum requirement for FORMfields
		 */
		function CheckboxGroupField($name, $label, $required, $options, $rows=null, $cols=1, $includeOtherChoice=false)
		{
			$this->__construct($name, $label, $required, $options, $rows, $cols, $includeOtherChoice);
		}

		/**
		 * Returns the HTML to display a single checkbox.
		 * @param CheckboxField checkbox a checkbox to display
		 * @return the HTML to display a single checkbox
		 * @since FORMfields v3.0
		 */
		function getSingleCheckboxTag($checkbox)
		{
			return
				$checkbox->getEditableFieldTag()
				. "<label class=\"isValid\" for=\"" . $checkbox->getId() . "\" style=\"width:auto;display:inline;\">" . htmlspecialchars($checkbox->getLabel()) . "</label>";
		}

		/**
		 * Returns the HTML used to display the input portion of this
		 * field.
		 * @return string the HTML used to display the input portion of this field
		 * @since FORMfields v3.0
		 */
		function getEditableFieldTag() 
		{
			$html = "";

			$choices = array();
			foreach ($this->checkboxes as $i=>$checkbox) {
				$choices[$i] = $this->getSingleCheckboxTag($checkbox);
			}
			$ts = new TableSet(null, "ffTableSetClear");
			$ts->loadRowsAndColumns($choices, $this->rows, $this->cols);
			if ($this->includeOtherChoice) {
				$ts->addRow(array("<table style=\"border-collapse:collapse;border-spacing:0px;\" cellspacing=\"0\" cellpadding=\"0\"><tr><td>" . $this->getSingleCheckboxTag($this->otherBox) . "</td><td> " . $this->otherChoice->getFieldTag() . "</td></tr></table>"));
			}
			$html .= $ts->getTableTag();

			return $html;
		}

		/**
		 * Returns the value of this form field.
		 * @return array a string array of options
		 * @since FORMfields v3.0
		 */
		function getValue() 
		{
			$value = array();
			foreach($this->checkboxes as $checkbox) {
				if (!$checkbox->isEmpty()) {
					array_push($value, $checkbox->getLabel());
				}
			}

			if ($this->otherBox->getValue() && $this->otherChoice->getValue()) {
				array_push($value, $this->otherChoice->getValue());
			}

			return $value;
		}

		/**
		 * Sets the value of this field.
		 * @param array values an array of strings equal to the selected options
		 * @since FORMfields v3.0
		 */
		function setValue($values)
		{
			parent::setValue($values);
			
			if (is_array($values)) {
				$this->clearValue();
				foreach ($values as $value) {
					$match = false;
					foreach ($this->checkboxes as $i=>$checkbox) {
						if ($checkbox->getLabel() === $value) {
							$this->checkboxes[$i]->setValue("true");
							$match = true;
							break;
						}
					}
					// If there wasn't a match then we assume it is the other value
					if ($this->includeOtherChoice && !$match && !$this->isBlank($value)) {
						$this->otherChoice->setValue($value);
						$this->otherBox->setValue("true");
						//$this->otherChoice->setEnabled(true);
					}
				}
			}
		}

		/**
		 * Sets the database value of this field. A database
		 * value can be different than the field's actual value. For
		 * example a phone number may have the value 
		 * "973-746-3233" but its database value would be "9737463233"
		 * @param string value a comma separated list of values that is comma escaped
		 * @since FORMfields v3.0
		 */
		function setDbValue($value) 
		{
			$this->setValue(FfHelper::stringToArray($value));
		}

		/**
		 * Retrieves the posted field value. In other words, sets this
		 * field value using the appropriate values in $_REQUEST.
		 * @since FORMfields v3.0
		 */
		function getParameter() 
		{
			parent::getParameter();
		}
		
		/**
		 * Checks for field errors detected by this field, including
		 * a check for blank. This method ensures that if the other
		 * choice is checked, that a value for other is supplied.
		 * If an error is detected, the setError() method is called
		 * to set the appropriate error message.
		 * @return boolean true if there is an error or false otherwise
		 * @since FORMfields v3.0
		 */
		function isValid() 
		{
			if (!parent::isValid())
				return false;

			if ($this->isEmpty() && $this->otherBox->isEmpty())
				return true;

			if ($this->includeOtherChoice && !$this->otherBox->isEmpty() && $this->otherChoice->isEmpty()) {
				$this->setError(FfLH::t("please specify a value for other") . "!");
				return false;
			}

			return true;
		}
	}

?>