Coverage Report

Coverage Report - org.melati.template.MarkupLanguage

Classes in this File

 /*
  * $Source$
  * $Revision$
  *
  * 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 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
    */
   String rendered(Object o);
   
   /**
    * @param s markup fragment to render
    * @return fragment rendered with markup unchanged
    */
   String renderedMarkup(String s);
 
 
   /**
    * 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
    * @return - the String having been rendered in a MarkupLanguage specific way.
    */
   String rendered(String s, int limit);
 
   /**
    * 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 TemplateEngineException - if there is a problem with the
    *                                   ServletTemplateEngine
    */
   String rendered(Field<?> field, int style)
           throws TemplateEngineException;
 
   /**
    * 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 TemplateEngineException - if there is a problem with the
    *                                   ServletTemplateEngine
    */
   String rendered(Field<?> field, int style, int limit)
           throws TemplateEngineException;
 
   /**
    * 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.
    */
   String renderedStart(Field<?> field);
 
   
   
   //
   // =========
   //  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, 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, 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, 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 encoded string.
    * @param s
    * @return the decoded String
    */
   String decoded(String s);
 }
 
 

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