001: // Jericho HTML Parser - Java based library for analysing and manipulating HTML
002: // Version 2.5
003: // Copyright (C) 2007 Martin Jericho
004: // http://jerichohtml.sourceforge.net/
005: //
006: // This library is free software; you can redistribute it and/or
007: // modify it under the terms of either one of the following licences:
008: //
009: // 1. The Eclipse Public License (EPL) version 1.0,
010: // included in this distribution in the file licence-epl-1.0.html
011: // or available at http://www.eclipse.org/legal/epl-v10.html
012: //
013: // 2. The GNU Lesser General Public License (LGPL) version 2.1 or later,
014: // included in this distribution in the file licence-lgpl-2.1.txt
015: // or available at http://www.gnu.org/licenses/lgpl.txt
016: //
017: // This library is distributed on an "AS IS" basis,
018: // WITHOUT WARRANTY OF ANY KIND, either express or implied.
019: // See the individual licence texts for more details.
020:
021: package au.id.jericho.lib.html;
022:
023: import java.util.*;
024:
025: /**
026: * An enumerated type representing the three major output styles of a {@linkplain FormControl form control's}
027: * <a href="FormControl.html#OutputElement">output element</a>.
028: * <p>
029: * A form control's output style is set using the {@link FormControl#setOutputStyle(FormControlOutputStyle)} method.
030: */
031: public final class FormControlOutputStyle {
032: private String description;
033:
034: /**
035: * Normal display of the <a href="FormControl.html#OutputElement">output element</a>.
036: * <p>
037: * This is the default display style.
038: */
039: public static final FormControlOutputStyle NORMAL = new FormControlOutputStyle(
040: "NORMAL");
041:
042: /**
043: * Remove the <a href="FormControl.html#OutputElement">output element</a> from the {@linkplain OutputDocument output document} completely.
044: */
045: public static final FormControlOutputStyle REMOVE = new FormControlOutputStyle(
046: "REMOVE");
047:
048: /**
049: * The {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element</a> is replaced with a simple representation
050: * of the {@linkplain FormControl form control's} <a href="FormControl.html#SubmissionValue">submission value(s)</a>.
051: * <p>
052: * The implementation of this functionality is highly subjective, but provides a more aesthetic way of displaying a read-only version
053: * of a form without having to resort to using {@linkplain FormControl#isDisabled() disabled} controls.
054: * <p>
055: * The representation is dependent on the {@linkplain FormControlType form control type}, and can be configured using the
056: * static properties of the {@link ConfigDisplayValue ConfigDisplayValue} nested class.
057: * <p>
058: * Unless specified otherwise below, the {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element</a> is
059: * replaced with a <i><a name="DisplayValueElement">display value element</a></i> having the {@linkplain Element#getName() name}
060: * specified in the static {@link ConfigDisplayValue#ElementName ConfigDisplayValue.ElementName} property
061: * (<code>div</code> by default).
062: * The attributes specified in the static {@link ConfigDisplayValue#AttributeNames ConfigDisplayValue.AttributeNames} list
063: * (<code>id</code>, <code>class</code> and <code>style</code> by default) are copied from
064: * the {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element</a> into the
065: * <a href="#DisplayValueElement">display value element</a>.
066: * <p>
067: * Details of the content of the <a href="#DisplayValueElement">display value element</a> or other representation of the
068: * control value are as follows:
069: * <p>
070: * <dl>
071: * <dt>{@link FormControlType#TEXT TEXT}, {@link FormControlType#FILE FILE}
072: * <dd>The content of the <a href="#DisplayValueElement">display value element</a> is the
073: * {@linkplain CharacterReference#reencode(CharSequence) re-encoded} value of the
074: * {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element's</a> <code>value</code> attribute.
075: * <dt>{@link FormControlType#TEXTAREA TEXTAREA}
076: * <dd>The content of the <a href="#DisplayValueElement">display value element</a> is the content of the <code>TEXTAREA</code> element
077: * re-encoded {@linkplain CharacterReference#encodeWithWhiteSpaceFormatting(CharSequence) with white space formatting}.
078: * <dt>{@link FormControlType#CHECKBOX CHECKBOX}, {@link FormControlType#RADIO RADIO}
079: * <dd>The {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element</a> is replaced with the
080: * un-encoded content specified in the {@link ConfigDisplayValue#CheckedHTML ConfigDisplayValue.CheckedHTML} or
081: * {@link ConfigDisplayValue#UncheckedHTML ConfigDisplayValue.UncheckedHTML} static property, depending on
082: * whether the {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element</a> contains a
083: * <code>checked</code> attribute.
084: * If the relevant static property has a value of <code>null</code> (the default), the
085: * <a href="FormControl.html#OutputElement">output element</a> is simply a {@linkplain FormControl#setDisabled(boolean) disabled}
086: * version of the form control.
087: * Attempting to determine which labels might apply to which checkbox or radio button, allowing only the
088: * selected controls to be displayed, would require a very complex and inexact algorithm, so is best left to the developer
089: * to implement if required.
090: * <dt>{@link FormControlType#SELECT_SINGLE SELECT_SINGLE}, {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}
091: * <dd>The content of the <a href="#DisplayValueElement">display value element</a> is the
092: * {@linkplain CharacterReference#reencode(CharSequence) re-encoded} label of the currently selected option.
093: * In the case of a {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} control, all labels of selected options
094: * are listed, separated by the text specified in the static
095: * {@link ConfigDisplayValue#MultipleValueSeparator ConfigDisplayValue.MultipleValueSeparator} property
096: * ("<code>, </code>" by default).
097: * <dt>{@link FormControlType#PASSWORD PASSWORD}
098: * <dd>The content of the <a href="#DisplayValueElement">display value element</a> is the
099: * {@linkplain CharacterReference#encode(CharSequence) encoded} character specified in the
100: * {@link ConfigDisplayValue#PasswordChar ConfigDisplayValue.PasswordChar} static property ('<code>*</code>' by default),
101: * repeated <i>n</i> times, where <i>n</i> is the number of characters in the control's
102: * <a href="FormControl.html#SubmissionValue">submission value</a>.
103: * <dt>{@link FormControlType#HIDDEN HIDDEN}
104: * <dd>The <a href="FormControl.html#OutputElement">output element</a> is {@linkplain #REMOVE removed} completely.
105: * <dt>{@link FormControlType#BUTTON BUTTON}, {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#IMAGE IMAGE}
106: * <dd>The <a href="FormControl.html#OutputElement">output element</a>
107: * is a {@linkplain FormControl#setDisabled(boolean) disabled} version of the original form control.
108: * </dl>
109: * <p>
110: * If the <a href="FormControl.html#SubmissionValue">submission value</a> of the control is <code>null</code> or an empty string,
111: * the <a href="#DisplayValueElement">display value element</a> is given the un-encoded content specified in the
112: * {@link ConfigDisplayValue#EmptyHTML ConfigDisplayValue.EmptyHTML} static property.
113: */
114: public static final FormControlOutputStyle DISPLAY_VALUE = new FormControlOutputStyle(
115: "DISPLAY_VALUE");
116:
117: private FormControlOutputStyle(final String description) {
118: this .description = description;
119: }
120:
121: /**
122: * Returns a string representation of this object useful for debugging purposes.
123: * @return a string representation of this object useful for debugging purposes.
124: */
125: public String getDebugInfo() {
126: return description;
127: }
128:
129: /**
130: * Returns a string representation of this object useful for debugging purposes.
131: * <p>
132: * This is equivalent to {@link #getDebugInfo()}.
133: *
134: * @return a string representation of this object useful for debugging purposes.
135: */
136: public String toString() {
137: return getDebugInfo();
138: }
139:
140: /**
141: * Contains static properties that configure the {@link #DISPLAY_VALUE} form control output style.
142: * <p>
143: * None of the properties should be assigned a <code>null</code> value.
144: * <p>
145: * See the documentation of the {@link #DISPLAY_VALUE} output style for details on how these properties are used.
146: */
147: public static final class ConfigDisplayValue {
148:
149: /**
150: * Defines the text that is used to separate multiple values in a
151: * <a href="FormControlOutputStyle.html#DisplayValueElement">display value element</a>.
152: * <p>
153: * This property is only relevant to {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} form controls, and is only used
154: * if multiple items in the control are selected.
155: * <p>
156: * The default value is "<code>, </code>".
157: */
158: public static volatile String MultipleValueSeparator = ", ";
159:
160: /**
161: * Defines the {@linkplain Element#getName() name} of
162: * <a href="FormControlOutputStyle.html#DisplayValueElement">display value elements</a>.
163: * <p>
164: * The default value is "<code>div</code>".
165: * <p>
166: * Although all form control {@linkplain FormControl#getElement() elements} are
167: * {@linkplain HTMLElements#getInlineLevelElementNames() inline-level} elements, the default replacement is the
168: * {@linkplain HTMLElements#getBlockLevelElementNames() block-level} {@link HTMLElementName#DIV DIV} element, which allows
169: * richer stylesheet formatting than the most common alternative, the {@link HTMLElementName#SPAN SPAN} element,
170: * such as the ability to set its <code>width</code> and <code>height</code>.
171: * <p>
172: * This has the undesired effect in some cases of displaying the value on a new line, whereas the original form control
173: * was not on a new line. In practical use however, many form controls are placed inside table cells for better control
174: * over their positioning. In this case replacing the original inline form control with the block <code>DIV</code>
175: * element does not alter its position.
176: */
177: public static volatile String ElementName = HTMLElementName.DIV;
178:
179: /**
180: * Defines the names of the {@linkplain Attributes attributes} that are copied from the normal form control
181: * <a href="FormControl.html#OutputElement">output element</a> to a
182: * <a href="FormControlOutputStyle.html#DisplayValueElement">display value element</a>.
183: * <p>
184: * The names included in the list by default are "<code>id</code>", "<code>class</code>" and "<code>style</code>".
185: * <p>
186: * These attributes are usually all that is needed to identify the elements in style sheets or specify the styles directly.
187: * <p>
188: * The default list is modifiable.
189: */
190: public static volatile List AttributeNames = new ArrayList(
191: Arrays.asList(new String[] { Attribute.ID,
192: Attribute.CLASS, Attribute.STYLE }));
193:
194: /**
195: * Defines the content of a <a href="FormControlOutputStyle.html#DisplayValueElement">display value element</a>
196: * if the <a href="FormControl.html#SubmissionValue">submission value</a> of the control is <code>null</code> or an empty string.
197: * <p>
198: * The content is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
199: * <p>
200: * The default content is "<code>&nbsp;</code>".
201: */
202: public static volatile String EmptyHTML = " ";
203:
204: /**
205: * Defines the character used to represent the value of a {@link FormControlType#PASSWORD PASSWORD} form control
206: * in a <a href="#DisplayValueElement">display value element</a>.
207: * <p>
208: * The character is repeated <i>n</i> times, where <i>n</i> is the number of characters in the control's
209: * <a href="FormControl.html#SubmissionValue">submission value</a>.
210: * <p>
211: * The resulting string is {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
212: * <p>
213: * The default password character is '<code>*</code>'.
214: */
215: public static volatile char PasswordChar = '*';
216:
217: /**
218: * Defines the HTML which replaces the {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element</a>
219: * of a {@link FormControlType#CHECKBOX CHECKBOX} or {@link FormControlType#RADIO RADIO} form control if it contains a
220: * <code>checked</code> attribute.
221: * <p>
222: * If this property is <code>null</code>, the <a href="FormControl.html#OutputElement">output element</a> is simply a
223: * {@linkplain FormControl#setDisabled(boolean) disabled} version of the form control.
224: * <p>
225: * The HTML is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
226: * <p>
227: * The default value is <code>null</code>.
228: */
229: public static volatile String CheckedHTML = null;
230:
231: /**
232: * Defines the HTML which replaces the {@linkplain #NORMAL normal} <a href="FormControl.html#OutputElement">output element</a>
233: * of a {@link FormControlType#CHECKBOX CHECKBOX} or {@link FormControlType#RADIO RADIO} form control if it does not contain a
234: * <code>checked</code> attribute.
235: * <p>
236: * If this property is <code>null</code>, the <a href="FormControl.html#OutputElement">output element</a> is simply a
237: * {@linkplain FormControl#setDisabled(boolean) disabled} version of the form control.
238: * <p>
239: * The HTML is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
240: * <p>
241: * The default value is <code>null</code>.
242: */
243: public static volatile String UncheckedHTML = null;
244:
245: private ConfigDisplayValue() {
246: }
247: }
248: }
|