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: 

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

/**
 * Trait for classes:
 * - `\MvcCore\Ext\Forms\Fields\Select`
 *    - `\MvcCore\Ext\Forms\Fields\CountrySelect`
 */
trait NullOptionText {

    /**
     * This attribute is a text placeholder for `<select>` controls,
     * when no option is selected yet. Typically: `--- please select an option ---`.
     * It's rendered every time this placeholder has any text value, doesn't matter,
     * if `<select>` tag has already any value selected or not yet . It's rendered usually 
     * as first `<option>` sub-element with an empty value, as `disabled` and `selected` 
     * `<option>` tag. `NULL` value means no placeholder `<option>` tag will be rendered.
     * @var string|NULL
     */
    protected $nullOptionText = NULL;
    
    /**
     * Boolean to translate placeholder text, `TRUE` by default.
     * @var boolean
     */
    protected $translateNullOptionText = TRUE;

    /**
     * Automatically translate `nullOptionText` property if necessary
     * in `PreDispatch()` field rendering moment.
     * @return void
     */
    protected function preDispatchNullOptionText () {
        /** @var $this \MvcCore\Ext\Forms\Fields\Select */
        if ($this->translate && $this->nullOptionText !== NULL && $this->translateNullOptionText)
            $this->nullOptionText = $this->form->Translate($this->nullOptionText);
    }

    /**
     * This attribute is a text placeholder for `<select>` controls,
     * when no option is selected yet. Typically: `--- please select an option ---`.
     * It's rendered every time this placeholder has any text value, doesn't matter,
     * if `<select>` tag has already any value selected or not yet . It's rendered usually 
     * as first `<option>` sub-element with an empty value, as `disabled` and `selected` 
     * `<option>` tag. `NULL` value means no placeholder `<option>` tag will be rendered.
     * @return string|NULL
     */
    public function GetNullOptionText () {
        /** @var $this \MvcCore\Ext\Forms\Fields\Select */
        return $this->nullOptionText;
    }
    
    /**
     * This attribute is a text placeholder for `<select>` controls,
     * when no option is selected yet. Typically: `--- please select an option ---`.
     * It's rendered every time this placeholder has any text value, doesn't matter,
     * if `<select>` tag has already any value selected or not yet . It's rendered usually 
     * as first `<option>` sub-element with an empty value, as `disabled` and `selected` 
     * `<option>` tag. `NULL` value means no placeholder `<option>` tag will be rendered.
     * @param string|NULL  $nullOptionText 
     * @param boolean|NULL $translateNullOptionText 
     * @return \MvcCore\Ext\Forms\Field
     */
    public function SetNullOptionText ($nullOptionText, $translateNullOptionText = NULL) {
        /** @var $this \MvcCore\Ext\Forms\Fields\Select */
        $this->nullOptionText = $nullOptionText;
        if ($translateNullOptionText !== NULL)
            $this->translateNullOptionText = $translateNullOptionText;
        return $this;
    }

}