| 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 |
} |