1:   2:   3:   4:   5:   6:   7:   8:   9:  10:  11:  12:  13:  14:  15:  16:  17:  18:  19:  20:  21:  22:  23:  24:  25:  26:  27:  28:  29:  30:  31:  32:  33:  34:  35:  36:  37:  38:  39:  40:  41:  42:  43:  44:  45:  46:  47:  48:  49:  50:  51:  52:  53:  54:  55:  56:  57:  58:  59:  60:  61:  62:  63:  64:  65:  66:  67:  68:  69:  70:  71:  72:  73:  74:  75:  76:  77:  78:  79:  80:  81:  82:  83:  84:  85:  86:  87:  88:  89:  90:  91:  92:  93:  94:  95:  96:  97:  98:  99: 100: 101: 102: 103: 104: 105: 106: 107: 108: 109: 110: 111: 112: 113: 114: 115: 116: 117: 118: 119: 120: 121: 122: 123: 124: 125: 126: 127: 128: 129: 130: 131: 132: 133: 134: 135: 136: 137: 138: 139: 140: 141: 142: 143: 144: 145: 146: 147: 148: 149: 150: 151: 152: 153: 154: 155: 156: 157: 158: 159: 160: 161: 162: 163: 164: 165: 166: 167: 168: 169: 170: 171: 172: 173: 174: 175: 176: 177: 178: 179: 180: 181: 182: 183: 184: 185: 186: 187: 188: 189: 190: 191: 192: 193: 194: 195: 196: 197: 198: 199: 200: 201: 202: 203: 204: 205: 206: 207: 208: 209: 210: 211: 212: 213: 214: 215: 216: 217: 218: 219: 220: 221: 222: 223: 224: 225: 226: 227: 228: 229: 230: 231: 232: 233: 234: 235: 236: 237: 238: 239: 240: 241: 242: 243: 244: 245: 246: 247: 248: 249: 250: 251: 252: 253: 254: 255: 256: 257: 258: 259: 260: 261: 262: 263: 264: 265: 266: 267: 268: 269: 270: 271: 272: 273: 274: 275: 276: 277: 278: 

<?php

/**
 * MvcCore
 *
 * This source file is subject to the BSD 3 License
 * For the full copyright and license information, please view
 * the LICENSE.md file that are distributed with this source code.
 *
 * @copyright   Copyright (c) 2016 Tom Flidr (https://github.com/mvccore)
 * @license     https://mvccore.github.io/docs/mvccore/5.0.0/LICENCE.md
 */

namespace MvcCore\Ext\Forms\Fields;

/**
 * Responsibility: init, pre-dispatch and render group of `input`s 
 *                 with `type` as `checkbox`, with configuration to 
 *                 select minimum and maximum count of values and 
 *                 required option. 
 *                 `CheckboxGroup` has it's own validator to check if 
 *                 submitted values are presented in configured by 
 *                 default and it's own validator to check minimum or 
 *                 maximum count of selected options.
 */
