1: <?php
2:
3: namespace Alpha\View\Renderer;
4:
5: /**
6: * Defines the renderer interface, which allows us to have various implementations (HTML,
7: * JSON, XML etc.) behind one unified interface. Use the
8: * RendererProviderFactory::getInstance() method to get instances of this.
9: *
10: * @since 1.2
11: *
12: * @author John Collins <dev@alphaframework.org>
13: * @license http://www.opensource.org/licenses/bsd-license.php The BSD License
14: * @copyright Copyright (c) 2015, John Collins (founder of Alpha Framework).
15: * All rights reserved.
16: *
17: * <pre>
18: * Redistribution and use in source and binary forms, with or
19: * without modification, are permitted provided that the
20: * following conditions are met:
21: *
22: * * Redistributions of source code must retain the above
23: * copyright notice, this list of conditions and the
24: * following disclaimer.
25: * * Redistributions in binary form must reproduce the above
26: * copyright notice, this list of conditions and the
27: * following disclaimer in the documentation and/or other
28: * materials provided with the distribution.
29: * * Neither the name of the Alpha Framework nor the names
30: * of its contributors may be used to endorse or promote
31: * products derived from this software without specific
32: * prior written permission.
33: *
34: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
35: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
36: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
37: * MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
38: * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
39: * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
40: * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
41: * NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
42: * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
43: * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
44: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
45: * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
46: * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
47: * </pre>
48: */
49: interface RendererProviderInterface
50: {
51: /**
52: * Provide the BO that we are going render.
53: *
54: * @param Alpha\Model\ActiveRecord $BO
55: *
56: * @since 1.2
57: */
58: public function setBO($BO);
59:
60: /**
61: * Renders the create view for the BO using the selected renderer.
62: *
63: * @param array $fields Hash array of fields to pass to the template.
64: *
65: * @return string
66: *
67: * @since 1.2
68: */
69: public function createView($fields = array());
70:
71: /**
72: * Renders the edit view for the BO using the selected renderer.
73: *
74: * @param array $fields Hash array of fields to pass to the template.
75: *
76: * @return string
77: *
78: * @since 1.2
79: */
80: public function editView($fields = array());
81:
82: /**
83: * Renders the list view for the BO using the selected renderer.
84: *
85: * @param array $fields Hash array of fields to pass to the template.
86: *
87: * @return string
88: *
89: * @since 1.2
90: */
91: public function listView($fields = array());
92:
93: /**
94: * Renders the detailed read-only view for the BO using the selected renderer.
95: *
96: * @param array $fields Hash array of fields to pass to the template.
97: *
98: * @return string
99: *
100: * @since 1.2
101: */
102: public function detailedView($fields = array());
103:
104: /**
105: * Renders the admin view for the BO using the selected renderer.
106: *
107: * @param array $fields Hash array of fields to pass to the template.
108: *
109: * @return string
110: *
111: * @since 1.2
112: */
113: public function adminView($fields = array());
114:
115: /**
116: * Renders the header content using the given renderer.
117: *
118: * @param Alpha\Controller\Controller $controller
119: *
120: * @return string
121: *
122: * @throws Alpha\Exception\IllegalArguementException
123: *
124: * @since 1.2
125: */
126: public static function displayPageHead($controller);
127:
128: /**
129: * Renders the footer content using the given renderer.
130: *
131: * @param Alpha\Controller\Controller $controller
132: *
133: * @return string
134: *
135: * @since 1.2
136: */
137: public static function displayPageFoot($controller);
138:
139: /**
140: * Renders an update (e.g. successful save) message.
141: *
142: * @param string $message
143: *
144: * @return string
145: *
146: * @since 1.2
147: */
148: public static function displayUpdateMessage($message);
149:
150: /**
151: * Renders an error (e.g. save failed) message.
152: *
153: * @param string $message
154: *
155: * @return string
156: *
157: * @since 1.2
158: */
159: public static function displayErrorMessage($message);
160:
161: /**
162: * Renders an error page with the supplied HTTP error code and a message.
163: *
164: * @param string $code
165: * @param string $message
166: *
167: * @return string
168: *
169: * @since 1.2
170: */
171: public static function renderErrorPage($code, $message);
172:
173: /**
174: * Method to render a hidden HTML form for posting the OID of an object to be deleted.
175: *
176: * @param string $URI The URI that the form will point to
177: *
178: * @return string
179: *
180: * @since 1.2
181: */
182: public static function renderDeleteForm($URI);
183:
184: /**
185: * Method to render a HTML form with two hidden, hashed (MD5) form fields to be used as
186: * a check to ensure that a post to the controller is being sent from the same server
187: * as hosting it.
188: *
189: * @return string
190: *
191: * @since 1.2
192: */
193: public static function renderSecurityFields();
194:
195: /**
196: * Renders an Integer field value.
197: *
198: * @param string $name The field name
199: * @param string $label The label to apply to the field
200: * @param string $mode The field mode (create/edit/view)
201: * @param string $value The field value (optional)
202: *
203: * @return string
204: *
205: * @since 1.2
206: */
207: public function renderIntegerField($name, $label, $mode, $value = '');
208:
209: /**
210: * Renders an Double field value.
211: *
212: * @param string $name The field name
213: * @param string $label The label to apply to the field
214: * @param string $mode The field mode (create/edit/view)
215: * @param string $value The field value (optional)
216: *
217: * @return string
218: *
219: * @since 1.2
220: */
221: public function renderDoubleField($name, $label, $mode, $value = '');
222:
223: /**
224: * Renders an Boolean field value.
225: *
226: * @param string $name The field name
227: * @param string $label The label to apply to the field
228: * @param string $mode The field mode (create/edit/view)
229: * @param string $value The field value (optional)
230: *
231: * @return string
232: *
233: * @since 1.2
234: */
235: public function renderBooleanField($name, $label, $mode, $value = '');
236:
237: /**
238: * Renders an Enum field value.
239: *
240: * @param string $name The field name
241: * @param string $label The label to apply to the field
242: * @param string $mode The field mode (create/edit/view)
243: * @param array $options The Enum options
244: * @param string $value The field value (optional)
245: *
246: * @return string
247: *
248: * @since 1.0
249: */
250: public function renderEnumField($name, $label, $mode, $options, $value = '');
251:
252: /**
253: * Renders an DEnum field value.
254: *
255: * @param string $name The field name
256: * @param string $label The label to apply to the field
257: * @param string $mode The field mode (create/edit/view)
258: * @param array $options The DEnum options
259: * @param string $value The field value (optional)
260: *
261: * @return string
262: *
263: * @since 1.2
264: */
265: public function renderDEnumField($name, $label, $mode, $options, $value = '');
266:
267: /**
268: * Method to render a field when type is not known.
269: *
270: * @param string $name The field name
271: * @param string $label The label to apply to the field
272: * @param string $mode The field mode (create/edit/view)
273: * @param string $value The field value (optional)
274: *
275: * @return string
276: *
277: * @since 1.2
278: */
279: public function renderDefaultField($name, $label, $mode, $value = '');
280:
281: /**
282: * Renders a Text field value.
283: *
284: * @param string $name The field name
285: * @param string $label The label to apply to the field
286: * @param string $mode The field mode (create/edit/view)
287: * @param string $value The field value (optional)
288: *
289: * @return string
290: *
291: * @since 1.0
292: */
293: public function renderTextField($name, $label, $mode, $value = '');
294:
295: /**
296: * Renders a String field value.
297: *
298: * @param string $name The field name
299: * @param string $label The label to apply to the field
300: * @param string $mode The field mode (create/edit/view)
301: * @param string $value The field value (optional)
302: *
303: * @return string
304: *
305: * @since 1.2.2
306: */
307: public function renderStringField($name, $label, $mode, $value = '');
308:
309: /**
310: * Renders a Relation field value.
311: *
312: * @param string $name The field name
313: * @param string $label The label to apply to the field
314: * @param string $mode The field mode (create/edit/view)
315: * @param string $value The field value (optional)
316: * @param bool $expanded Render the related fields in expanded format or not (optional)
317: * @param bool $buttons Render buttons for expanding/contacting the related fields (optional)
318: *
319: * @return string
320: *
321: * @since 1.2
322: */
323: public function renderRelationField($name, $label, $mode, $value = '', $expanded = false, $buttons = true);
324:
325: /**
326: * Convenience method that renders all fields for the current BO in edit/create/view mode.
327: *
328: * @param string $mode (view|edit|create)
329: * @param array $filterFields Optional list of field names to exclude from rendering.
330: * @param array $readOnlyFields Optional list of fields to render in a readonly fashion when rendering in create or edit mode.
331: *
332: * @return string
333: *
334: * @since 1.2
335: */
336: public function renderAllFields($mode, $filterFields = array(), $readOnlyFields = array());
337: }
338: