Debian Codegraph @

vendor/ipl/web/src/Layout/ItemLayout.php

raw
1 <?php
2
3 namespace ipl\Web\Layout;
4
5 use ipl\Html\Attributes;
6 use ipl\Html\HtmlDocument;
7 use ipl\Html\HtmlElement;
8 use ipl\Web\Common\ItemRenderer;
9
10 /**
11 * Layout for items
12 *
13 * @phpstan-type _SECTION1 = static::VISUAL|static::MAIN|static::HEADER|static::FOOTER
14 * @phpstan-type SECTION = _SECTION1|static::CAPTION|static::TITLE|static::EXTENDED_INFO
15 * @template Item
16 */
17 class ItemLayout extends HtmlDocument
18 {
19 /** The name of this layout */
20 public const NAME = 'common';
21
22 /** Identifier for the section containing an item's visual representation */
23 public const VISUAL = 'visual';
24
25 /** Identifier for the section containing an item's main content */
26 public const MAIN = 'main';
27
28 /** Identifier for the section containing an item's header */
29 public const HEADER = 'header';
30
31 /** Identifier for the section containing an item's footer */
32 public const FOOTER = 'footer';
33
34 /** Identifier for the section containing an item's caption */
35 public const CAPTION = 'caption';
36
37 /** Identifier for the section containing an item's title */
38 public const TITLE = 'title';
39
40 /** Identifier for the section containing an item's extended information */
41 public const EXTENDED_INFO = 'extended-info';
42
43 /** @var Item */
44 protected $item;
45
46 /** @var ItemRenderer */
47 protected $renderer;
48
49 /** @var array<SECTION, string> */
50 protected $before = [];
51
52 /** @var array<SECTION, string> */
53 protected $after = [];
54
55 /**
56 * Create a new layout for items
57 *
58 * @param Item $item The item to render
59 * @param ItemRenderer<Item> $renderer The renderer used to assemble the layout's content
60 */
61 public function __construct($item, ItemRenderer $renderer)
62 {
63 $this->item = $item;
64 $this->renderer = $renderer;
65 }
66
67 /**
68 * Get the name of this layout
69 *
70 * @return string
71 */
72 public function getName(): string
73 {
74 return static::NAME;
75 }
76
77 /**
78 * Create attributes for this layout
79 *
80 * @param Attributes $attributes
81 *
82 * @return void
83 */
84 protected function createAttributes(Attributes $attributes): void
85 {
86 $attributes->get('class')->addValue(['item-layout', 'default-item-layout']);
87 }
88
89 /**
90 * Get attributes to apply to the container the layout is added to
91 *
92 * @return Attributes
93 */
94 public function getAttributes(): Attributes
95 {
96 $attributes = new Attributes();
97 $this->createAttributes($attributes);
98 $this->renderer->assembleAttributes($this->item, $attributes, $this->getName());
99
100 return $attributes;
101 }
102
103 /**
104 * Create a container for the visual representation of the item
105 *
106 * @return HtmlDocument
107 */
108 protected function createVisual(): HtmlDocument
109 {
110 return new HtmlElement('div', Attributes::create(['class' => static::VISUAL]));
111 }
112
113 /**
114 * Assemble the visual representation of the item in the given container
115 *
116 * @return void
117 */
118 protected function assembleVisual(HtmlDocument $container)
119 {
120 $this->renderer->assembleVisual($this->item, $container, $this->getName());
121 }
122
123 /**
124 * Create, assemble and register the visual representation of the item
125 *
126 * @param HtmlDocument $container
127 *
128 * @return void
129 */
130 protected function registerVisual(HtmlDocument $container): void
131 {
132 $visual = $this->createVisual();
133
134 $this->createBefore(static::VISUAL, $container);
135
136 $this->assembleVisual($visual);
137 if ($visual->isEmpty()) {
138 return;
139 }
140
141 $container->addHtml($visual);
142
143 $this->createAfter(static::VISUAL, $container);
144 }
145
146 /**
147 * Create a container for the main content of the item
148 *
149 * @return HtmlDocument
150 */
151 protected function createMain(): HtmlDocument
152 {
153 return new HtmlElement('div', Attributes::create(['class' => static::MAIN]));
154 }
155
156 /**
157 * Assemble the main content of the item in the given container
158 *
159 * @param HtmlDocument $container
160 *
161 * @return void
162 */
163 protected function assembleMain(HtmlDocument $container): void
164 {
165 $this->registerHeader($container);
166 $this->registerCaption($container);
167 }
168
169 /**
170 * Create, assemble and register the main content of the item
171 *
172 * @param HtmlDocument $container
173 *
174 * @return void
175 */
176 protected function registerMain(HtmlDocument $container): void
177 {
178 $main = $this->createMain();
179
180 $this->createBefore(static::MAIN, $container);
181
182 $this->assembleMain($main);
183
184 $container->addHtml($main);
185
186 $this->createAfter(static::MAIN, $container);
187 }
188
189 /**
190 * Create a container for the header of the item
191 *
192 * @return HtmlDocument
193 */
194 protected function createHeader(): HtmlDocument
195 {
196 return new HtmlElement('header');
197 }
198
199 /**
200 * Assemble the header of the item in the given container
201 *
202 * @param HtmlDocument $container
203 *
204 * @return void
205 */
206 protected function assembleHeader(HtmlDocument $container): void
207 {
208 $this->registerTitle($container);
209 $this->registerExtendedInfo($container);
210 }
211
212 /**
213 * Create, assemble and register the header of the item
214 *
215 * @param HtmlDocument $container
216 *
217 * @return void
218 */
219 protected function registerHeader(HtmlDocument $container): void
220 {
221 $header = $this->createHeader();
222
223 $this->createBefore(static::HEADER, $container);
224
225 $this->assembleHeader($header);
226
227 $container->addHtml($header);
228
229 $this->createAfter(static::HEADER, $container);
230 }
231
232 /**
233 * Create a container for the footer of the item
234 *
235 * @return HtmlDocument
236 */
237 protected function createFooter(): HtmlDocument
238 {
239 return new HtmlElement('footer');
240 }
241
242 /**
243 * Assemble the footer of the item in the given container
244 *
245 * @param HtmlDocument $container
246 *
247 * @return void
248 */
249 protected function assembleFooter(HtmlDocument $container): void
250 {
251 $this->renderer->assembleFooter($this->item, $container, $this->getName());
252 }
253
254 /**
255 * Create, assemble and register the footer of the item
256 *
257 * @param HtmlDocument $container
258 *
259 * @return void
260 */
261 protected function registerFooter(HtmlDocument $container): void
262 {
263 $footer = $this->createFooter();
264
265 $this->createBefore(static::FOOTER, $container);
266
267 $this->assembleFooter($footer);
268 if ($footer->isEmpty()) {
269 return;
270 }
271
272 $container->addHtml($footer);
273
274 $this->createAfter(static::FOOTER, $container);
275 }
276
277 /**
278 * Create a container for the caption of the item
279 *
280 * @return HtmlDocument
281 */
282 protected function createCaption(): HtmlDocument
283 {
284 return new HtmlElement('section', Attributes::create(['class' => static::CAPTION]));
285 }
286
287 /**
288 * Assemble the caption of the item in the given container
289 *
290 * @param HtmlDocument $container
291 *
292 * @return void
293 */
294 protected function assembleCaption(HtmlDocument $container): void
295 {
296 $this->renderer->assembleCaption($this->item, $container, $this->getName());
297 }
298
299 /**
300 * Create, assemble and register the caption of the item
301 *
302 * @param HtmlDocument $container
303 *
304 * @return void
305 */
306 protected function registerCaption(HtmlDocument $container): void
307 {
308 $caption = $this->createCaption();
309
310 $this->createBefore(static::CAPTION, $container);
311
312 $this->assembleCaption($caption);
313
314 $container->addHtml($caption);
315
316 $this->createAfter(static::CAPTION, $container);
317 }
318
319 /**
320 * Create a container for the title of the item
321 *
322 * @return HtmlDocument
323 */
324 protected function createTitle(): HtmlDocument
325 {
326 return new HtmlElement('div', Attributes::create(['class' => static::TITLE]));
327 }
328
329 /**
330 * Assemble the title of the item in the given container
331 *
332 * @param HtmlDocument $container
333 *
334 * @return void
335 */
336 protected function assembleTitle(HtmlDocument $container): void
337 {
338 $this->renderer->assembleTitle($this->item, $container, $this->getName());
339 }
340
341 /**
342 * Create, assemble and register the title of the item
343 *
344 * @param HtmlDocument $container
345 *
346 * @return void
347 */
348 protected function registerTitle(HtmlDocument $container): void
349 {
350 $title = $this->createTitle();
351
352 $this->createBefore(static::TITLE, $container);
353
354 $this->assembleTitle($title);
355
356 $container->addHtml($title);
357
358 $this->createAfter(static::TITLE, $container);
359 }
360
361 /**
362 * Create a container for the extended information of the item
363 *
364 * @return HtmlDocument
365 */
366 protected function createExtendedInfo(): HtmlDocument
367 {
368 return new HtmlElement('div', Attributes::create(['class' => static::EXTENDED_INFO]));
369 }
370
371 /**
372 * Assemble the extended information of the item in the given container
373 *
374 * @param HtmlDocument $container
375 *
376 * @return void
377 */
378 protected function assembleExtendedInfo(HtmlDocument $container): void
379 {
380 $this->renderer->assembleExtendedInfo($this->item, $container, $this->getName());
381 }
382
383 /**
384 * Create, assemble and register the extended information of the item
385 *
386 * @param HtmlDocument $container
387 *
388 * @return void
389 */
390 protected function registerExtendedInfo(HtmlDocument $container): void
391 {
392 $info = $this->createExtendedInfo();
393
394 $this->createBefore(static::EXTENDED_INFO, $container);
395
396 $this->assembleExtendedInfo($info);
397 if ($info->isEmpty()) {
398 return;
399 }
400
401 $container->addHtml($info);
402
403 $this->createAfter(static::EXTENDED_INFO, $container);
404 }
405
406 /**
407 * Render a custom section before the given one
408 *
409 * @param SECTION $section Identifier of the target section
410 * @param string $customSection Identifier for the custom section
411 *
412 * @return void
413 */
414 public function before(string $section, string $customSection): void
415 {
416 $this->before[$section] = $customSection;
417 }
418
419 /**
420 * Add a custom section before the given one
421 *
422 * @param SECTION $section Identifier of the target section
423 * @param HtmlDocument $container The container to add the custom section to
424 *
425 * @return void
426 */
427 protected function createBefore(string $section, HtmlDocument $container): void
428 {
429 if (isset($this->before[$section])) {
430 $customSection = new HtmlElement('div', Attributes::create(['class' => $this->before[$section]]));
431 if ($this->renderer->assemble($this->item, $this->before[$section], $customSection, $this->getName())) {
432 $container->addHtml($customSection);
433 }
434 }
435 }
436
437 /**
438 * Render a custom section after the given one
439 *
440 * @param SECTION $section Identifier of the target section
441 * @param string $customSection Identifier for the custom section
442 *
443 * @return void
444 */
445 public function after(string $section, string $customSection): void
446 {
447 $this->after[$section] = $customSection;
448 }
449
450 /**
451 * Add a custom section after the given one
452 *
453 * @param SECTION $section Identifier of the target section
454 * @param HtmlDocument $container The container to add the custom section to
455 *
456 * @return void
457 */
458 protected function createAfter(string $section, HtmlDocument $container): void
459 {
460 if (isset($this->after[$section])) {
461 $customSection = new HtmlElement('div', Attributes::create(['class' => $this->after[$section]]));
462 if ($this->renderer->assemble($this->item, $this->after[$section], $customSection, $this->getName())) {
463 $container->addHtml($customSection);
464 }
465 }
466 }
467
468 /**
469 * Assemble the layout
470 *
471 * @return void
472 */
473 protected function assemble(): void
474 {
475 $this->registerVisual($this);
476 $this->registerMain($this);
477 }
478 }