1	<?php
2
3	declare(strict_types=1);
4
5	namespace Drupal\display_builder\Island;
6
7	use Drupal\Component\Plugin\ConfigurableInterface;
8	use Drupal\Component\Plugin\PluginInspectionInterface;
9	use Drupal\Core\Form\FormStateInterface;
10	use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
11	use Drupal\display_builder\InstanceInterface;
12
13	/**
14	* Interface for island plugins.
15	*/
16	interface IslandInterface extends ConfigurableInterface, ContainerFactoryPluginInterface, IslandEventSubscriberInterface, PluginInspectionInterface {
17
18	/**
19	* Define keyboard shortcuts.
20	*
21	* @return array
22	*   An associative array of key => description.
23	*/
24	public static function keyboardShortcuts(): array;
25
26	/**
27	* Build renderable from state data.
28	*
29	* @param \Drupal\display_builder\InstanceInterface $builder
30	*   Display builder instance.
31	* @param array $data
32	*   (Optional) UI Patterns 2 sources data. It can be the full data state
33	*   (so, the same as $builder->getCurrentState()) or just some specific data
34	*   of a single source of a sub-tree of sources.
35	* @param array $options
36	*   (Optional) Additional data to alter the island rendering.
37	*
38	* @return array
39	*   A renderable array.
40	*/
41	public function build(InstanceInterface $builder, array $data = [], array $options = []): array;
42
43	/**
44	* Alter form element after its built.
45	*
46	* @param array $element
47	*   An associative array containing the structure of the form element.
48	* @param \Drupal\Core\Form\FormStateInterface $form_state
49	*   The current state of the form.
50	*
51	* @return array
52	*   The altered form element.
53	*/
54	public function afterBuild(array $element, FormStateInterface $form_state): array;
55
56	/**
57	* Returns the translated plugin label.
58	*
59	* @return string
60	*   The island label.
61	*/
62	public function label(): string;
63
64	/**
65	* Get island type value.
66	*
67	* @return string
68	*   The type value attribute value.
69	*/
70	public function getTypeId(): string;
71
72	/**
73	* Get HTML ID.
74	*
75	* This ID is used to update an interactive island.
76	*
77	* @param string $builder_id
78	*   Builder ID.
79	*
80	* @return string
81	*   The HTML ID attribute value.
82	*/
83	public function getHtmlId(string $builder_id): string;
84
85	/**
86	* Returns the icon if any.
87	*
88	* @return string
89	*   The icon string.
90	*/
91	public function getIcon(): ?string;
92
93	/**
94	* Determine if the Island plugin is applicable.
95	*
96	* @return bool
97	*   TRUE if plugin is applicable, FALSE otherwise.
98	*/
99	public function isApplicable(): bool;
100
101	/**
102	* Alter the renderable of the display builder instance.
103	*
104	* @param \Drupal\display_builder\InstanceInterface $instance
105	*   Display builder instance.
106	* @param array $build
107	*   The renderable to alter.
108	*
109	* @return array
110	*   The altered renderable.
111	*/
112	public function alterRenderable(InstanceInterface $instance, array $build): array;
113
114	/**
115	* Whether this island's rebuild may be deferred while it is off screen.
116	*
117	* Deferrable islands are skipped by the event fan-out when the client
118	* reports them as hidden, and fetched again via reload() once the user
119	* brings them back into view.
120	*
121	* An island must decline if its pane content is not produced by its own
122	* build() - reload() would then swap in something incomplete. Panels that
123	* are permanently on screen have nothing to gain and also decline.
124	*
125	* @return bool
126	*   TRUE if this island can be deferred and later reloaded on its own.
127	*
128	* @see self::reload()
129	* @see \Drupal\display_builder\Event\DisplayBuilderEventsSubscriber::shouldDefer()
130	*/
131	public function isDeferrable(): bool;
132
133	/**
134	* Rebuild this island from the instance's current state, out of band.
135	*
136	* Produces the same out-of-band swap the event fan-out would have produced,
137	* but on demand and for this island alone. Used to refresh a panel which was
138	* deferred (skipped) while it was hidden, once it becomes visible again.
139	*
140	* @param \Drupal\display_builder\InstanceInterface $instance
141	*   Display builder instance.
142	*
143	* @return array
144	*   A renderable array carrying the out-of-band swap.
145	*
146	* @see \Drupal\display_builder\Controller\ApiController::reloadIsland()
147	* @see \Drupal\display_builder\Event\DisplayBuilderEventsSubscriber::shouldDefer()
148	*/
149	public function reload(InstanceInterface $instance): array;
150
151	}