1	<?php
2
3	declare(strict_types=1);
4
5	namespace Drupal\display_builder;
6
7	use Drupal\Component\Plugin\PluginInspectionInterface;
8	use Drupal\Core\Access\AccessResultInterface;
9	use Drupal\Core\Plugin\ContainerFactoryPluginInterface;
10	use Drupal\Core\Plugin\Context\ContextProviderInterface;
11	use Drupal\Core\Session\AccountInterface;
12	use Drupal\Core\StringTranslation\TranslatableMarkup;
13	use Drupal\Core\Url;
14	use Drupal\display_builder\Entity\ProfileInterface;
15
16	/**
17	* Interface for entities or plugins natively embedding a display builder.
18	*/
19	interface DisplayBuildableInterface extends ContainerFactoryPluginInterface, ContextProviderInterface, PluginInspectionInterface {
20
21	// Storage property for of the override field.
22	// This will we used in some schema.yml, careful if you change it.
23	public const OVERRIDE_FIELD_PROPERTY = 'override_field';
24
25	// Storage property for the overridden profile config entity ID.
26	// This will we used in some schema.yml, careful if you change it.
27	public const OVERRIDE_PROFILE_PROPERTY = 'override_profile';
28
29	// Storage property for the profile config entity ID.
30	// This will we used in some schema.yml, careful if you change it.
31	public const PROFILE_PROPERTY = 'profile';
32
33	// Storage property for the nestable list of UI Patterns 2 sources.
34	// This will we used in some schema.yml, careful if you change it.
35	public const SOURCES_PROPERTY = 'sources';
36
37	/**
38	* Returns the translated plugin label.
39	*/
40	public function label(): string;
41
42	/**
43	* Build form for integration with Display Builder.
44	*
45	* @param bool $mandatory
46	*   (Optional) Is it mandatory to use Display Builder? (for example, in
47	*   Page Layouts or in Entity View display Overrides). If not mandatory,
48	*   the Display Builder is activated only if a Display Builder config entity
49	*   is selected.
50	* @param \Drupal\Core\StringTranslation\TranslatableMarkup|null $title
51	*   (Optional) The Select title, default to 'Profile'.
52	* @param bool $link
53	*   (Optional) Display link to build the display.
54	*
55	* @return array
56	*   A form renderable array.
57	*/
58	public function buildInstanceForm(bool $mandatory = TRUE, ?TranslatableMarkup $title = NULL, bool $link = TRUE): array;
59
60	/**
61	* Checks access for an instance for a user account.
62	*
63	* @param string $instance_id
64	*   Instance entity ID.
65	* @param \Drupal\Core\Session\AccountInterface $account
66	*   The user session for which to check access.
67	*
68	* @return \Drupal\Core\Access\AccessResultInterface
69	*   The access result.
70	*
71	* @see \Drupal\display_builder\InstanceAccessControlHandler
72	*/
73	public static function checkAccess(string $instance_id, AccountInterface $account): AccessResultInterface;
74
75	/**
76	* Check if instance ID can be used with the interface implementation.
77	*
78	* @param string $instance_id
79	*   Instance entity ID.
80	*
81	* @return array|null
82	*   The parts we checked, extracted from the instance ID string.
83	*/
84	public static function checkInstanceId(string $instance_id): ?array;
85
86	/**
87	* Collect instances related to this buildable.
88	*
89	* @return array<string, \Drupal\display_builder\InstanceInterface>
90	*   A associative array of Instance entities.
91	*/
92	public static function collectInstances(): array;
93
94	/**
95	* Get profiles allowed for the user.
96	*
97	* @param \Drupal\Core\Session\AccountInterface|null $account
98	*   Optional user account. Current user if empty.
99	*
100	* @return array
101	*   The list of allowed profiles.
102	*/
103	public function getAllowedProfiles(?AccountInterface $account = NULL): array;
104
105	/**
106	* Get display builder instance URL.
107	*
108	* @return \Drupal\Core\Url
109	*   A Drupal URL object.
110	*/
111	public function getBuilderUrl(): Url;
112
113	/**
114	* Get the display url that use this instance.
115	*
116	* @param string $instance_id
117	*   Instance entity ID.
118	*
119	* @return \Drupal\Core\Url
120	*   A Drupal URL object.
121	*/
122	public static function getDisplayUrlFromInstanceId(string $instance_id): Url;
123
124	/**
125	* Gets the Display Builder instance.
126	*
127	* @return \Drupal\display_builder\InstanceInterface|null
128	*   A display builder instance.
129	*/
130	public function getInstance(): ?InstanceInterface;
131
132	/**
133	* Get instance ID.
134	*
135	* Will be used as HTML id & class attributes and Javascript variables names
136	* (because of HTMX) so must follow the intersection between:
137	* - https://developer.mozilla.org/en-US/docs/Web/CSS/ident
138	* - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#identifiers
139	* Characters can be any of the following:
140	* - any ASCII character in the ranges A-Z and a-z
141	* - any decimal digit (0 to 9), except for the first character
142	* - an underscore (_)
143	*
144	* @return string|null
145	*   The instance ID for the display builder, or NULL if the entity is new.
146	*/
147	public function getInstanceId(): ?string;
148
149	/**
150	* Get the instance prefix.
151	*
152	* @return string
153	*   The instance prefix.
154	*/
155	public static function getPrefix(): string;
156
157	/**
158	* Get display builder profile config entity.
159	*
160	* If NULL, the Display Builder is not activated for this entity.
161	*
162	* @return ?ProfileInterface
163	*   The display builder profile config entity.
164	*/
165	public function getProfile(): ?ProfileInterface;
166
167	/**
168	* Get sources tree.
169	*
170	* @return array
171	*   A list of nestable sources.
172	*/
173	public function getSources(): array;
174
175	/**
176	* Get display builder instance URL from an instance ID.
177	*
178	* @param string $instance_id
179	*   Instance entity ID.
180	*
181	* @return \Drupal\Core\Url
182	*   A Drupal URL object.
183	*/
184	public static function getUrlFromInstanceId(string $instance_id): Url;
185
186	/**
187	* Init instance if missing.
188	*
189	* Init an display_builder_instance entity if:
190	* - ::getProfile() is not null
191	* - the instance is not already existing in storage.
192	*/
193	public function initInstanceIfMissing(): void;
194
195	/**
196	* Is the user allowed to use display builder.
197	*
198	* @param \Drupal\Core\Session\AccountInterface|null $account
199	*   Optional user account. Current user if empty.
200	*
201	* @return bool
202	*   Allowed or not.
203	*/
204	public function isAllowed(?AccountInterface $account = NULL): bool;
205
206	/**
207	* Save sources tree retrieved from the Instance entity to config or content.
208	*/
209	public function saveSources(): void;
210
211	}