##### Coverage Report - org.melati.template.MarkupLanguage

Classes in this File | Line Coverage | Branch Coverage | Complexity
MarkupLanguage |
N/A | N/A
N/A | N/A
| 1.0;1

1 |  |
     /*
2 |  |
      * $Source: /usr/cvsroot/melati/melati/src/site/resources/withWebmacro/org.melati.template.MarkupLanguage.html,v $
3 |  |
      * $Revision: 1.1 $
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 |  |