1	<?php declare(strict_types=1);
2
3	namespace Computator\FrameworkUtils\PHPTemplate\UserApi;
4
5	/**
6	* Template engine methods available in templates.
7	*/
8	interface TemplateClient {
9	/**
10	* Output a block defined in a child template.
11	*
12	* This method is used to output a block that a child template has previously
13	* defined using `self::block()`. The return value of this method can be
14	* used to decide whether to render any fallback content.
15	*
16	* This method is only valid in a template that has been set as a parent
17	* from a child via `self::inherit()`.
18	*
19	* # Examples
20	*
21	* ## Normal
22	*
23	* ```php
24	* <? self::block('block_name'): ?>
25	* ```
26	*
27	* ## Fallback
28	*
29	* ```php
30	* <? if(!self::block('block_name')): ?>
31	*     Fallback content
32	* <? endif ?>
33	* ```
34	*
35	* @return bool whether or not the block was found and output
36	*/
37	public function block(string $block_name): bool;
38
39	/**
40	* Start defining a template block.
41	*
42	* Blocks defined with this method can be output in the parent template
43	* using `self::block()`.
44	*
45	* This method is only valid in a child template that has set a
46	* parent with `self::inherit()`.
47	*
48	* # Example
49	*
50	* ```php
51	* <? self::define('block_name') ?>
52	*     Block content
53	* <? self::define_end() ?>
54	* ```
55	*/
56	public function define(string $block_name): void;
57
58	/**
59	* End the current template block being defined.
60	*
61	* This method is used to mark the end of a block started with `self::define()`.
62	*
63	* This method is only valid in a child template that has set a
64	* parent with `self::inherit()`.
65	*
66	* # Example
67	*
68	* ```php
69	* <? self::define('block_name') ?>
70	*     Block content
71	* <? self::define_end() ?>
72	* ```
73	*/
74	public function define_end(): void;
75
76	/**
77	* Set a parent template to render this template with.
78	*
79	* This method can not be called more than once per template.
80	*
81	* # Example
82	*
83	* ## `child.php`
84	*
85	* ```php
86	* <? self::inherit('parent.php') ?>
87	*
88	* <? self::define('block_one') ?>
89	*     Block content
90	* <? self::define_end() ?>
91	* ```
92	*
93	* ## `parent.php`
94	*
95	* ```php
96	* <div class="content">
97	*     <? self::block('block_one') ?>
98	* </div>
99	* ```
100	*/
101	public function inherit(string $parent_template): void;
102
103	/**
104	* Create an insertion point for future content.
105	*
106	* This method is used to create an insertion point that can then be appended
107	* to from elsewhere in the rendering process. The insertion point is stored
108	* under the provided name which must be unique across all referenced templates.
109	*
110	* Note that content can be appended to an insertion point before it is created.
111	*
112	* # Example
113	*
114	* ```php
115	* <? self::insert_set('insert_name'): ?>
116	* ```
117	*/
118	public function insert_set(string $insert_name): void;
119
120	/**
121	* Start appending to an insertion point.
122	*
123	* Content blocks defined with this method will be appended to an insertion
124	* point created elsewhere using `self::insert_set()`.
125	*
126	* # Example
127	*
128	* ```php
129	* <? self::insert('insert_name'): ?>
130	*     Content to be appended
131	* <? self::insert_end() ?>
132	* ```
133	*/
134	public function insert(string $insert_name): void;
135
136	/**
137	* Stop appending to the current insertion point.
138	*
139	* This method is used to mark the end of a content block defined with
140	* `self::insert()` that will be appended to the selected insertion point.
141	*
142	* # Example
143	*
144	* ```php
145	* <? self::insert('insert_name'): ?>
146	*     Content to be appended
147	* <? self::insert_end() ?>
148	* ```
149	*/
150	public function insert_end(): void;
151
152	/**
153	* Output non-block content from a child template.
154	*
155	* This method is used to output all content displayed in a child
156	* template outside of defined blocks.
157	*
158	* This method is only valid in a template that has been set as a parent
159	* from a child via `self::inherit()`.
160	*
161	* # Example
162	*
163	* ## `child.php`
164	*
165	* ```php
166	* <? self::inherit('parent.php') ?>
167	*
168	* <p>Content outside block</p>
169	* ```
170	*
171	* ## `parent.php`
172	*
173	* ```php
174	* <div class="content">
175	*     <? self::primary() ?>
176	* </div>
177	* ```
178	*/
179	public function primary(): void;
180
181	/**
182	* Retrieve a reference to another template.
183	*
184	* This method is used to load another template to render. This returns a
185	* reference to the template rather than immediately rendering it, so the
186	* template can be used immediately or saved in a variable for later use.
187	*
188	* This method returns a reference to the template as an object that
189	* implements [UserApi\ResolvedTemplateClient](ResolvedTemplateClient.php).
190	*
191	* # Example
192	*
193	* ## `main.php`
194	*
195	* ```php
196	* <? self::tpl('child.php')() ?>
197	* ```
198	*
199	* ## `child.php`
200	*
201	* ```php
202	* <p>Child content</p>
203	* ```
204	*
205	* @return ResolvedTemplateClient Template reference as [UserApi\ResolvedTemplateClient](ResolvedTemplateClient.php)
206	*/
207	public function tpl(string $template): ResolvedTemplateClient;
208	}