Subversion Repositories web.creative

<?php namespace ProcessWire;

/**
 * ProcessWire Toggle Fieldtype
 * 
 * #pw-summary Configurable yes/no, on/off toggle alternative to a checkbox, plus optional “other” option.
 *
 * #pw-body =
 * Toggle fieldtype for “yes/on”, “no/off” and optional “other” state. Unlike
 * FieldtypeCheckbox, this Fieldtype can differentiate between a selection
 * of “no” and no-selection (aka unknown state), and it can also optionally
 * support a selection for “other” (with custom label).
 * 
 * When using a selector to find pages matching a particular toggle state,
 * or when setting values to `$page->your_field`, the following:
 *
 * - `0` or `no` or `FieldtypeToggle::valueNo` for no/off selection
 * - `1` or `yes` or `FieldtypeToggle::valueYes` for yes/on selection
 * - `2` or `other` or `FieldtypeToggle::valueOther` for other selection (if enabled for field)
 * - `''` blank string or `unknown` or `FieldtypeToggle::valueUnknown` for “no selection”
 * 
 * Please note that `0` and “no selection” are different things (unlike with a checkbox) so
 * be sure to consider this when finding pages or outputting values. The examples below
 * include a couple that demonstrate this. 
 * 
 * Examples (for field named “featured”):
 * ~~~~~
 * // find pages with “yes” selected for “featured”
 * $items = $pages->find("featured=1");
 * $items = $pages->find("featured=yes"); 
 * 
 * // find pages with “no” selected for “featured”
 * $items = $pages->find("featured=0");
 * $items = $pages->find("featured=no"); 
 * 
 * // find pages with no selection
 * $items = $pages->find("featured=''");
 * $items = $pages->find("featured=unknown");
 * 
 * // find pages with yes or no selection
 * $items = $pages->find("featured=1|0");
 * $items = $pages->find("featured=yes|no");
 * 
 * // find pages with “no” selected, or no selection
 * $items = $pages->find("featured=''|0"); 
 * $items = $pages->find("featured=unknown|no"); 
 * 
 * // output current value (blank, 0 or 1, or 2 if “other” option available)
 * // unless you’ve configured it to output custom labels when formatted
 * echo $page->featured;
 * 
 * // determine current setting (assuming labels not overriding values)
 * if($page->featured === '') {
 *   // unknown aka no-selection
 * } else if($page->featured === 0) {
 *   // no selected
 * } else if($page->featured === 1) {
 *   // yes selected
 * } else if($page->featured === 2) {
 *   // other selected (if enabled)
 * }
 * 
 * // set value of $page->featured to yes/on
 * $page->featured = 1; 
 * ~~~~~
 * 
 * #pw-body
 *
 * For documentation about the fields used in this class, please see:
 * /wire/core/Fieldtype.php
 *
 * ProcessWire 3.x, Copyright 2019 by Ryan Cramer
 * https://processwire.com
 * 
 *
 */

class FieldtypeToggle extends Fieldtype {

  public static function getModuleInfo() {
    return array(
      'title' => __('Toggle (Yes/No)', __FILE__),
      'version' => 1,
      'summary' => __('Configurable yes/no, on/off toggle alternative to a checkbox, plus optional “other” option.', __FILE__),
      'requires' => 'InputfieldToggle',
    );
  }

  // value constants
  const valueNo = 0;
  const valueYes = 1;
  const valueOther = 2;
  const valueUnknown = '';

  // format constants
  const formatNone = 0;
  const formatBoolean = 1;
  const formatString = 2;
  const formatEntities = 3;

  /**
   * Get the blank value
   * 
   * @param Page $page
   * @param Field $field
   * @return string
   * 
   */
  public function getBlankValue(Page $page, Field $field) {
    return self::valueUnknown;
  }
  
  /**
   * Get the default value
   *
   * #pw-internal
   *
   * @param Page $page
   * @param Field $field
   * @return mixed
   *
   */
  public function getDefaultValue(Page $page, Field $field) {
    return self::valueUnknown;
  }
  
  /**
   * Return whether the given value is considered empty or not.
   *
   * This can be anything that might be present in a selector value and thus is
   * typically a string. However, it may be used outside of that purpose so you
   * shouldn't count on it being a string.
   *
   * Example: an integer or text Fieldtype might not consider a "0" to be empty,
   * whereas a Page reference would.
   *
   * #pw-group-finding
   *
   * @param Field $field
   * @param mixed $value
   * @return bool
   *
   */
  public function isEmptyValue(Field $field, $value) {
    if($field) {}
    // 0 is allowed because it represents "no/off" selection
    if($value === 0 || $value === "0") return false; 
    if($value === 'unknown' || "$value" === "-1") return true;
    $value = trim($value, '"\''); 
    return empty($value);
  }

  /**
   * Sanitize value to 0, 1, 2, '' (blank string), or optionaly given fail value on failure
   * 
   * @param string|int $value
   * @param string $failValue Value to return if we are unable to map to toggle option
   * @return int|string
   * 
   */
  protected function _sanitizeValue($value, $failValue = self::valueUnknown) {
    $strValue = strtolower("$value");
    if($strValue === "0" || $value === false || $strValue === "no" || $strValue === "off") {
      $value = self::valueNo;
    } else if($strValue === "1" || $value === true || $strValue === "yes" || $strValue === "on") {
      $value = self::valueYes;
    } else if($strValue === "2" || $strValue === "other") {
      $value = self::valueOther;
    } else if($value === null || $strValue === '' || $strValue === 'unknown' || $strValue === '-1') {
      $value = self::valueUnknown;
    } else {
      $value = $failValue;
    }
    return $value;
  }

  /**
   * Sanitize value for placement on Page object
   * 
   * @param Page $page
   * @param Field $field
   * @param int|object|WireArray|string $value
   * @return int|object|WireArray|string
   * 
   */
  public function sanitizeValue(Page $page, Field $field, $value) {
    $cleanValue = $this->_sanitizeValue($value, 'fail');
    if($cleanValue === 'fail') {
      // if we fail to sanitize here, try to sanitize with InputfieldToggle
      // which can map toggle labels to toggle values
      /** @var InputfieldToggle $f */
      $f = $field->getInputfield($page, $field); 
      $cleanValue = $f ? $f->sanitizeValue($value) : '';
    }
    return $cleanValue;
  }

  /**
   * Return the markup value
   * 
   * @param Page $page
   * @param Field $field
   * @param int|string|null $value
   * @param string $property
   *
   * @return MarkupFieldtype|string
   * 
   */
  public function ___markupValue(Page $page, Field $field, $value = null, $property = '') {
    /** @var InputfieldToggle $f */
    $f = $field->getInputfield($page, $field); 
    if($value !== null) $f->val($value);
    if(!$f) return '';
    return $f->renderValue();
  }

  /**
   * Get the InputfieldToggle instance
   * 
   * @param Page $page
   * @param Field $field
   * @return InputfieldToggle
   * 
   */
  public function getInputfield(Page $page, Field $field) {
    /** @var InputfieldToggle $f */
    $f = $this->wire('modules')->get('InputfieldToggle');
    return $f;
  }

  /**
   * Get database schema
   * 
   * @param Field $field
   * @return array
   * 
   */
  public function getDatabaseSchema(Field $field) {
    $schema = parent::getDatabaseSchema($field);
    $schema['data'] = "tinyint NOT NULL";
    $schema['keys']['data'] = 'KEY data (data)';
    return $schema;
  }

  /**
   * @param DatabaseQuerySelect $query
   * @param string $table
   * @param string $subfield
   * @param string $operator
   * @param mixed $value
   *
   * @return DatabaseQuery|DatabaseQuerySelect
   * @throws WireException
   * 
   */
  public function getMatchQuery($query, $table, $subfield, $operator, $value) {
    
    $value = $this->_sanitizeValue($value); // 0, 1, 2 or ''
    $matchNull = false;
    
    if($value === '' && $operator === '=') {
      // match only no-selection
      $matchNull = true;
      
    } else if($value === '' && $operator === '>') {
      // match all except no-selection
      $value = 0;
      $operator = '>=';
      
    } else if($value !== '' && $operator === '!=') {
      // match value as well as no-selection
      $matchNull = true;
    } 
    
    if($value === '' && ($operator[0] === '<' || $operator[0] === '>')) {
      throw new WireException("Operator $operator not supported here for non-value");
    }

    if($matchNull) {
      // match non-present (null) rows in selection via left join
      static $n = 0;
      $_table = $table . '_tog' . (++$n);
      $query->leftjoin("$table AS $_table ON $_table.pages_id=pages.id");
      $where = "$_table.pages_id IS NULL ";
      if($value !== '') $where .= "OR $_table.data$operator" . ((int) $value);
      $query->where(trim($where));
    } else {
      $query = parent::getMatchQuery($query, $table, $subfield, $operator, $value);
    }
    
    return $query;
  }

