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\Session\AccountInterface;
9	use Drupal\Core\Url;
10
11	/**
12	* Interface for entities or plugins natively embedding a display builder.
13	*/
14	interface DisplayBuildableInterface {
15
16	/**
17	* Get the instance prefix.
18	*
19	* @return string
20	*   The instance prefix.
21	*/
22	public static function getPrefix(): string;
23
24	/**
25	* Get the context requirement.
26	*
27	* @return string
28	*   The context requirement.
29	*/
30	public static function getContextRequirement(): string;
31
32	/**
33	* Check if instance ID can be used with the interface implementation.
34	*
35	* @param string $instance_id
36	*   Instance entity ID.
37	*
38	* @return array
39	*   The parts we checked, extracted from the instance ID string.
40	*/
41	public static function checkInstanceId(string $instance_id): ?array;
42
43	/**
44	* Get display builder instance URL.
45	*
46	* @return \Drupal\Core\Url
47	*   A Drupal URL object.
48	*/
49	public function getBuilderUrl(): Url;
50
51	/**
52	* Get display builder instance URL from an instance ID.
53	*
54	* @param string $instance_id
55	*   Instance entity ID.
56	*
57	* @return \Drupal\Core\Url
58	*   A Drupal URL object.
59	*/
60	public static function getUrlFromInstanceId(string $instance_id): Url;
61
62	/**
63	* Get the display url that use this instance.
64	*
65	* @param string $instance_id
66	*   Instance entity ID.
67	*
68	* @return \Drupal\Core\Url
69	*   A Drupal URL object.
70	*/
71	public static function getDisplayUrlFromInstanceId(string $instance_id): Url;
72
73	/**
74	* Get display builder profile config entity.
75	*
76	* If NULL, the Display Builder is not activated for this entity.
77	*
78	* @return ?ProfileInterface
79	*   The display builder profile config entity.
80	*/
81	public function getProfile(): ?ProfileInterface;
82
83	/**
84	* Get instance ID.
85	*
86	* Will be used as HTML id & class attributes and Javascript variables names
87	* (because of HTMX) so must follow the intersection between:
88	* - https://developer.mozilla.org/en-US/docs/Web/CSS/ident
89	* - https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Lexical_grammar#identifiers
90	* Characters can be any of the following:
91	* - any ASCII character in the ranges A-Z and a-z
92	* - any decimal digit (0 to 9), except for the first character
93	* - an underscore (_)
94	*
95	* @return string|null
96	*   Instance entity ID.
97	*/
98	public function getInstanceId(): ?string;
99
100	/**
101	* Checks access.
102	*
103	* @param string $instance_id
104	*   Instance entity ID.
105	* @param \Drupal\Core\Session\AccountInterface $account
106	*   The user session for which to check access.
107	*
108	* @return \Drupal\Core\Access\AccessResultInterface
109	*   The access result.
110	*
111	* @see \Drupal\display_builder\InstanceAccessControlHandler
112	*/
113	public static function checkAccess(string $instance_id, AccountInterface $account): AccessResultInterface;
114
115	/**
116	* Init instance if missing.
117	*
118	* Init an display_builder_instance entity if:
119	* - ::getProfile() is not null
120	* - the instance is not already existing in storage.
121	*/
122	public function initInstanceIfMissing(): void;
123
124	/**
125	* Initialize sources for this implementation.
126	*
127	* @return array
128	*   The data.
129	*/
130	public function getInitialSources(): array;
131
132	/**
133	* Initialize contexts for this implementation.
134	*
135	* @return array<\Drupal\Core\Plugin\Context\ContextInterface>
136	*   The contexts.
137	*/
138	public function getInitialContext(): array;
139
140	/**
141	* Get sources tree.
142	*
143	* @return array
144	*   A list of nestable sources.
145	*/
146	public function getSources(): array;
147
148	/**
149	* Save sources tree retrieved from the Instance entity to config or content.
150	*
151	* Triggered by a DisplayBuilderEvents::ON_SAVE event.
152	*/
153	public function saveSources(): void;
154
155	}