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