1: <?php
2:
3: namespace Charcoal\Ui;
4:
5: use InvalidArgumentException;
6:
7: /**
8: * Provides an implementation of {@see \Charcoal\Ui\UiItemInterface}.
9: */
10: trait UiItemTrait
11: {
12: /**
13: * The UI item type.
14: *
15: * @var string|null
16: */
17: private $type;
18:
19: /**
20: * The UI item's template.
21: *
22: * @var string|null
23: */
24: private $template;
25:
26: /**
27: * The UI item's title.
28: *
29: * @var \Charcoal\Translator\Translation
30: */
31: private $title = '';
32:
33: /**
34: * The UI item's sub-title.
35: *
36: * @var \Charcoal\Translator\Translation
37: */
38: private $subtitle = '';
39:
40: /**
41: * The UI item's description.
42: *
43: * @var \Charcoal\Translator\Translation
44: */
45: private $description = '';
46:
47: /**
48: * The UI item's notes.
49: *
50: * @var \Charcoal\Translator\Translation
51: */
52: private $notes = '';
53:
54: /**
55: * The title is displayed by default.
56: *
57: * @var boolean
58: */
59: private $showTitle = true;
60:
61: /**
62: * The sub-title is displayed by default.
63: *
64: * @var boolean
65: */
66: private $showSubtitle = true;
67:
68: /**
69: * The description is displayed by default.
70: *
71: * @var boolean
72: */
73: private $showDescription = true;
74:
75: /**
76: * The notes are displayed by default.
77: *
78: * @var boolean
79: */
80: private $showNotes = true;
81:
82: /**
83: * The header is displayed by default.
84: *
85: * @var boolean
86: */
87: private $showHeader = true;
88:
89: /**
90: * The footer is displayed by default.
91: *
92: * @var boolean
93: */
94: private $showFooter = true;
95:
96: /**
97: * The icon ident from font-awesome library
98: *
99: * @var string
100: */
101: private $icon;
102:
103: /**
104: * Set the UI item type.
105: *
106: * @param string|null $type The UI item type.
107: * @throws InvalidArgumentException If the type is not a string.
108: * @return UiItemInterface Chainable
109: */
110: public function setType($type)
111: {
112: if (is_string($type) || $type === null) {
113: $this->type = $type;
114: } else {
115: throw new InvalidArgumentException(
116: 'Can not set UI item config type: Type must be a string or NULL'
117: );
118: }
119:
120: return $this;
121: }
122:
123: /**
124: * Retrieve the UI item type.
125: *
126: * @return string
127: */
128: public function type()
129: {
130: return $this->type;
131: }
132:
133: /**
134: * Set the UI item's template.
135: *
136: * Usually, a path to a file containing the template to be rendered.
137: *
138: * @param string $template A template (identifier).
139: * @throws InvalidArgumentException If the template is not a string.
140: * @return UiItemInterface Chainable
141: */
142: public function setTemplate($template)
143: {
144: if (!is_string($template)) {
145: throw new InvalidArgumentException(
146: 'The UI Item can not set the template, must be a string'
147: );
148: }
149:
150: $this->template = $template;
151:
152: return $this;
153: }
154:
155: /**
156: * Retrieve the UI item's template.
157: *
158: * @return string If unset, returns the UI item type.
159: */
160: public function template()
161: {
162: if ($this->template === null) {
163: return $this->type();
164: }
165:
166: return $this->template;
167: }
168:
169: /**
170: * Set the UI item's title.
171: *
172: * @param mixed $title A title.
173: * @return UiItemInterface Chainable
174: */
175: public function setTitle($title)
176: {
177: $this->title = $this->translator()->translation($title);
178: return $this;
179: }
180:
181: /**
182: * Retrieve the title.
183: *
184: * @return \Charcoal\Translator\Translation|null
185: */
186: public function title()
187: {
188: return $this->title;
189: }
190:
191: /**
192: * Set the UI item's sub-title.
193: *
194: * @param mixed $subtitle A sub-title.
195: * @return UiItemInterface Chainable
196: */
197: public function setSubtitle($subtitle)
198: {
199: $this->subtitle = $this->translator()->translation($subtitle);
200: return $this;
201: }
202:
203: /**
204: * Retrieve the sub-title.
205: *
206: * @return \Charcoal\Translator\Translation|null
207: */
208: public function subtitle()
209: {
210: return $this->subtitle;
211: }
212:
213: /**
214: * Set the UI item's description.
215: *
216: * @param mixed $description A description.
217: * @return UiItemInterface Chainable
218: */
219: public function setDescription($description)
220: {
221: $this->description = $this->translator()->translation($description);
222: return $this;
223: }
224:
225: /**
226: * Retrieve the description.
227: *
228: * @return \Charcoal\Translator\Translation|null
229: */
230: public function description()
231: {
232: return $this->description;
233: }
234:
235: /**
236: * Set notes about the UI item.
237: *
238: * @param mixed $notes Notes.
239: * @return UiItemInterface Chainable
240: */
241: public function setNotes($notes)
242: {
243: $this->notes = $this->translator()->translation($notes);
244: return $this;
245: }
246:
247: /**
248: * Retrieve the notes.
249: *
250: * @return \Charcoal\Translator\Translation|null
251: */
252: public function notes()
253: {
254: return $this->notes;
255: }
256:
257: /**
258: * Show/hide the UI item's title.
259: *
260: * @param boolean $show Show (TRUE) or hide (FALSE) the title.
261: * @return UiItemInterface Chainable
262: */
263: public function setShowTitle($show)
264: {
265: $this->showTitle = !!$show;
266:
267: return $this;
268: }
269:
270: /**
271: * Determine if the title is to be displayed.
272: *
273: * @return boolean If TRUE or unset, check if there is a title.
274: */
275: public function showTitle()
276: {
277: if ($this->showTitle === false) {
278: return false;
279: } else {
280: return !!$this->title();
281: }
282: }
283:
284: /**
285: * Show/hide the UI item's sub-title.
286: *
287: * @param boolean $show Show (TRUE) or hide (FALSE) the sub-title.
288: * @return UiItemInterface Chainable
289: */
290: public function setShowSubtitle($show)
291: {
292: $this->showSubtitle = !!$show;
293:
294: return $this;
295: }
296:
297: /**
298: * Determine if the sub-title is to be displayed.
299: *
300: * @return boolean If TRUE or unset, check if there is a sub-title.
301: */
302: public function showSubtitle()
303: {
304: if ($this->showSubtitle === false) {
305: return false;
306: } else {
307: return !!$this->subtitle();
308: }
309: }
310:
311: /**
312: * Show/hide the UI item's description.
313: *
314: * @param boolean $show Show (TRUE) or hide (FALSE) the description.
315: * @return UiItemInterface Chainable
316: */
317: public function setShowDescription($show)
318: {
319: $this->showDescription = !!$show;
320:
321: return $this;
322: }
323:
324: /**
325: * Determine if the description is to be displayed.
326: *
327: * @return boolean If TRUE or unset, check if there is a description.
328: */
329: public function showDescription()
330: {
331: if ($this->showDescription === false) {
332: return false;
333: } else {
334: return !!$this->description();
335: }
336: }
337:
338: /**
339: * Show/hide the UI item's notes.
340: *
341: * @param boolean $show Show (TRUE) or hide (FALSE) the notes.
342: * @return UiItemInterface Chainable
343: */
344: public function setShowNotes($show)
345: {
346: $this->showNotes = !!$show;
347:
348: return $this;
349: }
350:
351: /**
352: * Determine if the notes is to be displayed.
353: *
354: * @return boolean If TRUE or unset, check if there are notes.
355: */
356: public function showNotes()
357: {
358: if ($this->showNotes === false) {
359: return false;
360: } else {
361: return !!$this->notes();
362: }
363: }
364:
365: /**
366: * Show/hide the UI item's header.
367: *
368: * @param boolean $show Show (TRUE) or hide (FALSE) the header.
369: * @return UiItemInterface Chainable
370: */
371: public function setShowHeader($show)
372: {
373: $this->showHeader = !!$show;
374:
375: return $this;
376: }
377:
378: /**
379: * Determine if the header is to be displayed.
380: *
381: * @return boolean If TRUE or unset, check if there is a title.
382: */
383: public function showHeader()
384: {
385: if ($this->showHeader === false) {
386: return false;
387: } else {
388: return $this->showTitle();
389: }
390: }
391:
392: /**
393: * Show/hide the UI item's footer.
394: *
395: * @param boolean $show Show (TRUE) or hide (FALSE) the footer.
396: * @return UiItemInterface Chainable
397: */
398: public function setShowFooter($show)
399: {
400: $this->showFooter = !!$show;
401:
402: return $this;
403: }
404:
405: /**
406: * Determine if the footer is to be displayed.
407: *
408: * @return boolean If TRUE or unset, check if there are notes.
409: */
410: public function showFooter()
411: {
412: if ($this->showFooter === false) {
413: return false;
414: } else {
415: return $this->showNotes();
416: }
417: }
418:
419: /**
420: * Retrieve the path to the item's icon.
421: *
422: * @todo [mcaskill 2016-09-16] Move this to a tab interface in charcoal-admin
423: * so as to focus the icon getter/setter on being a Glyphicon.
424: * @return string
425: */
426: public function icon()
427: {
428: return $this->icon;
429: }
430:
431: /**
432: * Set the path to the item's icon associated with the object.
433: *
434: * @param string $icon A path to an image.
435: * @return UiItemInterface Chainable
436: */
437: public function setIcon($icon)
438: {
439: $this->icon = $icon;
440:
441: return $this;
442: }
443:
444: /**
445: * @return \Charcoal\Translator\Translator
446: */
447: abstract protected function translator();
448: }
449: