summaryrefslogtreecommitdiff
path: root/lib/prado/framework/Web/UI/WebControls/TLabel.php
blob: ba342b77a88236b13cea5d7e8eb3694e673d3d69 (plain)
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
<?php
/**
 * TLabel class file.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @link https://github.com/pradosoft/prado
 * @copyright Copyright &copy; 2005-2016 The PRADO Group
 * @license https://github.com/pradosoft/prado/blob/master/COPYRIGHT
 * @package System.Web.UI.WebControls
 */

/**
 * TLabel class
 *
 * TLabel displays a piece of text on a Web page.
 * Use {@link setText Text} property to set the text to be displayed.
 * TLabel will render the contents enclosed within its component tag
 * if {@link setText Text} is empty.
 * To use TLabel as a form label, associate it with a control by setting the
 * {@link setForControl ForControl} property.
 * The associated control must be locatable within the label's naming container.
 * If the associated control is not visible, the label will not be rendered, either.
 *
 * Note, {@link setText Text} will NOT be encoded for rendering.
 * Make sure it does not contain dangerous characters that you want to avoid.
 *
 * @author Qiang Xue <qiang.xue@gmail.com>
 * @package System.Web.UI.WebControls
 * @since 3.0
 */
class TLabel extends TWebControl implements IDataRenderer
{
	private $_forControl='';

	/**
	 * @return string tag name of the label, returns 'label' if there is an associated control, 'span' otherwise.
	 */
	protected function getTagName()
	{
		return ($this->getForControl()==='')?'span':'label';
	}

	/**
	 * Adds attributes to renderer.
	 * @param THtmlWriter the renderer
	 * @throws TInvalidDataValueException if associated control cannot be found using the ID
	 */
	protected function addAttributesToRender($writer)
	{
		if($this->_forControl!=='')
			$writer->addAttribute('for',$this->_forControl);
		parent::addAttributesToRender($writer);
	}

	/**
	 * Renders the label.
	 * It overrides the parent implementation by checking if an associated
	 * control is visible or not. If not, the label will not be rendered.
	 * @param THtmlWriter writer
	 */
	public function render($writer)
	{
		if(($aid=$this->getForControl())!=='')
		{
			if($control=$this->findControl($aid))
			{
				if($control->getVisible(true))
				{
					$this->_forControl=$control->getClientID();
					parent::render($writer);
				}
			}
			else
				throw new TInvalidDataValueException('label_associatedcontrol_invalid',$aid);
		}
		else
			parent::render($writer);
	}

	/**
	 * Renders the body content of the label.
	 * @param THtmlWriter the renderer
	 */
	public function renderContents($writer)
	{
		if(($text=$this->getText())==='')
			parent::renderContents($writer);
		else
			$writer->write($text);
	}

	/**
	 * @return string the text value of the label
	 */
	public function getText()
	{
		return $this->getViewState('Text','');
	}

	/**
	 * @param string the text value of the label
	 */
	public function setText($value)
	{
		$this->setViewState('Text',TPropertyValue::ensureString($value),'');
	}

	/**
	 * Returns the text value of the label.
	 * This method is required by {@link IDataRenderer}.
	 * It is the same as {@link getText()}.
	 * @return string the text value of the label
	 * @see getText
	 * @since 3.1.0
	 */
	public function getData()
	{
		return $this->getText();
	}

	/**
	 * Sets the text value of the label.
	 * This method is required by {@link IDataRenderer}.
	 * It is the same as {@link setText()}.
	 * @param string the text value of the label
	 * @see setText
	 * @since 3.1.0
	 */
	public function setData($value)
	{
		$this->setText($value);
	}

	/**
	 * @return string the associated control ID
	 */
	public function getForControl()
	{
		return $this->getViewState('ForControl','');
	}

	/**
	 * Sets the ID of the control that the label is associated with.
	 * The control must be locatable via {@link TControl::findControl} using the ID.
	 * @param string the associated control ID
	 */
	public function setForControl($value)
	{
		$this->setViewState('ForControl',$value,'');
	}
}