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