|
1
|
|
|
<?php |
|
2
|
|
|
|
|
3
|
|
|
namespace Charcoal\Ui; |
|
4
|
|
|
|
|
5
|
|
|
use \InvalidArgumentException; |
|
6
|
|
|
|
|
7
|
|
|
// Module `charcoal-config` dependencies |
|
8
|
|
|
use \Charcoal\Config\AbstractEntity; |
|
9
|
|
|
|
|
10
|
|
|
// Module `charcoal-core` dependencies |
|
11
|
|
|
use \Charcoal\Translation\TranslationString; |
|
12
|
|
|
|
|
13
|
|
|
// Module `charcoal-view` dependencies |
|
14
|
|
|
use \Charcoal\View\ViewableInterface; |
|
15
|
|
|
use \Charcoal\View\ViewableTrait; |
|
16
|
|
|
|
|
17
|
|
|
// Intra-module (`charcoal-ui`) dependencies |
|
18
|
|
|
use \Charcoal\Ui\UiItemInterface; |
|
19
|
|
|
|
|
20
|
|
|
/** |
|
21
|
|
|
* |
|
22
|
|
|
*/ |
|
23
|
|
|
abstract class AbstractUiItem extends AbstractEntity implements UiItemInterface |
|
24
|
|
|
{ |
|
25
|
|
|
use ViewableTrait; |
|
26
|
|
|
|
|
27
|
|
|
/** |
|
28
|
|
|
* @var string $type |
|
29
|
|
|
*/ |
|
30
|
|
|
private $type; |
|
31
|
|
|
|
|
32
|
|
|
/** |
|
33
|
|
|
* @var string $template |
|
34
|
|
|
*/ |
|
35
|
|
|
private $template; |
|
36
|
|
|
|
|
37
|
|
|
/** |
|
38
|
|
|
* @var TranslationString $title |
|
39
|
|
|
*/ |
|
40
|
|
|
private $title = ''; |
|
41
|
|
|
|
|
42
|
|
|
/** |
|
43
|
|
|
* @var TranslationString $subtitle |
|
44
|
|
|
*/ |
|
45
|
|
|
private $subtitle = ''; |
|
46
|
|
|
|
|
47
|
|
|
/** |
|
48
|
|
|
* @var TranslationString $description |
|
49
|
|
|
*/ |
|
50
|
|
|
private $description = ''; |
|
51
|
|
|
|
|
52
|
|
|
/** |
|
53
|
|
|
* @var TranslationString $notes |
|
54
|
|
|
*/ |
|
55
|
|
|
private $notes = ''; |
|
56
|
|
|
|
|
57
|
|
|
/** |
|
58
|
|
|
* If it is set to false, will disable display of title. |
|
59
|
|
|
* @var boolean $showTitle |
|
60
|
|
|
*/ |
|
61
|
|
|
private $showTitle = true; |
|
62
|
|
|
|
|
63
|
|
|
/** |
|
64
|
|
|
* If it is set to false, will disable display of title. |
|
65
|
|
|
* @var boolean $showSubtitle |
|
66
|
|
|
*/ |
|
67
|
|
|
private $showSubtitle = true; |
|
68
|
|
|
|
|
69
|
|
|
/** |
|
70
|
|
|
* If it is set to false, will disable display of description |
|
71
|
|
|
* @var boolean $showDescription |
|
72
|
|
|
*/ |
|
73
|
|
|
private $showDescription = true; |
|
74
|
|
|
|
|
75
|
|
|
/** |
|
76
|
|
|
* If it is set to false, will disable display of the notes (footer). |
|
77
|
|
|
* @var boolean $showNotes |
|
78
|
|
|
*/ |
|
79
|
|
|
private $showNotes = true; |
|
80
|
|
|
|
|
81
|
|
|
/** |
|
82
|
|
|
* @var boolean $showHeader |
|
83
|
|
|
*/ |
|
84
|
|
|
private $showHeader = true; |
|
85
|
|
|
|
|
86
|
|
|
/** |
|
87
|
|
|
* @var boolean $showFooter |
|
88
|
|
|
*/ |
|
89
|
|
|
private $showFooter = true; |
|
90
|
|
|
|
|
91
|
|
|
public function setType($type) |
|
92
|
|
|
{ |
|
93
|
|
|
$this->type = $type; |
|
94
|
|
|
return $this; |
|
95
|
|
|
} |
|
96
|
|
|
|
|
97
|
|
|
/** |
|
98
|
|
|
* @return string |
|
99
|
|
|
*/ |
|
100
|
|
|
public function type() |
|
101
|
|
|
{ |
|
102
|
|
|
return $this->type; |
|
103
|
|
|
} |
|
104
|
|
|
|
|
105
|
|
|
/** |
|
106
|
|
|
* @param string $template The UI item's template (identifier). |
|
107
|
|
|
* @throws InvalidArgumentException If the template identifier is not a string. |
|
108
|
|
|
* @return UiItemInterface Chainable |
|
109
|
|
|
*/ |
|
110
|
|
|
public function setTemplate($template) |
|
111
|
|
|
{ |
|
112
|
|
|
if (!is_string($template)) { |
|
113
|
|
|
throw new InvalidArgumentException( |
|
114
|
|
|
'Can not set UI Item\'s template: template identifier must be a string' |
|
115
|
|
|
); |
|
116
|
|
|
} |
|
117
|
|
|
$this->template = $template; |
|
118
|
|
|
return $this; |
|
119
|
|
|
} |
|
120
|
|
|
|
|
121
|
|
|
/** |
|
122
|
|
|
* @return string |
|
123
|
|
|
*/ |
|
124
|
|
|
public function template() |
|
125
|
|
|
{ |
|
126
|
|
|
if ($this->template === null) { |
|
127
|
|
|
return $this->type(); |
|
128
|
|
|
} |
|
129
|
|
|
return $this->template; |
|
130
|
|
|
} |
|
131
|
|
|
|
|
132
|
|
|
/** |
|
133
|
|
|
* @param mixed $title The group title. |
|
134
|
|
|
* @return UiItemInterface Chainable |
|
135
|
|
|
*/ |
|
136
|
|
|
public function setTitle($title) |
|
137
|
|
|
{ |
|
138
|
|
|
$this->title = new TranslationString($title); |
|
139
|
|
|
return $this; |
|
140
|
|
|
} |
|
141
|
|
|
|
|
142
|
|
|
/** |
|
143
|
|
|
* Get the title. |
|
144
|
|
|
* |
|
145
|
|
|
* @return TranslationString |
|
146
|
|
|
*/ |
|
147
|
|
|
public function title() |
|
148
|
|
|
{ |
|
149
|
|
|
return $this->title; |
|
|
|
|
|
|
150
|
|
|
} |
|
151
|
|
|
|
|
152
|
|
|
/** |
|
153
|
|
|
* @param mixed $subtitle The group subtitle. |
|
154
|
|
|
* @return UiItemInterface Chainable |
|
155
|
|
|
*/ |
|
156
|
|
|
public function setSubtitle($subtitle) |
|
157
|
|
|
{ |
|
158
|
|
|
$this->subtitle = new TranslationString($subtitle); |
|
159
|
|
|
return $this; |
|
160
|
|
|
} |
|
161
|
|
|
|
|
162
|
|
|
/** |
|
163
|
|
|
* @return TranslationString |
|
164
|
|
|
*/ |
|
165
|
|
|
public function subtitle() |
|
166
|
|
|
{ |
|
167
|
|
|
return $this->subtitle; |
|
|
|
|
|
|
168
|
|
|
} |
|
169
|
|
|
|
|
170
|
|
|
/** |
|
171
|
|
|
* @param mixed $description The group description. |
|
172
|
|
|
* @return UiItemInterface Chainable |
|
173
|
|
|
*/ |
|
174
|
|
|
public function setDescription($description) |
|
175
|
|
|
{ |
|
176
|
|
|
$this->description = new TranslationString($description); |
|
177
|
|
|
return $this; |
|
178
|
|
|
} |
|
179
|
|
|
|
|
180
|
|
|
/** |
|
181
|
|
|
* @return TranslationString |
|
182
|
|
|
*/ |
|
183
|
|
|
public function description() |
|
184
|
|
|
{ |
|
185
|
|
|
return $this->description; |
|
|
|
|
|
|
186
|
|
|
} |
|
187
|
|
|
|
|
188
|
|
|
/** |
|
189
|
|
|
* @param mixed $notes The group notes. |
|
190
|
|
|
* @return UiItemInterface Chainable |
|
191
|
|
|
*/ |
|
192
|
|
|
public function setNotes($notes) |
|
193
|
|
|
{ |
|
194
|
|
|
$this->notes = new TranslationString($notes); |
|
195
|
|
|
return $this; |
|
196
|
|
|
} |
|
197
|
|
|
|
|
198
|
|
|
/** |
|
199
|
|
|
* @return TranslationString |
|
200
|
|
|
*/ |
|
201
|
|
|
public function notes() |
|
202
|
|
|
{ |
|
203
|
|
|
return $this->notes; |
|
|
|
|
|
|
204
|
|
|
} |
|
205
|
|
|
|
|
206
|
|
|
/** |
|
207
|
|
|
* @param boolean $show The show title flag. |
|
208
|
|
|
* @return FormGroup Chainable |
|
209
|
|
|
*/ |
|
210
|
|
|
public function setShowTitle($show) |
|
211
|
|
|
{ |
|
212
|
|
|
$this->showTitle = !!$show; |
|
213
|
|
|
return $this; |
|
|
|
|
|
|
214
|
|
|
} |
|
215
|
|
|
|
|
216
|
|
|
/** |
|
217
|
|
|
* @return boolean |
|
218
|
|
|
*/ |
|
219
|
|
|
public function showTitle() |
|
220
|
|
|
{ |
|
221
|
|
|
if ($this->showTitle === false) { |
|
222
|
|
|
return false; |
|
223
|
|
|
} else { |
|
224
|
|
|
return !!$this->title(); |
|
225
|
|
|
} |
|
226
|
|
|
} |
|
227
|
|
|
|
|
228
|
|
|
/** |
|
229
|
|
|
* @param boolean $show The show subtitle flag. |
|
230
|
|
|
* @return FormGroup Chainable |
|
231
|
|
|
*/ |
|
232
|
|
|
public function setShowSubtitle($show) |
|
233
|
|
|
{ |
|
234
|
|
|
$this->showSubtitle = !!$show; |
|
235
|
|
|
return $this; |
|
|
|
|
|
|
236
|
|
|
} |
|
237
|
|
|
|
|
238
|
|
|
/** |
|
239
|
|
|
* @return boolean |
|
240
|
|
|
*/ |
|
241
|
|
|
public function showSubtitle() |
|
242
|
|
|
{ |
|
243
|
|
|
if ($this->showSubtitle === false) { |
|
244
|
|
|
return false; |
|
245
|
|
|
} else { |
|
246
|
|
|
return !!$this->subtitle(); |
|
247
|
|
|
} |
|
248
|
|
|
} |
|
249
|
|
|
|
|
250
|
|
|
/** |
|
251
|
|
|
* @param boolean $show The show description flag. |
|
252
|
|
|
* @return FormGroup Chainable |
|
253
|
|
|
*/ |
|
254
|
|
|
public function setShowDescription($show) |
|
255
|
|
|
{ |
|
256
|
|
|
$this->showDescription = !!$show; |
|
257
|
|
|
return $this; |
|
|
|
|
|
|
258
|
|
|
} |
|
259
|
|
|
|
|
260
|
|
|
/** |
|
261
|
|
|
* @return boolean |
|
262
|
|
|
*/ |
|
263
|
|
|
public function showDescription() |
|
264
|
|
|
{ |
|
265
|
|
|
if ($this->showTitle === false) { |
|
266
|
|
|
return false; |
|
267
|
|
|
} else { |
|
268
|
|
|
return !!$this->description(); |
|
269
|
|
|
} |
|
270
|
|
|
} |
|
271
|
|
|
|
|
272
|
|
|
/** |
|
273
|
|
|
* @param boolean $show The show notes flag. |
|
274
|
|
|
* @return FormGroup Chainable |
|
275
|
|
|
*/ |
|
276
|
|
|
public function setShowNotes($show) |
|
277
|
|
|
{ |
|
278
|
|
|
$this->showNotes = !!$show; |
|
279
|
|
|
return $this; |
|
|
|
|
|
|
280
|
|
|
} |
|
281
|
|
|
|
|
282
|
|
|
/** |
|
283
|
|
|
* Ensure there are are notes to show, if notes are to be shown. |
|
284
|
|
|
* @return boolean |
|
285
|
|
|
*/ |
|
286
|
|
|
public function showNotes() |
|
287
|
|
|
{ |
|
288
|
|
|
if ($this->showNotes === false) { |
|
289
|
|
|
return false; |
|
290
|
|
|
} else { |
|
291
|
|
|
$notes = $this->notes(); |
|
292
|
|
|
return !!$notes; |
|
293
|
|
|
} |
|
294
|
|
|
} |
|
295
|
|
|
|
|
296
|
|
|
/** |
|
297
|
|
|
* @param boolean $show The show header flag. |
|
298
|
|
|
* @return FormGroup Chainable |
|
299
|
|
|
*/ |
|
300
|
|
|
public function setShowHeader($show) |
|
301
|
|
|
{ |
|
302
|
|
|
$this->showHeader = !!$show; |
|
303
|
|
|
return $this; |
|
|
|
|
|
|
304
|
|
|
} |
|
305
|
|
|
|
|
306
|
|
|
/** |
|
307
|
|
|
* @return boolean |
|
308
|
|
|
*/ |
|
309
|
|
|
public function showHeader() |
|
310
|
|
|
{ |
|
311
|
|
|
if ($this->showHeader === false) { |
|
312
|
|
|
return false; |
|
313
|
|
|
} else { |
|
314
|
|
|
return $this->showTitle(); |
|
315
|
|
|
} |
|
316
|
|
|
} |
|
317
|
|
|
|
|
318
|
|
|
/** |
|
319
|
|
|
* @param boolean $show The show footer flag. |
|
320
|
|
|
* @return FormGroup Chainable |
|
321
|
|
|
*/ |
|
322
|
|
|
public function setShowFooter($show) |
|
323
|
|
|
{ |
|
324
|
|
|
$this->showFooger = !!$show; |
|
|
|
|
|
|
325
|
|
|
return $this; |
|
|
|
|
|
|
326
|
|
|
} |
|
327
|
|
|
|
|
328
|
|
|
/** |
|
329
|
|
|
* @return boolean |
|
330
|
|
|
*/ |
|
331
|
|
|
public function showFooter() |
|
332
|
|
|
{ |
|
333
|
|
|
if ($this->showFooter === false) { |
|
334
|
|
|
return false; |
|
335
|
|
|
} else { |
|
336
|
|
|
return $this->showNotes(); |
|
337
|
|
|
} |
|
338
|
|
|
} |
|
339
|
|
|
} |
|
340
|
|
|
|
If you return a value from a function or method, it should be a sub-type of the type that is given by the parent type f.e. an interface, or abstract method. This is more formally defined by the Lizkov substitution principle, and guarantees that classes that depend on the parent type can use any instance of a child type interchangably. This principle also belongs to the SOLID principles for object oriented design.
Let’s take a look at an example:
Our function
my_functionexpects aPostobject, and outputs the author of the post. The base classPostreturns a simple string and outputting a simple string will work just fine. However, the child classBlogPostwhich is a sub-type ofPostinstead decided to return anobject, and is therefore violating the SOLID principles. If aBlogPostwere passed tomy_function, PHP would not complain, but ultimately fail when executing thestrtouppercall in its body.