1 /*
2 * $Source$
3 * $Revision$
4 *
5 * Copyright (C) 2006 Tim Pizey
6 *
7 * Part of Melati (http://melati.org), a framework for the rapid
8 * development of clean, maintainable web applications.
9 *
10 * Melati is free software; Permission is granted to copy, distribute
11 * and/or modify this software under the terms either:
12 *
13 * a) the GNU General Public License as published by the Free Software
14 * Foundation; either version 2 of the License, or (at your option)
15 * any later version,
16 *
17 * or
18 *
19 * b) any version of the Melati Software License, as published
20 * at http://melati.org
21 *
22 * You should have received a copy of the GNU General Public License and
23 * the Melati Software License along with this program;
24 * if not, write to the Free Software Foundation, Inc.,
25 * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
26 * GNU General Public License and visit http://melati.org to obtain the
27 * Melati Software License.
28 *
29 * Feel free to contact the Developers of Melati (http://melati.org),
30 * if you would like to work out a different arrangement than the options
31 * outlined here. It is our intention to allow Melati to be used by as
32 * wide an audience as possible.
33 *
34 * This program is distributed in the hope that it will be useful,
35 * but WITHOUT ANY WARRANTY; without even the implied warranty of
36 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
37 * GNU General Public License for more details.
38 *
39 * Contact details for copyright holder:
40 *
41 * Tim Pizey <Timp At paneris.org>
42 * http://paneris.org/~timp
43 */
44 package org.melati.template;
45
46 import org.melati.poem.Field;
47 import org.melati.poem.Persistent;
48
49 /**
50 * MarkupLanguage provides a variety of methods for rendering objects in a
51 * template.
52 *
53 * Each object to be rendered has 3 methods:
54 * 1 - String rendered(Object o) - this will render the object to a String
55 * 2 - void render(Object o) - renders the object to melati.getWriter()
56 * 3 - void render(Object o, MelatiWriter w) - render the object to w.
57 *
58 * When this class was written it was thought that for maximum
59 * efficiency one should render the object direct to the output stream using
60 * method (2) above.
61 * However now all but (1) is deprecated.
62 */
63 public interface MarkupLanguage {
64
65 /**
66 * The AttributeMarkupLanguage associated with this MarkupLanguage.
67 * See org/melati/admin/EditHeader.wm
68 * See org/melati/admin/PrimarySelect.wm
69 * @return the AttributeMarkupLanguage to use for rendering attributes.
70 */
71 AttributeMarkupLanguage getAttr();
72
73 /**
74 * Get the name of this Markup Language.
75 *
76 * @return name - the name associated with this markup language.
77 * This is used to determine where to load
78 * templates from ie 'html' templates are
79 * found in the 'html' directory.
80 */
81 String getName();
82
83 /**
84 * Render an Object in a MarkupLanguage specific way, returning a String.
85 *
86 * @return - the object rendered as a String in a MarkupLanguage specific way.
87 * @param o - the Object to be rendered
88 */
89 String rendered(Object o);
90
91 /**
92 * @param s markup fragment to render
93 * @return fragment rendered with markup unchanged
94 */
95 String renderedMarkup(String s);
96
97
98 /**
99 * Render a String in a MarkupLanguage specific way, limiting it's length.
100 *
101 * @param s - the string to be rendered
102 * @param limit - the lenght to trim the string to
103 * @return - the String having been rendered in a MarkupLanguage specific way.
104 */
105 String rendered(String s, int limit);
106
107 /**
108 * Render a Field Object in a MarkupLanguage specific way,
109 * returning a String.
110 * Defaults to a limit of 10,000,000.
111 *
112 * @see org.melati.poem.DatePoemType#stringOfCooked
113 * (java.lang.Object,org.melati.poem.PoemLocale, int)
114 *
115 * @param field - the Field to be rendered
116 * @param style - a style to format this Field.
117 * @return - the Field rendered as a String in a MarkupLanguage specific way.
118 * @throws TemplateEngineException - if there is a problem with the
119 * ServletTemplateEngine
120 */
121 String rendered(Field<?> field, int style)
122 throws TemplateEngineException;
123
124 /**
125 * Render a Field Object in a MarkupLanguage specific way,
126 * returning a String.
127 *
128 * see org.melati.poem.DatePoemType#_stringOfCooked
129 * (java.lang.Object,org.melati.poem.PoemLocale, int)
130 *
131 * @param field - the Field to be rendered
132 * @param style - a DateFormat style to format this Field.
133 * @param limit - the length to trim the rendered string to
134 * @return - the Field rendered as a String in a MarkupLanguage specific way.
135 * @throws TemplateEngineException - if there is a problem with the
136 * ServletTemplateEngine
137 */
138 String rendered(Field<?> field, int style, int limit)
139 throws TemplateEngineException;
140
141 /**
142 * Render a Date Field Object in a MarkupLanguage specific way,
143 * returning a START Date format String.
144 *
145 * @see org.melati.poem.DatePoemType#stringOfCooked
146 * (java.lang.Object,org.melati.poem.PoemLocale, int)
147 *
148 * @param field - the Field to be rendered
149 * @return - the Field rendered as a String in a MarkupLanguage specific way.
150 */
151 String renderedStart(Field<?> field);
152
153
154
155 //
156 // =========
157 // Widgets
158 // =========
159 //
160 /**
161 * Get an input widget for this Field.
162 *
163 * @param field The Field
164 * @return The default input widget for the Field type
165 * @throws NotFoundException if template not found
166 */
167 String input(Field<?> field) throws TemplateEngineException, NotFoundException;
168
169 /**
170 * Get an input widget for this Field defined by name.
171 *
172 * @param field The Field
173 * @param templetName the templet to use instead of the default
174 * @return The specified input widget for the Field type
175 * @throws NotFoundException if template not found
176 */
177 String inputAs(Field<?> field, String templetName)
178 throws TemplateEngineException, NotFoundException;
179
180 /**
181 * Get an input widget for this Field specifying the null value.
182 *
183 * @param field The Field
184 * @param nullValue the value to use for null for example in a dropdown.
185 * @return The default input widget for the Field type with a specified null value
186 * @throws NotFoundException if template not found
187 */
188 String searchInput(Field<?> field, String nullValue)
189 throws TemplateEngineException, NotFoundException;
190
191
192 /**
193 * Escape a String.
194 *
195 * @param s the String to escape
196 * @return the escaped String
197 */
198 String escaped(String s);
199
200 /**
201 * Get the DisplayString of a <code>Persistent</code> and
202 * escape that using the current locale and a MEDIUM DateFormat.
203 *
204 * See org/melati/admin/SelectionWindowSelection.wm
205 * See org/melati/admin/Update.wm
206 * @param o
207 * @return the escaped DisplayString
208 */
209 String escaped(Persistent o);
210
211 /**
212 * Encode a String as a UTF-8 URL.
213 *
214 * @param s the String to encode
215 * @return the encoded String
216 */
217 String encoded(String s);
218
219 /**
220 * Decode a UTF-8 URL encoded string.
221 * @param s
222 * @return the decoded String
223 */
224 String decoded(String s);
225 }
226
227