Passed
Pull Request — master (#31)
by Mr.
06:01 queued 02:12
created

Toast::footerOptions()   A

Complexity

Conditions 1
Paths 1

Size

Total Lines 5
Code Lines 2

Duplication

Lines 0
Ratio 0 %

Code Coverage

Tests 0
CRAP Score 2

Importance

Changes 1
Bugs 0 Features 0
Metric Value
cc 1
eloc 2
c 1
b 0
f 0
nc 1
nop 1
dl 0
loc 5
ccs 0
cts 3
cp 0
crap 2
rs 10
1
<?php
2
3
declare(strict_types=1);
4
5
namespace Yiisoft\Yii\Bootstrap5;
6
7
use JsonException;
8
use Yiisoft\Arrays\ArrayHelper;
9
use Yiisoft\Html\Html;
10
11
use function array_merge;
12
13
/**
14
 * Toasts renders an toast bootstrap component.
15
 *
16
 * For example,
17
 *
18
 * ```php
19
  * Toast::widget()
20
 *     ->title('Hello world!')
21
 *     ->dateTime('a minute ago')
22
 *     ->body('Say hello...')
23
 * ])
24
 * ->begin();
25
 * ```
26
 *
27
 * The following example will show the content enclosed between the [[begin()]]
28
 * and [[end()]] calls within the toast box:
29
 *
30
 * ```php
31
 * Toast::widget()
32
 *     ->title('Hello world!')
33
 *     ->dateTime('a minute ago')
34
 * ])
35
 * ->begin();
36
 *
37
 * echo 'Say hello...';
38
 *
39
 * Toast::end();
40
 * ```
41
 *
42
 * @see https://getbootstrap.com/docs/components/toasts/
43
 * @author Simon Karlen <[email protected]>
44
 */
45
final class Toast extends Widget
46
{
47
    /**
48
     * @var string the body content in the alert component. Note that anything between
49
     * the [[begin()]] and [[end()]] calls of the Toast widget will also be treated
50
     * as the body content, and will be rendered before this.
51
     */
52
    private string $body = '';
53
    /**
54
     * @var string The title content in the toast.
55
     */
56
    private string $title = '';
57
    /**
58
     * @var string The footer content in the toast.
59
     */
60
    private string $footer = '';
61
    /**
62
     * @var string The date time the toast message references to.
63
     * This will be formatted as relative time (via formatter component). It will be omitted if
64
     * set to `false` (default).
65
     */
66
    private string $dateTime = '';
67
    /**
68
     * @var array the options for rendering the close button tag.
69
     * The close button is displayed in the header of the toast. Clicking on the button will hide the toast.
70
     *
71
     * The following special options are supported:
72
     *
73
     * - tag: string, the tag name of the button. Defaults to 'button'.
74
     * - label: string, the label of the button. Defaults to '&times;'.
75
     *
76
     * The rest of the options will be rendered as the HTML attributes of the button tag.
77
     * Please refer to the [Toast documentation](https://getbootstrap.com/docs/4.5/components/toasts/)
78
     * for the supported HTML attributes.
79
     */
80
    private array $closeButton = [];
81
    /**
82
     * @var array additional title options
83
     *
84
     * The following special options are supported:
85
     *
86
     * - tag: string, the tag name of the button. Defaults to 'strong'.
87
     *
88
     * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
89
     */
90
    public array $titleOptions = [];
91
    /**
92
     * @var array additional date time part options
93
     *
94
     * The following special options are supported:
95
     *
96
     * - tag: string, the tag name of the button. Defaults to 'small'.
97
     *
98
     * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
99
     */
100
    private array $dateTimeOptions = [];
101
    /**
102
     * @var array additional header options
103
     * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
104
     */
105
    private array $headerOptions = [];
106
    /**
107
     * @var array body options
108
     * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
109
     */
110
    private array $bodyOptions = [];
111
    /**
112
     * @var array options
113
     */
114
    private array $options = [];
115
    /**
116
     * @var array footer options
117
     * @see \yii\helpers\Html::renderTagAttributes() for details on how attributes are being rendered.
118
     */
119
    private array $footerOptions = [];
120
121 4
    public function begin(): ?string
122
    {
123 4
        parent::begin();
124
125 4
        if (!isset($this->options['id'])) {
126 4
            $this->options['id'] = "{$this->getId()}-toast";
127
        }
128
129 4
        $this->initOptions();
130
131
        return
132 4
            Html::beginTag('div', $this->options) . "\n" .
133 4
            $this->renderHeader() . "\n" .
134 4
            $this->renderBodyBegin() . "\n";
135
    }
136
137 4
    protected function run(): string
138
    {
139 4
        $this->registerPlugin('toast', $this->options);
140
141
        return
142 4
            "\n" . $this->renderBodyEnd() .
143 4
            "\n" . Html::endTag('div');
144
    }
145
146
    /**
147
     * Renders the header HTML markup of the toast.
148
     *
149
     * @throws JsonException
150
     *
151
     * @return string the rendering result
152
     */
153 4
    protected function renderHeader(): string
154
    {
155 4
        $button = $this->renderCloseButton();
156 4
        $tag = ArrayHelper::remove($this->titleOptions, 'tag', 'strong');
157 4
        Html::addCssClass($this->titleOptions, ['widget' => 'me-auto']);
158 4
        $title = Html::tag($tag, $this->title, $this->titleOptions);
159
160 4
        if ($this->dateTime !== '') {
161 2
            $tag = ArrayHelper::remove($this->dateTimeOptions, 'tag', 'small');
162 2
            $title .= "\n" . Html::tag($tag, $this->dateTime, $this->dateTimeOptions);
163
        }
164
165 4
        $title .= "\n" . $button;
166
167 4
        Html::addCssClass($this->headerOptions, ['widget' => 'toast-header']);
168 4
        return Html::div("\n" . $title . "\n", $this->headerOptions);
169
    }
170
171
    /**
172
     * Renders the opening tag of the toast body.
173
     *
174
     * @throws JsonException
175
     *
176
     * @return string the rendering result
177
     */
178 4
    protected function renderBodyBegin(): string
179
    {
180 4
        Html::addCssClass($this->bodyOptions, ['widget' => 'toast-body']);
181 4
        return Html::beginTag('div', $this->bodyOptions);
182
    }
183
184
    /**
185
     * Renders the closing tag of the toast body.
186
     *
187
     * @return string the rendering result
188
     */
189 4
    protected function renderBodyEnd(): string
190
    {
191 4
        return $this->body . "\n" . Html::endTag('div');
192
    }
193
194
    /**
195
     * Renders the close button.
196
     *
197
     * @throws JsonException
198
     *
199
     * @return string the rendering result
200
     */
201 4
    protected function renderCloseButton(): ?string
202
    {
203 4
        $tag = ArrayHelper::remove($this->closeButton, 'tag', 'button');
204 4
        $label = ArrayHelper::remove($this->closeButton, 'label', Html::tag('span', '&times;', [
205 4
            'aria-hidden' => 'true'
206
        ]));
207
208 4
        return Html::tag($tag, "\n" . $label . "\n", $this->closeButton);
209
    }
210
211
    /**
212
     * Initializes the widget options.
213
     *
214
     * This method sets the default values for various options.
215
     */
216 4
    protected function initOptions(): void
217
    {
218 4
        Html::addCssClass($this->options, ['widget' => 'toast']);
219
220 4
        $this->closeButton = array_merge([
221 4
            'aria' => ['label' => 'Close'],
222
            'data' => ['bs-dismiss' => 'toast'],
223
            'class' => ['widget' => 'btn-close'],
224
            'type' => 'button'
225 4
        ], $this->closeButton);
226
227 4
        if (!isset($this->options['role'])) {
228 4
            $this->options['role'] = 'alert';
229
        }
230
231 4
        if (!isset($this->options['aria']) && !isset($this->options['aria-live'])) {
232 4
            $this->options['aria'] = [
233
                'live' => 'assertive',
234
                'atomic' => 'true'
235
            ];
236
        }
237 4
    }
238
239
    /**
240
     * Body options.
241
     *
242
     * {@see \Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
243
     *
244
     * @param array $value
245
     *
246
     * @return $this
247
     */
248 1
    public function bodyOptions(array $value): self
249
    {
250 1
        $this->bodyOptions = $value;
251
252 1
        return $this;
253
    }
254
255
    /**
256
     * The options for rendering the close button tag.
257
     *
258
     * The close button is displayed in the header of the toast window. Clicking on the button will hide the toast
259
     * window. If {@see closeButtonEnabled} is false, no close button will be rendered.
260
     *
261
     * The following special options are supported:
262
     *
263
     * - tag: string, the tag name of the button. Defaults to 'button'.
264
     * - label: string, the label of the button. Defaults to '&times;'.
265
     *
266
     * The rest of the options will be rendered as the HTML attributes of the button tag. Please refer to the
267
     * [Toast plugin help](https://getbootstrap.com/docs/components/toasts/) for the supported HTML attributes.
268
     *
269
     * @param array $value
270
     *
271
     * @return $this
272
     */
273
    public function closeButton(array $value): self
274
    {
275
        $this->closeButton = $value;
276
277
        return $this;
278
    }
279
280
    /**
281
     * The date/time content in the toast window.
282
     *
283
     * @param string $value
284
     *
285
     * @return $this
286
     */
287 2
    public function dateTime(string $value): self
288
    {
289 2
        $this->dateTime = $value;
290
291 2
        return $this;
292
    }
293
294
    /**
295
     * Additional DateTime options.
296
     *
297
     * @param array $value
298
     *
299
     * @return $this
300
     *
301
     * {@see \Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
302
     */
303 1
    public function dateTimeOptions(array $value): self
304
    {
305 1
        $this->dateTimeOptions = $value;
306
307 1
        return $this;
308
    }
309
310
    /**
311
     * The footer content in the toast window.
312
     *
313
     * @param string|null $value
314
     *
315
     * @return $this
316
     */
317
    public function footer(?string $value): self
318
    {
319
        $this->footer = $value;
320
321
        return $this;
322
    }
323
324
    /**
325
     * Additional footer options.
326
     *
327
     * @param array $value
328
     *
329
     * @return $this
330
     *
331
     * {@see \Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
332
     */
333
    public function footerOptions(array $value): self
334
    {
335
        $this->footerOptions = $value;
336
337
        return $this;
338
    }
339
340
    /**
341
     * Additional header options.
342
     *
343
     * @param array $value
344
     *
345
     * @return $this
346
     *
347
     * {@see \Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
348
     */
349
    public function headerOptions(array $value): self
350
    {
351
        $this->headerOptions = $value;
352
353
        return $this;
354
    }
355
356
    /**
357
     * @param array $value the HTML attributes for the widget container tag. The following special options are
358
     * recognized.
359
     *
360
     * @return $this
361
     *
362
     * {@see \Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
363
     */
364
    public function options(array $value): self
365
    {
366
        $this->options = $value;
367
368
        return $this;
369
    }
370
371
    /**
372
     * The title content in the toast window.
373
     *
374
     * @param string|null $value
375
     *
376
     * @return $this
377
     */
378 3
    public function title(?string $value): self
379
    {
380 3
        $this->title = $value;
381
382 3
        return $this;
383
    }
384
385
    /**
386
     * Additional title options.
387
     *
388
     * {@see \Yiisoft\Html\Html::renderTagAttributes()} for details on how attributes are being rendered.
389
     *
390
     * @param array $value
391
     *
392
     * @return $this
393
     */
394 1
    public function titleOptions(array $value): self
395
    {
396 1
        $this->titleOptions = $value;
397
398 1
        return $this;
399
    }
400
}
401