1 /*
2 * $Source: /usr/cvsroot/melati/melati/src/main/java/org/melati/template/MarkupLanguage.java,v $
3 * $Revision: 1.47 $
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 java.io.IOException;
47
48 import org.melati.poem.Field;
49 import org.melati.poem.Persistent;
50
51 /**
52 * MarkupLanguage provides a variety of methods for rendering objects in a
53 * template.
54 *
55 * Each object to be rendered has 3 methods:
56 * 1 - String rendered(Object o) - this will render the object to a String
57 * 2 - void render(Object o) - renders the object to melati.getWriter()
58 * 3 - void render(Object o, MelatiWriter w) - render the object to w.
59 *
60 * When this class was written it was thought that for maximum
61 * efficiency one should render the object direct to the output stream using
62 * method (2) above.
63 * However now all but (1) is deprecated.
64 */
65 public interface MarkupLanguage {
66
67 /**
68 * The AttributeMarkupLanguage associated with this MarkupLanguage.
69 * See org/melati/admin/EditHeader.wm
70 * See org/melati/admin/PrimarySelect.wm
71 * @return the AttributeMarkupLanguage to use for rendering attributes.
72 */
73 AttributeMarkupLanguage getAttr();
74
75 /**
76 * Get the name of this Markup Language.
77 *
78 * @return name - the name associated with this markup language.
79 * This is used to determine where to load
80 * templates from ie 'html' templates are
81 * found in the 'html' directory.
82 */
83 String getName();
84
85 /**
86 * Render an Object in a MarkupLanguage specific way, returning a String.
87 *
88 * @return - the object rendered as a String in a MarkupLanguage specific way.
89 * @param o - the Object to be rendered
90 * @throws IOException - if there is a problem during rendering
91 */
92 String rendered(Object o) throws IOException;
93
94 /**
95 * @param s markup fragment to render
96 * @return fragment rendered with markup unchanged
97 * @throws IOException if there is a problem during rendering
98 */
99 String renderedMarkup(String s) throws IOException;
100
101
102 /**
103 * Render a String in a MarkupLanguage specific way, limiting it's length.
104 *
105 * @param s - the string to be rendered
106 * @param limit - the lenght to trim the string to
107 * @throws IOException - if there is a problem during rendering
108 * @return - the String having been rendered in a MarkupLanguage specific way.
109 */
110 String rendered(String s, int limit) throws IOException;
111
112 /**
113 * Render a Field Object in a MarkupLanguage specific way,
114 * returning a String.
115 * Defaults to a limit of 10,000,000.
116 *
117 * @see org.melati.poem.DatePoemType#stringOfCooked
118 * (java.lang.Object,org.melati.poem.PoemLocale, int)
119 *
120 * @param field - the Field to be rendered
121 * @param style - a style to format this Field.
122 * @return - the Field rendered as a String in a MarkupLanguage specific way.
123 * @throws IOException - if there is a problem during rendering
124 * @throws TemplateEngineException - if there is a problem with the
125 * ServletTemplateEngine
126 */
127 String rendered(Field field, int style)
128 throws TemplateEngineException, IOException;
129
130 /**
131 * Render a Field Object in a MarkupLanguage specific way,
132 * returning a String.
133 *
134 * see org.melati.poem.DatePoemType#_stringOfCooked
135 * (java.lang.Object,org.melati.poem.PoemLocale, int)
136 *
137 * @param field - the Field to be rendered
138 * @param style - a DateFormat style to format this Field.
139 * @param limit - the length to trim the rendered string to
140 * @return - the Field rendered as a String in a MarkupLanguage specific way.
141 * @throws IOException - if there is a problem during rendering
142 * @throws TemplateEngineException - if there is a problem with the
143 * ServletTemplateEngine
144 */
145 String rendered(Field field, int style, int limit)
146 throws TemplateEngineException, IOException;
147
148 /**
149 * Render a Date Field Object in a MarkupLanguage specific way,
150 * returning a START Date format String.
151 *
152 * @see org.melati.poem.DatePoemType#stringOfCooked
153 * (java.lang.Object,org.melati.poem.PoemLocale, int)
154 *
155 * @param field - the Field to be rendered
156 * @return - the Field rendered as a String in a MarkupLanguage specific way.
157 * @throws IOException - if there is a problem during rendering
158 */
159 String renderedStart(Field field)
160 throws IOException;
161
162
163
164 //
165 // =========
166 // Widgets
167 // =========
168 //
169 /**
170 * Get an input widget for this Field.
171 *
172 * @param field The Field
173 * @return The default input widget for the Field type
174 * @throws NotFoundException if template not found
175 */
176 String input(Field field) throws TemplateEngineException,
177 IOException, NotFoundException;
178
179 /**
180 * Get an input widget for this Field defined by name.
181 *
182 * @param field The Field
183 * @param templetName the templet to use instead of the default
184 * @return The specified input widget for the Field type
185 * @throws NotFoundException if template not found
186 */
187 String inputAs(Field field, String templetName)
188 throws TemplateEngineException, IOException, NotFoundException;
189
190 /**
191 * Get an input widget for this Field specifying the null value.
192 *
193 * @param field The Field
194 * @param nullValue the value to use for null for example in a dropdown.
195 * @return The default input widget for the Field type with a specified null value
196 * @throws NotFoundException if template not found
197 */
198 String searchInput(Field field, String nullValue)
199 throws TemplateEngineException, IOException, NotFoundException;
200
201
202 /**
203 * Escape a String.
204 *
205 * @param s the String to escape
206 * @return the escaped String
207 */
208 String escaped(String s);
209
210 /**
211 * Get the DisplayString of a <code>Persistent</code> and
212 * escape that using the current locale and a MEDIUM DateFormat.
213 *
214 * See org/melati/admin/SelectionWindowSelection.wm
215 * See org/melati/admin/Update.wm
216 * @param o
217 * @return the escaped DisplayString
218 */
219 String escaped(Persistent o);
220
221 /**
222 * Encode a String as a UTF-8 URL.
223 *
224 * @param s the String to encode
225 * @return the encoded String
226 */
227 String encoded(String s);
228
229 /**
230 * Decode a UTF-8 URL encoded string.
231 * @param s
232 * @return the decoded String
233 */
234 String decoded(String s);
235 }
236
237