Passed
Push — master ( b5cfd6...ee46ce )
by P.R.
07:54
created

HtmlElement::unsetClass()   A

Complexity

Conditions 1
Paths 1

Size

Total Lines 5
Code Lines 2

Duplication

Lines 0
Ratio 0 %

Code Coverage

Tests 3
CRAP Score 1

Importance

Changes 0
Metric Value
cc 1
eloc 2
nc 1
nop 0
dl 0
loc 5
ccs 3
cts 3
cp 1
crap 1
rs 10
c 0
b 0
f 0
1
<?php
2
declare(strict_types=1);
3
4
namespace Plaisio\Helper;
5
6
/**
7
 * Trait for HTML elements.
8
 *
9
 * This class should be used for generation "heavy" HTML elements only. For light weight elements use methods of
10
 * {@link \Plaisio\Helper\Html}.
11
 *
12
 * #### Global Attributes
13
 * This class defines methods for getting attributes and setting
14
 * [global attributes](http://www.w3schools.com/tags/ref_standardattributes.asp) only.
15
 *
16
 * Unless stated otherwise setting an attribute to null, false, or '' will unset the attribute.
17
 *
18
 * #### Event Attributes
19
 * This class does not define methods for setting event attributes. Events handlers must be set with JavaScript.
20
 */
