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: 279: 

<?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\Field;

/**
 * Trait for class `\MvcCore\Ext\Forms\Field` containing field (mostly 
 * configurable) properties getter methods.
 */
trait Getters {

    /**
     * Get form field HTML id attribute, completed from form name and field name.
     * This value is completed automatically, but you can customize it.
     * @return string|NULL
     */
    public function GetId () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->id;
    }

    /**
     * Get form field specific name, used to identify submitted value.
     * This value is required for all form fields.
     * @return string|NULL
     */
    public function GetName () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->name;
    }

    /**
     * Get form field type, used in `<input type="...">` attribute value.
     * Every typed field has it's own string value, but base field type 
     * `\MvcCore\Ext\Forms\Field` has `NULL`.
     * @return string|NULL
     */
    public function GetType () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->type;
    }

    /**
     * Get form field value. It could be string or array, in or float, it depends
     * on field implementation. Default value is `NULL`.
     * @return string|array|int|float|NULL
     */
    public function GetValue () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->value;
    }

    /**
     * Get form field HTML element css classes strings as array.
     * Default value is an empty array to not render HTML `class` attribute.
     * @return \string[]
     */
    public function & GetCssClasses () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->cssClasses;
    }

    /**
     * Get field title, global HTML attribute, optional.
     * @return string|NULL
     */
    public function GetTitle () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->title;
    }

    /**
     * Get collection with field HTML element 
     * additional attributes by array keys/values.
     * There are no system attributes as: `id`, `name`, 
     * `value`, `readonly`, `disabled`, `class` ...
     * Those attributes have it's own configurable 
     * properties with it's own getters.
     * HTML field elements are meant: `<input>, 
     * <button>, <select>, <textarea> ...`
     * Default value is an empty array to not 
     * render any additional attributes.
     * @return array
     */
    public function & GetControlAttrs () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->controlAttrs;
    }

    /**
     * Get field HTML element additional attribute 
     * by attribute name and value.
     * There are no system attributes as: `id`, `name`, 
     * `value`, `readonly`, `disabled`, `class` ...
     * Those attributes have it's own configurable 
     * properties with it's own getters.
     * HTML field elements are meant: `<input>, 
     * <button>, <select>, <textarea> ...`
     * If attribute doesn't exist, `NULL` is returned.
     * @param string $name
     * @return mixed
     */
    public function GetControlAttr ($name = 'data-*') {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return isset($this->controlAttrs[$name])
            ? $this->controlAttrs[$name]
            : NULL;
    }

    /**
     * Get list of predefined validator classes ending names or validator instances.
     * Validator class must exist in any validators namespace(s) configured by default:
     * - `array('\MvcCore\Ext\Forms\Validators\');`
     * Or it could exist in any other validators namespaces, configured by method(s):
     * - `\MvcCore\Ext\Form::AddValidatorsNamespaces(...);`
     * - `\MvcCore\Ext\Form::SetValidatorsNamespaces(...);`
     * Every validator class (ending name) or validator instance has to 
     * implement interface `\MvcCore\Ext\Forms\IValidator` or it could be extended 
     * from base abstract validator class: `\MvcCore\Ext\Forms\Validator`.
     * Every typed field has it's own predefined validators, but you can define any
     * validator you want and replace them.
     * @return \string[]|\MvcCore\Ext\Forms\Validator[]
     */
    public function & GetValidators () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->validators;
    }

    /**
     * Get `TRUE`, if field has configured in it's validators array
     * given validator class ending name or validator instance.
     * @param string|\MvcCore\Ext\Forms\Validator $validatorNameOrInstance
     * @return bool
     */
    public function HasValidator ($validatorNameOrInstance) {
        /** @var $this \MvcCore\Ext\Forms\Field */
        if (is_string($validatorNameOrInstance)) {
            $validatorClassName = $validatorNameOrInstance;
        } else if ($validatorNameOrInstance instanceof \MvcCore\Ext\Forms\IValidator) {
            $validatorClassName = get_class($validatorNameOrInstance);
        } else {
            return $this->throwNewInvalidArgumentException(
                'Unknown validator type given: `' . $validatorNameOrInstance 
                . '`, type: `' . gettype($validatorNameOrInstance) . '`.'
            );
        }
        $slashPos = strrpos($validatorClassName, '\\');
        $validatorName = $slashPos !== FALSE 
            ? substr($validatorClassName, $slashPos + 1)
            : $validatorClassName;
        return isset($this->validators[$validatorName]);
    }

    /**
     * Get boolean `TRUE` or string with template relative path 
     * without `.phtml` or `.php` extension to render 
     * field by any custom template. 
     * 
     * If `TRUE`, path to template is always completed by configured 
     * `\MvcCore\Ext\Forms\view::SetFieldsDir(...);`
     * value, which is `/App/Views/Forms/Fields` by default.
     * 
     * If returned any string with relative path, path is always relative from configured
     * `\MvcCore\Ext\Forms\view::SetFieldsDir(...);` value, which is again 
     * `/App/Views/Forms/Fields` by default.
     * 
     * `FALSE` or `NULL` (`NULL` is default) is returned to render field naturally.
     * 
     * Example:
     * ```
     * // Render field template prepared in:
     * // '/App/Views/Forms/Fields/my-specials/my-field-type.phtml':
     * 
     * \MvcCore\Ext\Forms\View::GetFieldsDir(); // returned by default: 'Forms/Fields'
     * $field->GetViewScript(); // returned 'my-specials/my-field-type'
     * 
     * // Or the same by:
     * \MvcCore\Ext\Forms\View::GetFieldsDir(); // returned 'Forms/Fields/my-specials'
     * $field->GetType(); // returned 'my-field-type'
     * $field->GetViewScript(); // returned TRUE
     * ```
     * @return bool|string|NULL
     */
    public function GetViewScript () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->viewScript;
    }

    /**
     * Get 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->SetJsSupportingFile(...)` 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.
     * @return string|NULL
     */
    public function GetJsClassName () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->jsClassName;
    }

    /**
     * Get 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.
     * @return string|NULL
     */
    public function GetJsSupportingFile () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->jsSupportingFile;
    }

    /**
     * Get field supporting css file relative path.
     * If you want to use any custom supporting css file 
     * for any additional purposes for your custom field, you need to 
     * define path to your css file relatively from configured 
     * `\MvcCore\Ext\Form::SetCssSupportFilesRootDir(...);` value. 
     * Than you have to add supporting css 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->SetCssSupportFilesRenderer(...);` method.
     * Or you can add your custom supporting css files into response by your 
     * own and also you can run your helper css also by your own. Is up to you.
     * `NULL` by default.
     * @return string|NULL
     */
    public function GetCssSupportingFile () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->cssSupportingFile;
    }

    /**
     * Get boolean flag about field visible texts and error messages translation.
     * This flag is automatically assigned from `$field->form->GetTranslate();` 
     * flag in `$field->Init();` method.
     * @var bool
     */
    public function GetTranslate () {
        /** @var $this \MvcCore\Ext\Forms\Field */
        return $this->translate;
    }

    /**
     * Get fields (and labels) default templates 
     * for natural (not customized) field rendering.
     * @return array
     */
    public static function & GetTemplates () {
        return (array) static::$templates;
    }
}