class       CheckboxGroup 
extends     \MvcCore\Ext\Forms\FieldsGroup 
implements  \MvcCore\Ext\Forms\Fields\IMinMaxOptions {

    use \MvcCore\Ext\Forms\Field\Props\MinMaxOptions;
    
    /**
     * Valid email address error message index.
     * @var int
     */
    const ERROR_REQUIRED_BUBBLE = 0;
    const ERROR_MIN_OPTIONS_BUBBLE = 1;
    const ERROR_MAX_OPTIONS_BUBBLE = 2;

    /**
     * Validation failure message template definitions.
     * @var array
     */
    protected static $errorMessages = [
        self::ERROR_REQUIRED_BUBBLE     => "Please tick this box, field is required.",
        self::ERROR_MIN_OPTIONS_BUBBLE  => "Please select at least `{1}` option(s) as minimum.",
        self::ERROR_MAX_OPTIONS_BUBBLE  => "Please select up to `{1}` option(s) at maximum.",
    ];

    /**
     * Possible value: `checkbox`, used in HTML code for this fields.
     * @var string
     */
    protected $type = 'checkbox-group';
    
    /**
     * Validators: 
     * - `ValueInOptions` - to validate if submitted string(s) 
     *                      are presented in select options keys.
     * @var string[]|\Closure[]
     */
    protected $validators = ["ValueInOptions"];

    /**
     * Supporting javascript full javascript class name.
     * If you want to use any custom supporting javascript prototyped class
     * for any additional purposes for your custom field, you need to use
     * `$field->jsSupportingFile` property to define path to your javascript file
     * relatively from configured `\MvcCore\Ext\Form::SetJsSupportFilesRootDir(...);`
     * value. Than you have to add supporting javascript file path into field form 
     * in `$field->PreDispatch();` method to render those files immediately after form
     * (once) or by any external custom assets renderer configured by:
     * `$form->SetJsSupportFilesRenderer(...);` method.
     * Or you can add your custom supporting javascript files into response by your 
     * own and also you can run your helper javascripts also by your own. Is up to you.
     * `NULL` by default.
     * @var string
     */
    protected $jsClassName = 'MvcCoreForm.CheckboxGroup';

    /**
     * Field supporting javascript file relative path.
     * If you want to use any custom supporting javascript file (with prototyped 
     * class) for any additional purposes for your custom field, you need to 
     * define path to your javascript file relatively from configured 
     * `\MvcCore\Ext\Form::SetJsSupportFilesRootDir(...);` value. 
     * Than you have to add supporting javascript file path into field form 
     * in `$field->PreDispatch();` method to render those files immediately after form
     * (once) or by any external custom assets renderer configured by:
     * `$form->SetJsSupportFilesRenderer(...);` method.
     * Or you can add your custom supporting javascript files into response by your 
     * own and also you can run your helper javascripts also by your own. Is up to you.
     * `NULL` by default.
     * @var string
     */
    protected $jsSupportingFile = \MvcCore\Ext\IForm::FORM_ASSETS_DIR_REPLACEMENT . '/fields/checkbox-group.js';

    /**
     * Maximum options specific css class for supporting javascript code.
     * @var string
     */
    protected $maxOptionsClassName = 'max-selected-options';

    /**
     * Standard field template strings for natural rendering a `control`.
     * @var string
     */
    protected static $templates = [
        'control'   => '<input id="{id}" name="{name}[]" type="checkbox" value="{value}"{checked}{attrs} />',
    ];

    /**
     * Create new form `<input type="checkbox" />` group control instance.
     * @param array $cfg Config array with public properties and it's 
     *                   values which you want to configure, presented 
     *                   in camel case properties names syntax.
     * @throws \InvalidArgumentException
     * @return void
     */
    public function __construct(array $cfg = []) {
        parent::__construct($cfg);
        static::$templates = (object) array_merge(
            (array) parent::$templates, 
            (array) self::$templates
        );
    }

    /**
     * This INTERNAL method is called from `\MvcCore\Ext\Form` after field
     * is added into form by `$form->AddField();` method. 
     * Do not use this method even if you don't develop any form field group.
     * - Check if field has any name, which is required.
     * - Set up form and field id attribute by form id and field name.
     * - Set up required.
     * - Check if there are any options for current controls group.
     * - Check if there are defined validators if there are defined minimum or maximum selected options.
     * @param \MvcCore\Ext\Form $form
     * @throws \InvalidArgumentException
     * @return \MvcCore\Ext\Forms\Fields\Select
     */
    public function SetForm (\MvcCore\Ext\IForm $form) {
        /** @var $this \MvcCore\Ext\Forms\Field */
        parent::SetForm($form);
        // add minimum/maximum options count validator if necessary
        $this->setFormMinMaxOptions();
        return $this;
    }

    /**
     * Return field specific data for validator.
     * @param array $fieldPropsDefaultValidValues 
     * @return array
     */
    public function & GetValidatorData ($fieldPropsDefaultValidValues = []) {
        $result = [
            'multiple'      => TRUE, 
            'options'       => & $this->options, 
            'minOptions'    => $this->minOptions,
            'maxOptions'    => $this->maxOptions,
        ];
        return $result;
    }

    /**
     * This INTERNAL method is called from `\MvcCore\Ext\Form` just before
     * field is naturally rendered. It sets up field for rendering process.
     * Do not use this method even if you don't develop any form field.
     * Set up field properties before rendering process.
     * - Set up field render mode.
     * - Set up translation boolean.
     * - Translate label property if any.
     * - Translate all option texts if necessary.
     * - Translate browser bubble messages if necessary.
     * - Add supporting javascripts if necessary.
     * @return void
     */
    public function PreDispatch () {
        parent::PreDispatch();
        $minOptsDefined = $this->minOptions !== NULL;
        $maxOptsDefined = $this->maxOptions !== NULL;
        $addSupportingJavascript = $this->required || $minOptsDefined || $maxOptsDefined;
        if (!$addSupportingJavascript) return;
        $form = & $this->form;
        // add necessary error messages
        $this->requiredBubbleMessage = strip_tags($this->translateAndFormatValidationError(
            ($this->requiredBubbleMessage
                ? $this->requiredBubbleMessage
                : static::$errorMessages[static::ERROR_REQUIRED_BUBBLE])
        ));
        $this->minOptionsBubbleMessage = strip_tags($this->translateAndFormatValidationError(
            ($this->minOptionsBubbleMessage
                ? $this->minOptionsBubbleMessage
                : static::$errorMessages[static::ERROR_MIN_OPTIONS_BUBBLE]),
            [$minOptsDefined ? $this->minOptions : 1]
        ));
        $this->maxOptionsBubbleMessage = strip_tags($this->translateAndFormatValidationError(
            ($this->maxOptionsBubbleMessage
                ? $this->maxOptionsBubbleMessage
                : static::$errorMessages[static::ERROR_MAX_OPTIONS_BUBBLE]),
            [$maxOptsDefined ? $this->maxOptions : count($this->options)]
        ));
        $form->AddJsSupportFile(
            $this->jsSupportingFile, 
            $this->jsClassName, 
            [
                $this->name . '[]', 
                $this->required,
                $this->minOptions,
                $this->maxOptions,
                $this->requiredBubbleMessage,
                $this->minOptionsBubbleMessage,
                $this->maxOptionsBubbleMessage,
                $this->maxOptionsClassName
            ]
        );
    }

    /**
     * Complete and return semi-finished strings for rendering by field key and option:
     * - Label text string.
     * - Label attributes string.
     * - Control attributes string.
     * @param string       $key
     * @param string|array $option
     * @return array
     */
    protected function renderControlItemCompleteAttrsClassesAndText ($key, & $option) {
        $optionType = gettype($option);
        $labelAttrsStr = '';
        $controlAttrsStr = '';
        $itemLabelText = '';
        $originalRequired = $this->required;
        $this->required = FALSE;
        if ($optionType == 'string') {
            $itemLabelText = $option ? $option : $key;
            $labelAttrsStr = $this->renderLabelAttrsWithFieldVars();
            $controlAttrsMerged = $this->controlAttrs;
            if ($this->minOptions !== NULL)
                $controlAttrsMerged = array_merge($controlAttrsMerged, ['data-min-selected-options' => $this->minOptions,]);
            if ($this->maxOptions !== NULL)
                $controlAttrsMerged = array_merge($controlAttrsMerged, ['data-max-selected-options' => $this->maxOptions,]);
            $controlAttrsStr = $this->renderAttrsWithFieldVars(
                [], $controlAttrsMerged, $this->cssClasses, TRUE
            );
        } else if ($optionType == 'array') {
            $itemLabelText = isset($option['text']) ? $option['text'] : $key;
            $attrsArr = $this->controlAttrs;
            $classArr = $this->cssClasses;
            if (isset($option['attrs']) && gettype($option['attrs']) == 'array') {
                $attrsArr = array_merge($this->controlAttrs, $option['attrs']);
            }
            if ($this->minOptions !== NULL)
                $attrsArr = array_merge($attrsArr, ['data-min-selected-options' => $this->minOptions,]);
            if ($this->maxOptions !== NULL)
                $attrsArr = array_merge($attrsArr, ['data-max-selected-options' => $this->maxOptions,]);
            if (isset($option['class'])) {
                $classArrParam = [];
                $cssClass = $option['class'];
                if (is_array($cssClass)) {
                    $classArrParam = $cssClass;
                } else if (is_string($cssClass)) {
                    $classArrParam = explode(' ', $cssClass);
                }
                foreach ($classArrParam as $clsValue) 
                    if ($clsValue) $classArr[] = $clsValue;
            }
            $labelAttrsStr = $this->renderAttrsWithFieldVars(
                [], $attrsArr, $classArr, FALSE
            );
            $controlAttrsStr = $this->renderAttrsWithFieldVars(
                [], $attrsArr, $classArr, TRUE
            );
        }
        $this->required = $originalRequired;
        return [$itemLabelText, $labelAttrsStr, $controlAttrsStr];
    }
}