Coverage Report

Coverage Report - org.melati.template.MarkupLanguage

Classes in this File

 /*
  * $Source: /usr/cvsroot/melati/melati/src/main/java/org/melati/template/MarkupLanguage.java,v $
  * $Revision: 1.46 $
  *
  * Copyright (C) 2006 Tim Pizey
  *
  * Part of Melati (http://melati.org), a framework for the rapid
  * development of clean, maintainable web applications.
  *
  * Melati is free software; Permission is granted to copy, distribute
  * and/or modify this software under the terms either:
  *
  * a) the GNU General Public License as published by the Free Software
  *    Foundation; either version 2 of the License, or (at your option)
  *    any later version,
  *
  *    or
  *
  * b) any version of the Melati Software License, as published
  *    at http://melati.org
  *
  * You should have received a copy of the GNU General Public License and
  * the Melati Software License along with this program;
  * if not, write to the Free Software Foundation, Inc.,
  * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
  * GNU General Public License and visit http://melati.org to obtain the
  * Melati Software License.
  *
  * Feel free to contact the Developers of Melati (http://melati.org),
  * if you would like to work out a different arrangement than the options
  * outlined here.  It is our intention to allow Melati to be used by as
  * wide an audience as possible.
  *
  * This program is distributed in the hope that it will be useful,
  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  * GNU General Public License for more details.
  *
  * Contact details for copyright holder:
  *
  *     Tim Pizey <Timp At paneris.org>
  *     http://paneris.org/~timp
  */
 package org.melati.template;
 
 import java.io.IOException;
 
 import org.melati.poem.Field;
 import org.melati.poem.Persistent;
 
 /**
  * MarkupLanguage provides a variety of methods for rendering objects in a
  * template.  
  *
  * Each object to be rendered has 3 methods:
  * 1 - String rendered(Object o) - this will render the object to a String
  * 2 - void render(Object o) - renders the object to melati.getWriter()
  * 3 - void render(Object o, MelatiWriter w) - render the object to w.
  *
  * When this class was written it was thought that for maximum 
  * efficiency one should render the object direct to the output stream using
  * method (2) above.  
  * However now all but (1) is deprecated. 
  */
 public interface MarkupLanguage {
 
   /**
    * The AttributeMarkupLanguage associated with this MarkupLanguage.
    * See org/melati/admin/EditHeader.wm
    * See org/melati/admin/PrimarySelect.wm
    * @return the AttributeMarkupLanguage to use for rendering attributes.
    */
   AttributeMarkupLanguage getAttr();
 
   /**
    * Get the name of this Markup Language.
    *
    * @return name - the name associated with this markup language.
    *                This is used to determine where to load
    *                templates from ie 'html' templates are
    *                found in the 'html' directory.
    */
   String getName();
 
   /**
    * Render an Object in a MarkupLanguage specific way, returning a String.
    *
    * @return - the object rendered as a String in a MarkupLanguage specific way.
    * @param o - the Object to be rendered
    * @throws IOException - if there is a problem during rendering
    */
   String rendered(Object o) throws IOException;
 
 
   /**
    * Render a String in a MarkupLanguage specific way, limiting it's length.
    *
    * @param s - the string to be rendered
    * @param limit - the lenght to trim the string to
    * @throws IOException - if there is a problem during rendering
    * @return - the String having been rendered in a MarkupLanguage specific way.
    */
   String rendered(String s, int limit) throws IOException;
 
   /**
    * Render a Field Object in a MarkupLanguage specific way, 
    * returning a String.
    * Defaults to a limit of 10,000,000. 
    *
    * @see org.melati.poem.DatePoemType#stringOfCooked
    *              (java.lang.Object,org.melati.poem.PoemLocale, int)
    * 
    * @param field - the Field to be rendered
    * @param style - a style to format this Field.
    * @return - the Field rendered as a String in a MarkupLanguage specific way.
    * @throws IOException - if there is a problem during rendering
    * @throws TemplateEngineException - if there is a problem with the
    *                                   ServletTemplateEngine
    */
   String rendered(Field field, int style)
           throws TemplateEngineException, IOException;
 
   /**
    * Render a Field Object in a MarkupLanguage specific way, 
    * returning a String.
    *
    * see org.melati.poem.DatePoemType#_stringOfCooked
    *              (java.lang.Object,org.melati.poem.PoemLocale, int)
    * 
    * @param field - the Field to be rendered
    * @param style - a DateFormat style to format this Field.
    * @param limit - the length to trim the rendered string to
    * @return - the Field rendered as a String in a MarkupLanguage specific way.
    * @throws IOException - if there is a problem during rendering
    * @throws TemplateEngineException - if there is a problem with the
    *                                   ServletTemplateEngine
    */
   String rendered(Field field, int style, int limit)
           throws TemplateEngineException, IOException;
 
   /**
    * Render a Date Field Object in a MarkupLanguage specific way, 
    * returning a START Date format String.
    *
    * @see org.melati.poem.DatePoemType#stringOfCooked
    *              (java.lang.Object,org.melati.poem.PoemLocale, int)
    * 
    * @param field - the Field to be rendered
    * @return - the Field rendered as a String in a MarkupLanguage specific way.
    * @throws IOException - if there is a problem during rendering
    */
   String renderedStart(Field field)
           throws IOException;
 
   
   
   //
   // =========
   //  Widgets
   // =========
   //
   /**
    * Get an input widget for this Field.
    * 
    * @param field The Field
    * @return The default input widget for the Field type
    * @throws NotFoundException if template not found
    */
   String input(Field field) throws TemplateEngineException,
           IOException, NotFoundException;
 
   /**
    * Get an input widget for this Field defined by name.
    * 
    * @param field The Field
    * @param templetName the templet to use instead of the default
    * @return The specified input widget for the Field type
    * @throws NotFoundException if template not found
    */
   String inputAs(Field field, String templetName)
           throws TemplateEngineException, IOException, NotFoundException;
 
   /**
    * Get an input widget for this Field specifying the null value.
    * 
    * @param field The Field
    * @param nullValue the value to use for null for example in a dropdown. 
    * @return The default input widget for the Field type with a specified null value
    * @throws NotFoundException if template not found
    */
   String searchInput(Field field, String nullValue)
           throws TemplateEngineException, IOException, NotFoundException;
 
 
   /**
    * Escape a String.
    * 
    * @param s the String to escape
    * @return the escaped String
    */
   String escaped(String s);
 
   /**
    * Get the DisplayString of a <code>Persistent</code> and 
    * escape that using the current locale and a MEDIUM DateFormat.
    * 
    * See org/melati/admin/SelectionWindowSelection.wm
    * See org/melati/admin/Update.wm
    * @param o
    * @return the escaped DisplayString
    */
   String escaped(Persistent o);
 
   /**
    * Encode a String as a UTF-8 URL. 
    * 
    * @param s the String to encode
    * @return the encoded String
    */
   String encoded(String s);
   
   /**
    * Decode a UTF-8 URL encode string.
    * @param s
    * @return the decoded String
    */
   String decoded(String s);
 }
 
 

1		/*
2		* $Source: /usr/cvsroot/melati/melati/src/main/java/org/melati/template/MarkupLanguage.java,v $
3		* $Revision: 1.46 $
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		/**
96		* Render a String in a MarkupLanguage specific way, limiting it's length.
97		*
98		* @param s - the string to be rendered
99		* @param limit - the lenght to trim the string to
100		* @throws IOException - if there is a problem during rendering
101		* @return - the String having been rendered in a MarkupLanguage specific way.
102		*/
103		String rendered(String s, int limit) throws IOException;
104
105		/**
106		* Render a Field Object in a MarkupLanguage specific way,
107		* returning a String.
108		* Defaults to a limit of 10,000,000.
109		*
110		* @see org.melati.poem.DatePoemType#stringOfCooked
111		* (java.lang.Object,org.melati.poem.PoemLocale, int)
112		*
113		* @param field - the Field to be rendered
114		* @param style - a style to format this Field.
115		* @return - the Field rendered as a String in a MarkupLanguage specific way.
116		* @throws IOException - if there is a problem during rendering
117		* @throws TemplateEngineException - if there is a problem with the
118		* ServletTemplateEngine
119		*/
120		String rendered(Field field, int style)
121		throws TemplateEngineException, IOException;
122
123		/**
124		* Render a Field Object in a MarkupLanguage specific way,
125		* returning a String.
126		*
127		* see org.melati.poem.DatePoemType#_stringOfCooked
128		* (java.lang.Object,org.melati.poem.PoemLocale, int)
129		*
130		* @param field - the Field to be rendered
131		* @param style - a DateFormat style to format this Field.
132		* @param limit - the length to trim the rendered string to
133		* @return - the Field rendered as a String in a MarkupLanguage specific way.
134		* @throws IOException - if there is a problem during rendering
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, IOException;
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		* @throws IOException - if there is a problem during rendering
151		*/
152		String renderedStart(Field field)
153		throws IOException;
154
155
156
157		//
158		// =========
159		// Widgets
160		// =========
161		//
162		/**
163		* Get an input widget for this Field.
164		*
165		* @param field The Field
166		* @return The default input widget for the Field type
167		* @throws NotFoundException if template not found
168		*/
169		String input(Field field) throws TemplateEngineException,
170		IOException, NotFoundException;
171
172		/**
173		* Get an input widget for this Field defined by name.
174		*
175		* @param field The Field
176		* @param templetName the templet to use instead of the default
177		* @return The specified input widget for the Field type
178		* @throws NotFoundException if template not found
179		*/
180		String inputAs(Field field, String templetName)
181		throws TemplateEngineException, IOException, NotFoundException;
182
183		/**
184		* Get an input widget for this Field specifying the null value.
185		*
186		* @param field The Field
187		* @param nullValue the value to use for null for example in a dropdown.
188		* @return The default input widget for the Field type with a specified null value
189		* @throws NotFoundException if template not found
190		*/
191		String searchInput(Field field, String nullValue)
192		throws TemplateEngineException, IOException, NotFoundException;
193
194
195		/**
196		* Escape a String.
197		*
198		* @param s the String to escape
199		* @return the escaped String
200		*/
201		String escaped(String s);
202
203		/**
204		* Get the DisplayString of a <code>Persistent</code> and
205		* escape that using the current locale and a MEDIUM DateFormat.
206		*
207		* See org/melati/admin/SelectionWindowSelection.wm
208		* See org/melati/admin/Update.wm
209		* @param o
210		* @return the escaped DisplayString
211		*/
212		String escaped(Persistent o);
213
214		/**
215		* Encode a String as a UTF-8 URL.
216		*
217		* @param s the String to encode
218		* @return the encoded String
219		*/
220		String encoded(String s);
221
222		/**
223		* Decode a UTF-8 URL encode string.
224		* @param s
225		* @return the decoded String
226		*/
227		String decoded(String s);
228		}
229
230