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