Debian Codegraph @

vendor/ipl/web/src/Widget/ItemList.php

raw
1 <?php
2
3 namespace ipl\Web\Widget;
4
5 use InvalidArgumentException;
6 use ipl\Html\BaseHtmlElement;
7 use ipl\Html\Html;
8 use ipl\Html\Text;
9 use ipl\Html\ValidHtml;
10 use ipl\I18n\Translation;
11 use ipl\Orm\ResultSet;
12 use ipl\Web\Common\ItemRenderer;
13 use ipl\Web\Layout\ItemLayout;
14
15 /**
16 * ItemList
17 *
18 * @template Result of object
19 * @template Item of object = Result
20 */
21 class ItemList extends BaseHtmlElement
22 {
23 use Translation;
24
25 /** @var string Emitted while assembling the list after adding each list item */
26 public const ON_ITEM_ADD = 'item-added';
27
28 /** @var string Emitted while assembling the list before adding each list item */
29 public const BEFORE_ITEM_ADD = 'before-item-add';
30
31 /** @var ResultSet|iterable<Result> */
32 protected $data;
33
34 /** @var ItemRenderer|callable */
35 protected $itemRenderer;
36
37 /** @var string */
38 private $itemLayoutClass = ItemLayout::class;
39
40 /** @var ?ValidHtml Message to show if the list is empty */
41 protected $emptyStateMessage;
42
43 /** @var array<string, mixed> */
44 protected $baseAttributes = [
45 'class' => 'item-list',
46 'data-base-target' => '_next',
47 'data-pdfexport-page-breaks-at' => '.list-item'
48 ];
49
50 protected $tag = 'ul';
51
52 /**
53 * Create a new item list
54 *
55 * @param ResultSet|iterable<Result> $data
56 * @param ItemRenderer<Item>|callable $itemRenderer If a callable is passed,
57 * it must accept an item as first argument
58 */
59 public function __construct($data, $itemRenderer)
60 {
61 if (! is_iterable($data)) {
62 throw new InvalidArgumentException('Data must be an array or an instance of Traversable');
63 }
64
65 $this->data = $data;
66 $this->itemRenderer = $itemRenderer;
67
68 $this->addAttributes($this->baseAttributes);
69
70 $this->init();
71 }
72
73 /**
74 * Initialize the item list
75 *
76 * If you want to adjust the item list after construction, override this method.
77 */
78 protected function init(): void
79 {
80 }
81
82 /**
83 * Set the layout class for the items
84 *
85 * @param string $class Must be an instance of the previously set item layout class
86 *
87 * @return $this
88 *
89 * @throws InvalidArgumentException If the class is not a subclass of {@see ItemLayout}
90 */
91 public function setItemLayoutClass(string $class): self
92 {
93 if ($class !== $this->itemLayoutClass && ! is_subclass_of($class, $this->itemLayoutClass)) {
94 throw new InvalidArgumentException("Class $class must be a subclass of " . $this->itemLayoutClass);
95 }
96
97 $this->itemLayoutClass = $class;
98
99 return $this;
100 }
101
102 /**
103 * Get the layout for the given item
104 *
105 * @param Item $item
106 *
107 * @return ItemLayout
108 */
109 public function getItemLayout($item): ItemLayout
110 {
111 return new $this->itemLayoutClass($item, $this->getItemRenderer($item));
112 }
113
114 /**
115 * Get message to show if the list is empty
116 *
117 * @return ValidHtml
118 */
119 public function getEmptyStateMessage(): ValidHtml
120 {
121 if ($this->emptyStateMessage === null) {
122 return new Text($this->translate('No items found.'));
123 }
124
125 return $this->emptyStateMessage;
126 }
127
128 /**
129 * Set message to show if the list is empty
130 *
131 * @param mixed $message If empty, the default message is used
132 *
133 * @return $this
134 */
135 public function setEmptyStateMessage(mixed $message): self
136 {
137 if (empty($message)) {
138 $this->emptyStateMessage = null;
139 } else {
140 $this->emptyStateMessage = Html::wantHtml($message);
141 }
142
143 return $this;
144 }
145
146 /**
147 * Get renderer for the given item
148 *
149 * @param Item $item
150 *
151 * @return ItemRenderer<Item>
152 */
153 protected function getItemRenderer($item): ItemRenderer
154 {
155 if (is_callable($this->itemRenderer)) {
156 return call_user_func($this->itemRenderer, $item);
157 } elseif (is_string($this->itemRenderer)) {
158 $this->itemRenderer = new $this->itemRenderer();
159 }
160
161 return $this->itemRenderer;
162 }
163
164 /**
165 * Create a list item for the given data
166 *
167 * @param Result $data
168 *
169 * @return ListItem<Item>
170 */
171 protected function createListItem(object $data)
172 {
173 return new ListItem($data, $this);
174 }
175
176 protected function assemble(): void
177 {
178 /** @var Result $data */
179 foreach ($this->data as $data) {
180 $item = $this->createListItem($data);
181 $this->emit(self::BEFORE_ITEM_ADD, [$item, $data]);
182 $this->addHtml($item);
183 $this->emit(self::ON_ITEM_ADD, [$item, $data]);
184 }
185
186 if ($this->isEmpty()) {
187 $this->setTag('div');
188 $this->addHtml(new EmptyState($this->getEmptyStateMessage()));
189 }
190 }
191 }