21
trait HtmlElement
22
{
23
  //--------------------------------------------------------------------------------------------------------------------
24
  /**
25
   * The attributes of this HTML element.
26
   *
27
   * @var array
28
   *
29
   * @since 1.0.0
30
   * @api
31
   */
32
  protected array $attributes = [];
33
34
  //--------------------------------------------------------------------------------------------------------------------
35
  /**
36
   * Adds a class to the list of classes.
37
   *
38
   * @param string|null $class The class.
39
   *
40
   * @return $this
41
   *
42
   * @since 1.0.0
43
   * @api
44
   */
45 7
  public function addClass(?string $class): self
46
  {
47 7
    if ($class===null || $class==='')
48
    {
49 2
      return $this;
50
    }
51
52 5
    if (empty($this->attributes['class']))
53
    {
54 3
      $this->attributes['class'] = [];
55
    }
56 3
    elseif (is_string($this->attributes['class']))
57
    {
58 1
      $this->attributes['class'] = explode(' ', $this->attributes['class']);
59
    }
60
61 5
    $this->attributes['class'][] = $class;
62
63 5
    return $this;
64
  }
65
66
  //--------------------------------------------------------------------------------------------------------------------
67
  /**
68
   * Adds classes to the list of classes.
69
   *
70
   * @param array $classes The classes.
71
   *
72
   * @return $this
73
   *
74
   * @since 1.5.0
75
   * @api
76
   */
77 4
  public function addClasses(array $classes): self
78
  {
79 4
    if (empty($this->attributes['class']))
80
    {
81 3
      $this->attributes['class'] = [];
82
    }
83 2
    elseif (is_string($this->attributes['class']))
84
    {
85 1
      $this->attributes['class'] = explode(' ', $this->attributes['class']);
86
    }
87
88 4
    foreach ($classes as $class)
89
    {
90 4
      $this->attributes['class'][] = $class;
91
    }
92
93 4
    return $this;
94
  }
95
96
  //--------------------------------------------------------------------------------------------------------------------
97
  /**
98
   * Returns the value of an attribute.
99
   *
100
   * @param string $attributeName The name of the attribute.
101
   *
102
   * @return mixed
103
   *
104
   * @since 1.0.0
105
   * @api
106
   */
107 3
  public function getAttribute(string $attributeName)
108
  {
109 3
    return $this->attributes[$attributeName] ?? null;
110
  }
111
112
  //--------------------------------------------------------------------------------------------------------------------
113
  /**
114
   * Returns the attributes of this HTML element.
115
   *
116
   * @return array
117
   */
118 1
  public function getAttributes(): array
119
  {
120 1
    return $this->attributes;
121
  }
122
123
  //--------------------------------------------------------------------------------------------------------------------
124
  /**
125
   * Returns the mandatory attribute [id](http://www.w3schools.com/tags/att_global_id.asp) of this element. If the id
126
   * attribute was not set prior calling this method the id attribute will set with a automatically generate value.
127
   *
128
   * @return string
129
   *
130
   * @since 1.4.0
131
   * @api
132
   */
133 1
  public function getId(): string
134
  {
135 1
    $this->attributes['id'] ??= Html::getAutoId();
136
137 1
    return $this->attributes['id'];
138
  }
139
140
  //--------------------------------------------------------------------------------------------------------------------
141
  /**
142
   * Removes a class from the list of classes.
143
   *
144
   * @param string|null $class The class to be removed.
145
   *
146
   * @return $this
147
   *
148
   * @since 1.0.0
149
   * @api
150
   */
151 5
  public function removeClass(?string $class): self
152
  {
153
    // If class is empty or no classes are set return immediately.
154 5
    if ($class===null || $class==='' || !isset($this->attributes['class'])) return $this;
155
156 3
    $this->attributes['class'] = array_unique($this->attributes['class']);
157 3
    $key                       = array_search($class, $this->attributes['class']);
158 3
    if ($key!==false)
159
    {
160 3
      unset($this->attributes['class'][$key]);
161
    }
162
163 3
    return $this;
164
  }
165
166
  //--------------------------------------------------------------------------------------------------------------------
167
  /**
168
   * Sets the attribute [accesskey](http://www.w3schools.com/tags/att_global_accesskey.asp).
169
   *
170
   * @param string|null $value The attribute value.
171
   *
172
   * @return $this
173
   *
174
   * @api
175
   * @since 1.0.0
176
   */
177 1
  public function setAttrAccessKey(?string $value): self
178
  {
179 1
    $this->attributes['accesskey'] = $value;
180
181 1
    return $this;
182
  }
183
184
  //--------------------------------------------------------------------------------------------------------------------
185
  /**
186
   * Sets a [aria](http://w3c.github.io/html/infrastructure.html#element-attrdef-aria-aria) attribute.
187
   *
188
   * @param string      $name  The name of the attribute (without 'aria-').
189
   * @param string|null $value The attribute value.
190
   *
191
   * @return $this
192
   *
193
   * @since 1.3.0
194
   * @api
195
   */
196 1
  public function setAttrAria(string $name, ?string $value): self
197
  {
198 1
    $this->attributes['aria-'.$name] = $value;
199
200 1
    return $this;
201
  }
202
203
  //--------------------------------------------------------------------------------------------------------------------
204
  /**
205
   * Sets the attribute [class](https://www.w3schools.com/tags/att_global_class.asp).
206
   *
207
   * @param string|null $value The class or classes. Any value set by {@link addClass} will be overwritten.
208
   *
209
   * @return $this
210
   *
211
   * @since 1.4.0
212
   * @api
213
   */
214 4
  public function setAttrClass(?string $value): self
215
  {
216 4
    if ($value===null || $value==='')
217
    {
218 1
      unset($this->attributes['class']);
219
    }
220
    else
221
    {
222 4
      $this->attributes['class'] = [$value];
223
    }
224
225 4
    return $this;
226
  }
227
228
  //--------------------------------------------------------------------------------------------------------------------
229
  /**
230
   * Sets the attribute [contenteditable](http://www.w3schools.com/tags/att_global_contenteditable.asp).
231
   * <ul>
232
   * <li> Any value that evaluates to true will set the attribute to 'true'.
233
   * <li> Any value that evaluates to false will set the attribute to 'false'.
234
   * <li> Null will unset the attribute.
235
   * </ul>
236
   *
237
   * @param mixed $value The attribute value.
238
   *
239
   * @return $this
240
   *
241
   * @since 1.0.0
242
   * @api
243
   */
244 1
  public function setAttrContentEditable(?string $value): self
245
  {
246 1
    $this->attributes['contenteditable'] = $value;
247
248 1
    return $this;
249
  }
250
251
  //--------------------------------------------------------------------------------------------------------------------
252
  /**
253
   * Sets the attribute [contextmenu](http://www.w3schools.com/tags/att_global_contextmenu.asp).
254
   *
255
   * @param string|null $value The attribute value.
256
   *
257
   * @return $this
258
   *
259
   * @since 1.0.0
260
   * @api
261
   */
262 1
  public function setAttrContextMenu(?string $value): self
263
  {
264 1
    $this->attributes['contextmenu'] = $value;
265
266 1
    return $this;
267
  }
268
269
  //--------------------------------------------------------------------------------------------------------------------
270
  /**
271
   * Sets a [data](http://www.w3schools.com/tags/att_global_data.asp) attribute.
272
   *
273
   * @param string      $name  The name of the attribute (without 'data-').
274
   * @param string|null $value The attribute value.
275
   *
276
   * @return $this
277
   *
278
   * @since 1.0.0
279
   * @api
280
   */
281 1
  public function setAttrData(string $name, ?string $value): self
282
  {
283 1
    $this->attributes['data-'.$name] = $value;
284
285 1
    return $this;
286
  }
287
288
  //--------------------------------------------------------------------------------------------------------------------
289
  /**
290
   * Sets the attribute [dir](http://www.w3schools.com/tags/att_global_dir.asp). Possible values:
291
   * <ul>
292
   * <li> ltr
293
   * <li> rtl
294
   * <li> auto
295
   * </ul>
296
   *
297
   * @param string|null $value The attribute value.
298
   *
299
   * @return $this
300
   *
301
   * @since 1.0.0
302
   * @api
303
   */
304 1
  public function setAttrDir(?string $value): self
305
  {
306 1
    $this->attributes['dir'] = $value;
307
308 1
    return $this;
309
  }
310
311
  //--------------------------------------------------------------------------------------------------------------------
312
  /**
313
   * Sets the attribute [draggable](http://www.w3schools.com/tags/att_global_draggable.asp). Possible values:
314
   * <ul>
315
   * <li> true
316
   * <li> false
317
   * <li> auto
318
   * </ul>
319
   *
320
   * @param string|null $value The attribute value.
321
   *
322
   * @return $this
323
   *
324
   * @since 1.0.0
325
   * @api
326
   */
327 1
  public function setAttrDraggable(?string $value): self
328
  {
329 1
    $this->attributes['draggable'] = $value;
330
331 1
    return $this;
332
  }
333
334
  //--------------------------------------------------------------------------------------------------------------------
335
  /**
336
   * Sets the attribute [dropzone](http://www.w3schools.com/tags/att_global_dropzone.asp).
337
   *
338
   * @param string|null $value The attribute value.
339
   *
340
   * @return $this
341
   *
342
   * @since 1.0.0
343
   * @api
344
   */
345 1
  public function setAttrDropZone(?string $value): self
346
  {
347 1
    $this->attributes['dropzone'] = $value;
348
349 1
    return $this;
350
  }
351
352
  //--------------------------------------------------------------------------------------------------------------------
353
  /**
354
   * Sets the attribute [hidden](http://www.w3schools.com/tags/att_global_hidden.asp).
355
   * This is a boolean attribute. Any none [empty](http://php.net/manual/function.empty.php) value will set the
356
   * attribute to 'hidden'. Any other value will unset the attribute.
357
   *
358
   * @param mixed $value The attribute value.
359
   *
360
   * @return $this
361
   *
362
   * @since 1.0.0
363
   * @api
364
   */
365 1
  public function setAttrHidden(?string $value): self
366
  {
367 1
    $this->attributes['hidden'] = $value;
368
369 1
    return $this;
370
  }
371
372
  //--------------------------------------------------------------------------------------------------------------------
373
  /**
374
   * Sets the attribute [id](http://www.w3schools.com/tags/att_global_id.asp).
375
   *
376
   * @param string|null $value The attribute value.
377
   *
378
   * @return $this
379
   *
380
   * @since 1.0.0
381
   * @api
382
   */
383 2
  public function setAttrId(?string $value): self
384
  {
385 2
    $this->attributes['id'] = $value;
386
387 2
    return $this;
388
  }
389
390
  //--------------------------------------------------------------------------------------------------------------------
391
  /**
392
   * Sets the attribute [lang](http://www.w3schools.com/tags/att_global_lang.asp).
393
   *
394
   * @param string|null $value The attribute value.
395
   *
396
   * @return $this
397
   *
398
   * @since 1.0.0
399
   * @api
400
   */
401 1
  public function setAttrLang(?string $value): self
402
  {
403 1
    $this->attributes['lang'] = $value;
404
405 1
    return $this;
406
  }
407
408
  //--------------------------------------------------------------------------------------------------------------------
409
  /**
410
   * Sets the attribute [role](http://w3c.github.io/html/infrastructure.html#element-attrdef-aria-role).
411
   *
412
   * @param string|null $value The attribute value.
413
   *
414
   * @return $this
415
   *
416
   * @since 1.3.0
417
   * @api
418
   */
419 1
  public function setAttrRole(?string $value): self
420
  {
421 1
    $this->attributes['role'] = $value;
422
423 1
    return $this;
424
  }
425
426
  //--------------------------------------------------------------------------------------------------------------------
427
  /**
428
   * Sets the attribute [spellcheck](http://www.w3schools.com/tags/att_global_spellcheck.asp).
429
   * <ul>
430
   * <li> Any value that evaluates to true will set the attribute to 'true'.
431
   * <li> Any value that evaluates to false will set the attribute to 'false'.
432
   * <li> Null will unset the attribute.
433
   * <ul>
434
   *
435
   * @param string|null $value The attribute value.
436
   *
437
   * @return $this
438
   *
439
   * @since 1.0.0
440
   * @api
441
   */
442 1
  public function setAttrSpellCheck(?string $value): self
443
  {
444 1
    $this->attributes['spellcheck'] = $value;
445
446 1
    return $this;
447
  }
448
449
  //--------------------------------------------------------------------------------------------------------------------
450
  /**
451
   * Sets the attribute [style](http://www.w3schools.com/tags/att_global_style.asp)
452
   *
453
   * @param string|null $value The attribute value.
454
   *
455
   * @return $this
456
   *
457
   * @since 1.0.0
458
   * @api
459
   */
460 1
  public function setAttrStyle(?string $value): self
461
  {
462 1
    $this->attributes['style'] = $value;
463
464 1
    return $this;
465
  }
466
467
  //--------------------------------------------------------------------------------------------------------------------
468
  /**
469
   * Sets the attribute [tabindex](http://www.w3schools.com/tags/att_global_tabindex.asp).
470
   *
471
   * @param int|null $value The attribute value.
472
   *
473
   * @return $this
474
   *
475
   * @since 1.0.0
476
   * @api
477
   */
478 1
  public function setAttrTabIndex(?int $value): self
479
  {
480 1
    $this->attributes['tabindex'] = $value;
481
482 1
    return $this;
483
  }
484
485
  //--------------------------------------------------------------------------------------------------------------------
486
  /**
487
   * Sets the attribute [title](http://www.w3schools.com/tags/att_global_title.asp).
488
   *
489
   * @param string|null $value The attribute value.
490
   *
491
   * @return $this
492
   *
493
   * @since 1.0.0
494
   * @api
495
   */
496 1
  public function setAttrTitle(?string $value): self
497
  {
498 1
    $this->attributes['title'] = $value;
499
500 1
    return $this;
501
  }
502
503
  //--------------------------------------------------------------------------------------------------------------------
504
  /**
505
   * Sets the attribute [translate](http://www.w3schools.com/tags/att_global_translate.asp).
506
   * <ul>
507
   * <li> Any value that evaluates to true will set the attribute to 'yes'.
508
   * <li> Any value that evaluates to false will set the attribute to 'no'.
509
   * <li> Null will unset the attribute.
510
   * </ul>
511
   *
512
   * @param mixed $value The attribute value.
513
   *
514
   * @return $this
515
   *
516
   * @since 1.0.0
517
   * @api
518
   */
519 1
  public function setAttrTranslate(?string $value): self
520
  {
521 1
    $this->attributes['translate'] = $value;
522
523 1
    return $this;
524
  }
525
526
  //--------------------------------------------------------------------------------------------------------------------
527
  /**
528
   * Removes all classes for the list of classes.
529
   *
530
   * @return $this
531
   *
532
   * @since 1.0.0
533
   * @api
534
   */
535 1
  public function unsetClass(): self
536
  {
537 1
    unset($this->attributes['class']);
538
539 1
    return $this;
540
  }
541
542
  //--------------------------------------------------------------------------------------------------------------------
543
}
544
545
//----------------------------------------------------------------------------------------------------------------------
546