net.htmlparser.jericho.FormControlOutputStyle Maven / Gradle / Ivy

// Jericho HTML Parser - Java based library for analysing and manipulating HTML
// Version 3.4
// Copyright (C) 2004-2013 Martin Jericho
// http://jericho.htmlparser.net/
//
// This library is free software; you can redistribute it and/or
// modify it under the terms of either one of the following licences:
//
// 1. The Eclipse Public License (EPL) version 1.0,
// included in this distribution in the file licence-epl-1.0.html
// or available at http://www.eclipse.org/legal/epl-v10.html
//
// 2. The GNU Lesser General Public License (LGPL) version 2.1 or later,
// included in this distribution in the file licence-lgpl-2.1.txt
// or available at http://www.gnu.org/licenses/lgpl.txt
//
// 3. The Apache License version 2.0,
// included in this distribution in the file licence-apache-2.0.html
// or available at http://www.apache.org/licenses/LICENSE-2.0.html
//
// This library is distributed on an "AS IS" basis,
// WITHOUT WARRANTY OF ANY KIND, either express or implied.
// See the individual licence texts for more details.

package net.htmlparser.jericho;

import java.util.*;

/**
 * An enumerated type representing the three major output styles of a {@linkplain FormControl form control's}
 * output element.
 * 
 * A form control's output style is set using the {@link FormControl#setOutputStyle(FormControlOutputStyle)} method.
 */
public enum FormControlOutputStyle {
	/**
	 * Normal display of the output element.
	 * 

	 * This is the default display style.
	 */
	NORMAL,

	/**
	 * Remove the output element from the {@linkplain OutputDocument output document} completely.
	 */
	REMOVE,

	/**
	 * The {@linkplain #NORMAL normal} output element is replaced with a simple representation
	 * of the {@linkplain FormControl form control's} submission value(s).
	 * 

	 * The implementation of this functionality is highly subjective, but provides a more aesthetic way of displaying a read-only version
	 * of a form without having to resort to using {@linkplain FormControl#isDisabled() disabled} controls.
	 * 

	 * The representation is dependent on the {@linkplain FormControlType form control type}, and can be configured using the
	 * static properties of the {@link ConfigDisplayValue ConfigDisplayValue} nested class.
	 * 

	 * Unless specified otherwise below, the {@linkplain #NORMAL normal} output element is 
	 * replaced with a display value element having the {@linkplain Element#getName() name}
	 * specified in the static {@link ConfigDisplayValue#ElementName ConfigDisplayValue.ElementName} property
	 * (div by default).
	 * The attributes specified in the static {@link ConfigDisplayValue#AttributeNames ConfigDisplayValue.AttributeNames} list
	 * (id, class and style by default) are copied from
	 * the {@linkplain #NORMAL normal} output element into the
	 * display value element.
	 * 

	 * Details of the content of the display value element or other representation of the
	 * control value are as follows:
	 * 

	 * 

	 *  {@link FormControlType#TEXT TEXT}, {@link FormControlType#FILE FILE}
	 *   
The content of the display value element is the
	 *    {@linkplain CharacterReference#reencode(CharSequence) re-encoded} value of the
	 *    {@linkplain #NORMAL normal} output element's value attribute.
	 *  
{@link FormControlType#TEXTAREA TEXTAREA}
	 *   
The content of the display value element is the content of the TEXTAREA element
	 *    re-encoded {@linkplain CharacterReference#encodeWithWhiteSpaceFormatting(CharSequence) with white space formatting}.
	 *  
{@link FormControlType#CHECKBOX CHECKBOX}, {@link FormControlType#RADIO RADIO}
	 *   
The {@linkplain #NORMAL normal} output element is replaced with the
	 *    un-encoded content specified in the {@link ConfigDisplayValue#CheckedHTML ConfigDisplayValue.CheckedHTML} or
	 *    {@link ConfigDisplayValue#UncheckedHTML ConfigDisplayValue.UncheckedHTML} static property, depending on
	 *    whether the {@linkplain #NORMAL normal} output element contains a
	 *    checked attribute.
	 *    If the relevant static property has a value of null (the default), the 
	 *    output element is simply a {@linkplain FormControl#setDisabled(boolean) disabled}
	 *    version of the form control.
	 *    Attempting to determine which labels might apply to which checkbox or radio button, allowing only the
	 *    selected controls to be displayed, would require a very complex and inexact algorithm, so is best left to the developer
	 *    to implement if required.
	 *  
{@link FormControlType#SELECT_SINGLE SELECT_SINGLE}, {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE}
	 *   
The content of the display value element is the
	 *    {@linkplain CharacterReference#reencode(CharSequence) re-encoded} label of the currently selected option.
	 *    In the case of a {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} control, all labels of selected options
	 *    are listed, separated by the text specified in the static
	 *    {@link ConfigDisplayValue#MultipleValueSeparator ConfigDisplayValue.MultipleValueSeparator} property
	 *    (", " by default).
	 *  
{@link FormControlType#PASSWORD PASSWORD}
	 *   
The content of the display value element is the
	 *    {@linkplain CharacterReference#encode(CharSequence) encoded} character specified in the
	 *    {@link ConfigDisplayValue#PasswordChar ConfigDisplayValue.PasswordChar} static property ('*' by default),
	 *    repeated n times, where n is the number of characters in the control's
	 *    submission value.
	 *  
{@link FormControlType#HIDDEN HIDDEN}
	 *   
The output element is {@linkplain #REMOVE removed} completely.
	 *  
{@link FormControlType#BUTTON BUTTON}, {@link FormControlType#SUBMIT SUBMIT}, {@link FormControlType#IMAGE IMAGE}
	 *   
The output element
	 *    is a {@linkplain FormControl#setDisabled(boolean) disabled} version of the original form control.
	 * 
	 * 
	 * If the submission value of the control is null or an empty string,
	 * the display value element is given the un-encoded content specified in the
	 * {@link ConfigDisplayValue#EmptyHTML ConfigDisplayValue.EmptyHTML} static property.
	 */
	DISPLAY_VALUE;

	/**
	 * Returns a string representation of this object useful for debugging purposes.
	 * 

	 * This is equivalent to {@link #toString()}.
	 *
	 * @return a string representation of this object useful for debugging purposes.
	 */
	public String getDebugInfo() {
		return toString();
	}

	/**
	 * Contains static properties that configure the {@link #DISPLAY_VALUE} form control output style.
	 * 

	 * None of the properties should be assigned a null value.
	 * 

	 * See the documentation of the {@link #DISPLAY_VALUE} output style for details on how these properties are used.
	 */
	public static final class ConfigDisplayValue {

		/**
		 * Defines the text that is used to separate multiple values in a 
		 * display value element.
		 * 

		 * This property is only relevant to {@link FormControlType#SELECT_MULTIPLE SELECT_MULTIPLE} form controls, and is only used
		 * if multiple items in the control are selected.
		 * 

		 * The default value is ", ".
		 */
		public static volatile String MultipleValueSeparator=", ";

		/**
		 * Defines the {@linkplain Element#getName() name} of
		 * display value elements.
		 * 

		 * The default value is "div".
		 * 

		 * Although all form control {@linkplain FormControl#getElement() elements} are
		 * {@linkplain HTMLElements#getInlineLevelElementNames() inline-level} elements, the default replacement is the
		 * {@linkplain HTMLElements#getBlockLevelElementNames() block-level} {@link HTMLElementName#DIV DIV} element, which allows
		 * richer stylesheet formatting than the most common alternative, the {@link HTMLElementName#SPAN SPAN} element, 
		 * such as the ability to set its width and height.
		 * 

		 * This has the undesired effect in some cases of displaying the value on a new line, whereas the original form control
		 * was not on a new line.  In practical use however, many form controls are placed inside table cells for better control
		 * over their positioning.  In this case replacing the original inline form control with the block DIV
		 * element does not alter its position.
		 */
		public static volatile String ElementName=HTMLElementName.DIV;

		/**
		 * Defines the names of the {@linkplain Attributes attributes} that are copied from the normal form control
		 * output element to a
		 * display value element.
		 * 

		 * The names included in the list by default are "id", "class" and "style".
		 * 

		 * These attributes are usually all that is needed to identify the elements in style sheets or specify the styles directly.
		 * 

		 * The default list is modifiable.
		 */
		public static volatile List AttributeNames=new ArrayList(Arrays.asList(new String[] {Attribute.ID,Attribute.CLASS,Attribute.STYLE}));

		/**
		 * Defines the content of a display value element
		 * if the submission value of the control is null or an empty string.
		 * 

		 * The content is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
		 * 

		 * The default content is "&nbsp;".
		 */
		public static volatile String EmptyHTML=" ";
		
		/**
		 * Defines the character used to represent the value of a {@link FormControlType#PASSWORD PASSWORD} form control
		 * in a display value element.
		 * 

		 * The character is repeated n times, where n is the number of characters in the control's
		 * submission value.
		 * 

		 * The resulting string is {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
		 * 

		 * The default password character is '*'.
		 */
		public static volatile char PasswordChar='*';
		
		/**
		 * Defines the HTML which replaces the {@linkplain #NORMAL normal} output element
		 * of a {@link FormControlType#CHECKBOX CHECKBOX} or {@link FormControlType#RADIO RADIO} form control if it contains a
		 * checked attribute.
		 * 

		 * If this property is null, the output element is simply a 
		 * {@linkplain FormControl#setDisabled(boolean) disabled} version of the form control.
		 * 
	
		 * The HTML is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
		 * 

		 * The default value is null.
		 */
		public static volatile String CheckedHTML=null;

		/**
		 * Defines the HTML which replaces the {@linkplain #NORMAL normal} output element
		 * of a {@link FormControlType#CHECKBOX CHECKBOX} or {@link FormControlType#RADIO RADIO} form control if it does not contain a
		 * checked attribute.
		 * 

		 * If this property is null, the output element is simply a 
		 * {@linkplain FormControl#setDisabled(boolean) disabled} version of the form control.
		 * 
	
		 * The HTML is not {@linkplain CharacterReference#encode(CharSequence) encoded} before output.
		 * 
		 * The default value is null.
		 */
		public static volatile String UncheckedHTML=null;

		private ConfigDisplayValue() {}
	}
}