KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > au > id > jericho > lib > html > FormControlOutputStyle


1 // Jericho HTML Parser - Java based library for analysing and manipulating HTML
2 // Version 2.2
3 // Copyright (C) 2006 Martin Jericho
4 // http://sourceforge.net/projects/jerichohtml/
5 //
6 // This library is free software; you can redistribute it and/or
7 // modify it under the terms of the GNU Lesser General Public
8 // License as published by the Free Software Foundation; either
9 // version 2.1 of the License, or (at your option) any later version.
10 // http://www.gnu.org/copyleft/lesser.html
11 //
12 // This library is distributed in the hope that it will be useful,
13 // but WITHOUT ANY WARRANTY; without even the implied warranty of
14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 // Lesser General Public License for more details.
16 //
17 // You should have received a copy of the GNU Lesser General Public
18 // License along with this library; if not, write to the Free Software
19 // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20
21 package au.id.jericho.lib.html;
22
23 import java.util.*;
24
25 /**
26  * An enumerated type representing the three major output styles of a {@linkplain FormControl form control's}
27  * <a HREF="FormControl.html#OutputElement">output element</a>.
28  * <p>
29  * A form control's output style is set using the {@link FormControl#setOutputStyle(FormControlOutputStyle)} method.
30  */
31 public final class FormControlOutputStyle {
32     private String JavaDoc description;
33
34     /**
35      * Normal display of the <a HREF="FormControl.html#OutputElement">output element</a>.
36      * <p>
37      * This is the default display style.
38      */
39     public static final FormControlOutputStyle NORMAL=new FormControlOutputStyle("NORMAL");
40
41     /**
42      * Remove the <a HREF="FormControl.html#OutputElement">output element</a> from the {@linkplain OutputDocument output document} completely.
43      */
44     public static final FormControlOutputStyle REMOVE=new FormControlOutputStyle("REMOVE");
45
46     /**
47      * The {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element</a> is replaced with a simple representation
48      * of the {@linkplain FormControl form control's} <a HREF="FormControl.html#SubmissionValue">submission value(s)</a>.
49      * <p>
50      * The implementation of this functionality is highly subjective, but provides a more aesthetic way of displaying a read-only version
51      * of a form without having to resort to using {@linkplain FormControl#isDisabled() disabled} controls.
52      * <p>
53      * The representation is dependent on the {@linkplain FormControlType form control type}, and can be configured using the
54      * static properties of the {@link ConfigDisplayValue ConfigDisplayValue} nested class.
55      * <p>
56      * Unless specified otherwise below, the {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element</a> is
57      * replaced with a <i><a name="DisplayValueElement">display value element</a></i> having the {@linkplain Element#getName() name}
58      * specified in the static {@link ConfigDisplayValue#ElementName ConfigDisplayValue.ElementName} property
59      * (<code>div</code> by default).
60      * The attributes specified in the static {@link ConfigDisplayValue#AttributeNames ConfigDisplayValue.AttributeNames} list
61      * (<code>id</code>, <code>class</code> and <code>style</code> by default) are copied from
62      * the {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element</a> into the
63      * <a HREF="#DisplayValueElement">display value element</a>.
64      * <p>
65      * Details of the content of the <a HREF="#DisplayValueElement">display value element</a> or other representation of the
66      * control value are as follows:
67      * <dl>
68      * <dt>{@link FormControlType#TEXT TEXT}, {@link FormControlType#FILE FILE}
69      * <dd>The content of the <a HREF="#DisplayValueElement">display value element</a> is the
70      * {@linkplain CharacterReference#reencode(CharSequence) re-encoded} value of the
71      * {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element's</a> <code>value</code> attribute.
72      * <dt>{@link FormControlType#TEXTAREA TEXTAREA}
73      * <dd>The content of the <a HREF="#DisplayValueElement">display value element</a> is the content of the <code>TEXTAREA</code> element
74      * re-encoded {@linkplain CharacterReference#encodeWithWhiteSpaceFormatting(CharSequence) with white space formatting}.
75      * <dt>{@link FormControlType#CHECKBOX CHECKBOX}, {@link FormControlType#RADIO RADIO}
76      * <dd>The {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element</a> is replaced with the
77      * un-encoded content specified in the {@link ConfigDisplayValue#CheckedHTML ConfigDisplayValue.CheckedHTML} or
78      * {@link ConfigDisplayValue#UncheckedHTML ConfigDisplayValue.UncheckedHTML} static property, depending on
79      * whether the {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element</a> contains a
80      * <code>checked</code> attribute.
81      * If the relevant static property has a value of <code>null</code> (the default), the
82      * <a HREF="FormControl.html#OutputElement">output element</a> is simply a {@linkplain FormControl#setDisabled(boolean) disabled}
83      * version of the form control.
84      * Attempting to determine which labels might apply to which checkbox or radio button, allowing only the
85      * selected controls to be displayed, would require a very complex and inexact algorithm, so is best left to the developer
86      * to implement if required.
87      * <dt>{@link FormControlType#SELECT_SINGLE SELECT_SINGLE}, {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}
88      * <dd>The content of the <a HREF="#DisplayValueElement">display value element</a> is the
89      * {@linkplain CharacterReference#reencode(CharSequence) re-encoded} label of the currently selected option.
90      * In the case of a {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} control, all labels of selected options
91      * are listed, separated by the text specified in the static
92      * {@link ConfigDisplayValue#MultipleValueSeparator ConfigDisplayValue.MultipleValueSeparator} property
93      * ("<code>, </code>" by default).
94      * <dt>{@link FormControlType#PASSWORD PASSWORD}
95      * <dd>The content of the <a HREF="#DisplayValueElement">display value element</a> is the
96      * {@linkplain CharacterReference#encode(CharSequence) encoded} character specified in the
97      * {@link ConfigDisplayValue#PasswordChar ConfigDisplayValue.PasswordChar} static property ('<code>*</code>' by default),
98      * repeated <i>n</i> times, where <i>n</i> is the number of characters in the control's
99      * <a HREF="FormControl.html#SubmissionValue">submission value</a>.
100      * <dt>{@link FormControlType#HIDDEN HIDDEN}
101      * <dd>The <a HREF="FormControl.html#OutputElement">output element</a> is {@linkplain #REMOVE removed} completely.
102      * <dt>{@link FormControlType#BUTTON BUTTON}, {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#IMAGE IMAGE}
103      * <dd>The <a HREF="FormControl.html#OutputElement">output element</a>
104      * is a {@linkplain FormControl#setDisabled(boolean) disabled} version of the original form control.
105      * </dl>
106      * <p>
107      * If the <a HREF="FormControl.html#SubmissionValue">submission value</a> of the control is <code>null</code> or an empty string,
108      * the <a HREF="#DisplayValueElement">display value element</a> is given the un-encoded content specified in the
109      * {@link ConfigDisplayValue#EmptyHTML ConfigDisplayValue.EmptyHTML} static property.
110      */
111     public static final FormControlOutputStyle DISPLAY_VALUE=new FormControlOutputStyle("DISPLAY_VALUE");
112
113     private FormControlOutputStyle(final String JavaDoc description) {
114         this.description=description;
115     }
116
117     /**
118      * Returns a string representation of this object useful for debugging purposes.
119      * @return a string representation of this object useful for debugging purposes.
120      */
121     public String JavaDoc getDebugInfo() {
122         return description;
123     }
124
125     /**
126      * Returns a string representation of this object useful for debugging purposes.
127      * <p>
128      * This is equivalent to {@link #getDebugInfo()}.
129      *
130      * @return a string representation of this object useful for debugging purposes.
131      */
132     public String JavaDoc toString() {
133         return getDebugInfo();
134     }
135
136     /**
137      * Contains static properties that configure the {@link #DISPLAY_VALUE} form control output style.
138      * <p>
139      * None of the properties should be assigned a <code>null</code> value.
140      * <p>
141      * See the documentation of the {@link #DISPLAY_VALUE} output style for details on how these properties are used.
142      */
143     public static final class ConfigDisplayValue {
144
145         /**
146          * Defines the text that is used to separate multiple values in a
147          * <a HREF="FormControlOutputStyle.html#DisplayValueElement">display value element</a>.
148          * <p>
149          * This property is only relevant to {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} form controls, and is only used
150          * if multiple items in the control are selected.
151          * <p>
152          * The default value is "<code>, </code>".
153          */
154         public static volatile String JavaDoc MultipleValueSeparator=", ";
155
156         /**
157          * Defines the {@linkplain Element#getName() name} of
158          * <a HREF="FormControlOutputStyle.html#DisplayValueElement">display value elements</a>.
159          * <p>
160          * The default value is "<code>div</code>".
161          * <p>
162          * Although all form control {@linkplain FormControl#getElement() elements} are
163          * {@linkplain HTMLElements#getInlineLevelElementNames() inline-level} elements, the default replacement is the
164          * {@linkplain HTMLElements#getBlockLevelElementNames() block-level} {@link HTMLElementName#DIV DIV} element, which allows
165          * richer stylesheet formatting than the most common alternative, the {@link HTMLElementName#SPAN SPAN} element,
166          * such as the ability to set its <code>width</code> and <code>height</code>.
167          * <p>
168          * This has the undesired effect in some cases of displaying the value on a new line, whereas the original form control
169          * was not on a new line. In practical use however, many form controls are placed inside table cells for better control
170          * over their positioning. In this case replacing the original inline form control with the block <code>DIV</code>
171          * element does not alter its position.
172          */
173         public static volatile String JavaDoc ElementName=HTMLElementName.DIV;
174
175         /**
176          * Defines the names of the {@linkplain Attributes attributes} that are copied from the normal form control
177          * <a HREF="FormControl.html#OutputElement">output element</a> to a
178          * <a HREF="FormControlOutputStyle.html#DisplayValueElement">display value element</a>.
179          * <p>
180          * The names included in the list by default are "<code>id</code>", "<code>class</code>" and "<code>style</code>".
181          * <p>
182          * These attributes are usually all that is needed to identify the elements in style sheets or specify the styles directly.
183          * <p>
184          * The default list is modifiable.
185          */
186         public static volatile List AttributeNames=new ArrayList(Arrays.asList(new String JavaDoc[] {Attribute.ID,Attribute.CLASS,Attribute.STYLE}));
187
188         /**
189          * Defines the content of a <a HREF="FormControlOutputStyle.html#DisplayValueElement">display value element</a>
190          * if the <a HREF="FormControl.html#SubmissionValue">submission value</a> of the control is <code>null</code> or an empty string.
191          * <p>
192          * The content is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
193          * <p>
194          * The default content is "<code>&amp;nbsp;</code>".
195          */
196         public static volatile String JavaDoc EmptyHTML="&nbsp;";
197         
198         /**
199          * Defines the character used to represent the value of a {@link FormControlType#PASSWORD PASSWORD} form control
200          * in a <a HREF="#DisplayValueElement">display value element</a>.
201          * <p>
202          * The character is repeated <i>n</i> times, where <i>n</i> is the number of characters in the control's
203          * <a HREF="FormControl.html#SubmissionValue">submission value</a>.
204          * <p>
205          * The resulting string is {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
206          * <p>
207          * The default password character is '<code>*</code>'.
208          */
209         public static volatile char PasswordChar='*';
210         
211         /**
212          * Defines the HTML which replaces the {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element</a>
213          * of a {@link FormControlType#CHECKBOX CHECKBOX} or {@link FormControlType#RADIO RADIO} form control if it contains a
214          * <code>checked</code> attribute.
215          * <p>
216          * If this property is <code>null</code>, the <a HREF="FormControl.html#OutputElement">output element</a> is simply a
217          * {@linkplain FormControl#setDisabled(boolean) disabled} version of the form control.
218          * <p>
219          * The HTML is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
220          * <p>
221          * The default value is <code>null</code>.
222          */
223         public static volatile String JavaDoc CheckedHTML=null;
224
225         /**
226          * Defines the HTML which replaces the {@linkplain #NORMAL normal} <a HREF="FormControl.html#OutputElement">output element</a>
227          * of a {@link FormControlType#CHECKBOX CHECKBOX} or {@link FormControlType#RADIO RADIO} form control if it does not contain a
228          * <code>checked</code> attribute.
229          * <p>
230          * If this property is <code>null</code>, the <a HREF="FormControl.html#OutputElement">output element</a> is simply a
231          * {@linkplain FormControl#setDisabled(boolean) disabled} version of the form control.
232          * <p>
233          * The HTML is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
234          * <p>
235          * The default value is <code>null</code>.
236          */
237         public static volatile String JavaDoc UncheckedHTML=null;
238
239         private ConfigDisplayValue() {}
240     }
241 }
242
Popular Tags