  /**
   * Get information used for InputfieldSelector interactive selector builder
   *
   * @param Field $field
   * @param array $data
   * @return array
   *
   */
  public function ___getSelectorInfo(Field $field, array $data = array()) {
    /** @var InputfieldToggle $inputfield */
    $inputfield = $field->getInputfield(new NullPage(), $field);
    $labels = $inputfield->getLabels();
    $info = parent::___getSelectorInfo($field, $data);
    $info['input'] = 'select';
    $info['options'] = array('1' => $labels['yes'], '0' => $labels['no']); 
    if($field->get('useOther')) $info['options']['2'] = $labels['other'];
    $info['options']['""'] = $labels['unknown'];
    $info['operators'] = array('=', '!=');
    return $info;
  }


  /**
   * Get an array of Fieldtypes that are compatible with this one
   *
   * This represents the list of Fieldtype modules that the user is allowed to change to from this one.
   *
   * @param Field $field
   * @return Fieldtypes|null
   *
   */
  public function ___getCompatibleFieldtypes(Field $field) {
    if($field) {}
    $fieldtypes = $this->wire(new Fieldtypes());
    foreach($this->wire('fieldtypes') as $fieldtype) {
      if($fieldtype instanceof FieldtypeToggle || $fieldtype instanceof FieldtypeCheckbox) {
        $fieldtypes->add($fieldtype);
      }
    }
    return $fieldtypes;
  }
  
  /**
   * Given an 'awake' value, as set by wakeupValue(), convert the value back to a basic type for storage in database.
   *
   * @param Page $page
   * @param Field $field
   * @param string|int|float|array|object $value
   * @return string|int|float|array
   * @see Fieldtype::wakeupValue()
   *
   */
  public function ___sleepValue(Page $page, Field $field, $value) {
    if($page && $field) {}
    return $this->_sanitizeValue($value);
  }
  
  /**
   * Format the given value for output and return a string of the formatted value
   *
   * @param Page $page Page that the value lives on
   * @param Field $field Field that represents the value
   * @param string|int|object $value The value to format
   * @return mixed
   *
   */
  public function ___formatValue(Page $page, Field $field, $value) {
    
    $value = $this->_sanitizeValue($value);
    $formatType = (int) $field->get('formatType');

    if($value === '' || $formatType === self::formatNone) {
      // no formatting, or blank string which always represents no-selection
    } else if($formatType === self::formatBoolean) {
      if($value === 0) $value = false;
      if($value === 1) $value = true;
      
    } else if($formatType === self::formatString || $formatType === self::formatEntities) {
      /** @var InputfieldToggle $f */
      $f = $field->getInputfield($page, $field);
      if($f && $f instanceof InputfieldToggle) {
        $value = $f->getValueLabel($value);
        if($formatType == self::formatEntities) $value = $f->formatLabel($value, false);
      } else if($formatType == self::formatEntities) {
        $value = $this->wire('sanitizer')->entities1($value);
      }
    }
    
    return $value;
  }
  
  /**
   * Get any Inputfields used for configuration of this Fieldtype.
   *
   * @param Field $field
   * @return InputfieldWrapper
   *
   */
  public function ___getConfigInputfields(Field $field) {
    $inputfields = parent::___getConfigInputfields($field);

    /** @var InputfieldRadios $f */
    $f = $this->modules->get('InputfieldRadios'); 
    $f->attr('name', 'formatType'); 
    $f->attr('value', (int) $field->get('formatType')); 
    $f->label = $this->_('What do you want the formatted value of your toggle field to be?'); 
    $f->icon = 'toggle-on';
    $f->description = 
      sprintf($this->_('Select the formatted value returned by %s.'), "`\$page->$field->name`") . ' ' . 
      $this->_('Please also see the “Input” tab for all of the other Toggle field settings.'); 
    $f->notes = 
      '¹ ' . $this->_('For all of the above, no-selection is always represented by a blank string.') . "\n" . 
      '² ' . $this->_('If a 3rd/other option is enabled, it is represented by integer 2.');
    $f->detail = 
      $this->_('When a page’s output formatting is off, the value is always integer 0, 1, 2 (for No, Yes, Other) or a blank string when no selection.');
    $f->addOption(self::formatNone, $this->_('**Integer:** 0=no, 1=yes (same as no formatting).') . ' ²');
    $f->addOption(self::formatBoolean, $this->_('**Boolean:** True or false for yes/no states.') . ' ²');
    $f->addOption(self::formatString, $this->_('**String:** Use text labels configured with “Input” settings.'));
    $f->addOption(self::formatEntities, $this->_('**Entities:** Same as above (string) but entity encoded for HTML output.')); 
    $f->attr('value', (int) $field->get('formatType'));
    $inputfields->add($f); 

    // names of fields in the form that are allowed in fieldgroup/template context
    return $inputfields;
  }

}