com.sun.webui.jsf.component.RadioButton Maven / Gradle / Ivy
/*
* The contents of this file are subject to the terms
* of the Common Development and Distribution License
* (the License). You may not use this file except in
* compliance with the License.
*
* You can obtain a copy of the license at
* https://woodstock.dev.java.net/public/CDDLv1.0.html.
* See the License for the specific language governing
* permissions and limitations under the License.
*
* When distributing Covered Code, include this CDDL
* Header Notice in each file and include the License file
* at https://woodstock.dev.java.net/public/CDDLv1.0.html.
* If applicable, add the following below the CDDL Header,
* with the fields enclosed by brackets [] replaced by
* you own identifying information:
* "Portions Copyrighted [year] [name of copyright owner]"
*
* Copyright 2007 Sun Microsystems, Inc. All rights reserved.
*/
package com.sun.webui.jsf.component;
import com.sun.faces.annotation.Component;
import com.sun.faces.annotation.Property;
import java.util.Map;
import javax.el.ValueExpression;
import javax.faces.context.FacesContext;
/**
* A component that represents a radio button.
*
* The RadioButton can be used as a single radio button
* or one radio button among a group of radio button. A group
* of radio button represents a multiple selection list which can have any
* number of radio button selected, or none selected. A radio button can
* represent a Boolean value, a String value,
* or a developer defined Object value.
*
* Detecting a selected radio button
*
* The RadioButton uses both the selected
* and selectedValue properties to pass information about
* the radio button's selection status. The selected
* property is used to indicate that the radio button is selected.
* The selectedValue property is used to pass a data value,
* a string by default, for the radio button. A radio button is considered to be
* selected when the value of the selected property is equal
* to the value of the selectedValue property. A radio button can
* be initally selected by assigning the same value
* to the selectedValue and the selected
* properties. isChecked is called to determine
* if this RadioButton is selected.
*
* If the selectedValue property is not specified or its
* value is null then the radio button behaves like a
* boolean control. If the radio button is selected, the value of the
* selected property is a true Boolean
* instance. If the radio button is not selected, the value of the
* selected property will be a false Boolean
* instance.
*
* Note that a value binding expression that evaluates to a
* primitive boolean value can be assigned to the selected
* property. Proper type coercion from Boolean to
* boolean occurs.
*
*
* When a radio button is part of a group, the selected radio
* button is maintained as a request attribute in the
* RequestMap. The name of the attribute is
* the value of the radio button's name property.
* The request attribute value is the
* value of the selectedValue property of the
* selected radio button.
* The selected property
* of the selected radio button within the group, will also contain the
* value of the selectedValue property of the
* respective selected radio button. If no radio buttons are selected,
* no request attribute is created, however at least one radio button
* must be selected.
*
*
* Note that the RadioButton does not enforce the
* requirement that at least one radio button must be selected.
* The application should ensure that this requirement is met.
*
* Using a radio button tag as a boolean control
*
* If the selectedValue property is not specified or its
* value is null then the radio button behaves like a
* boolean control.
*
*
* To use the RadioButton as a boolean control, do not
* specify a value for the selectedValue property. The
* radio button is selected if the selected property is not
* null and has the value of a Boolean instance with a true
* value. If the radio button is not selected, then the value of the
* selected property is a false Boolean instance.
*
* Note that using a boolean radio button in a group and
* referencing the request property for the selected radio button is not
* useful, since the value of the request property will be an
* indistinguishable true value.
*
* Using a RadioButton to represent a developer defined
* value
* The selectedValue property can be assigned a
* developer defined object value to represent the value of a selected
* radio button. If the radio button is selected, the value of the
* selected property is assigned the value of the
* selectedValue property.
*
*
* If the value of the selectedValue property is a
* developer defined object, a Converter must be registered
* to convert to and from a String value.
* In addition the object must support an
* equals method that returns true when the
* value of the selectedValue property is compared to
* the selected property value in order to detect a
* selected radio button.
*
* Using a RadioButton as one control in a group
*
* The name property determines whether a
* radio button is part of a group. A radio button is treated as part of a group
* of radio buttons if the name property of the radio button is
* assigned a value equal to the name property of the other
* radio buttons in the group. In other words, all radio button of a
* group have the same name property value. The group behaves
* like a single selection list, where only one radio button
* can be selected. The value of the name property must
* be unique within the scope of the Form parent containing the
* radio buttons.
*
* Facets
*
* The following facets are supported:
*
*
* - image If the image facet exists, it replaces the
* {@link com.sun.webui.jsf.component.ImageComponent} subcompoent
* normally created for the image associated with the radio button,
* if the
imageURL property is not null.
* - label If the label facet exists, it replaces the
* {@link com.sun.webui.jsf.component.Label} subcomponent normally
* created for the label associated with the radio button, if the
* label property is not null.
*
*
* Add an image or label facet to the RadioButton if more
* control over the properties of the subcomponents is needed.
*
*
* Note that if a facet is exists, RadioButton properties
* that would normally be assigned to the created subcomponent, will
* not be assigned to the facet
*
*
* Note that unexpected layout of the RadioButton may occur
* if the component specified by the facet is not a
* {@link com.sun.webui.jsf.component.ImageComponent} for the image facet or
* {@link com.sun.webui.jsf.component.Label} for the label facet.
*
* ImageComponent and Label subcomponents
*
* An image and a label may be associated with the
* RadioButton.
* If the imageURL property is not null and an image facet
* does not exist then a {@link com.sun.webui.jsf.component.ImageComponent}
* component is created.
* If the label property is not null and a label facet does not
* exist then a {@link com.sun.webui.jsf.component.Label} component is
* created.
*
*
* The following RadioButton properties are assigned to
* the subcomponents only if a facet does not exist.
* For the {@link com.sun.webui.jsf.component.ImageComponent} subcomponent
*
this.getId() + "_image" is assigned to the id property.
* - this.getImageURL() is assigned to the
url property.
* - this.getToolTip() is assigned to the
toolTip property.
* - this.getToolTip() is assigned to the
alt property.
* - this.isVisible() is assigned to the
visible property.
* - this.isRendered() is assigned to the
renderer property.
*
*
*
* For the {@link com.sun.webui.jsf.component.Label} subcomponent
*
* - this.getId() + "_label" is assigned to the
id
* property.
* - this.getClientId() is assigned to the
for
* property.
* - this.getLabel() is assigned to the
text property.
* - this.getLabelLevel is assigned to the
labelLevel property.
* - this.getToolTip is assigned to the
toolTip property.
* - this.isVisible is assigned to the
visible property.
* - this.isRendered is assigned to the
renderer property.
*
*
* Note that if a value binding exists for one of the
* RadioButton properties mentioned above, the value binding is
* set on the subcomponent for that property.
*
*/
@Component(type = "com.sun.webui.jsf.RadioButton", family = "com.sun.webui.jsf.RadioButton",
displayName = "Radio Button", tagName = "radioButton",
helpKey = "projrave_ui_elements_palette_wdstk-jsf1.2_radiobutton",
propertiesHelpKey = "projrave_ui_elements_palette_wdstk-jsf1.2_propsheets_radio_button_props")
public class RadioButton extends RbCbSelector {
/**
* Default constructor.
*/
public RadioButton() {
super();
setMultiple(false);
setRendererType("com.sun.webui.jsf.RadioButton");
}
/**
* Return the family for this component.
*/
@Override
public String getFamily() {
return "com.sun.webui.jsf.RadioButton";
}
/**
* Return the value of the selectedValue property
* of the selected radio button in the group of radio buttons
* identified by the name parameter.
* A RadioButton is one of a group of radio buttons
* if more than on radio button has the same value for the
* name property.
* When one of the radio buttons among that group is selected,
* the value of its selectedValue property
* is maintained in a request attribute identified by the value
* of its name property.
*
* @param name the value a RadioButton name property.
*/
public static Object getSelected(String name) {
Map rm = FacesContext.getCurrentInstance().getExternalContext().
getRequestMap();
if (name != null) {
return rm.get(name);
} else {
return null;
}
}
/**
* Update the request parameter that holds the value of the
* selectedValue property of the selected radio button.
*
* If the name property has been set
* a request attribute is created.
* The value of the name property will
* be used for the request attribute name and the value of the request
* attribute will be the value of the
* selectedValue property.
*
* The request attribute described above is available during
* a ValueChangeEvent.
*
*
* @param context The context of this request.
*/
@Override
public void validate(FacesContext context) {
super.validate(context);
if (!(isValid() && isChecked())) {
return;
}
String groupName = getName();
if (groupName == null) {
return;
}
addToRequestMap(context, groupName);
}
@Override
protected void addToRequestMap(FacesContext context, String groupName) {
Map requestMap = context.getExternalContext().getRequestMap();
requestMap.put(groupName, getValue());
}
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Tag attribute methods
// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
// Hide items
@Property(name = "items", isHidden = true, isAttribute = false)
@Override
public Object getItems() {
return super.getItems();
}
// Hide required
@Property(name = "required", isHidden = true, isAttribute = false)
@Override
public boolean isRequired() {
return super.isRequired();
}
// Hide hidden
@Property(isHidden = true, isAttribute = false)
@Override
public Object getValue() {
return super.getValue();
}
// Hide onSelect
@Property(isHidden = true, isAttribute = false)
@Override
public String getOnSelect() {
return super.getOnSelect();
}
/**
* Sets the style level for the generated label, provided the
* label attribute has been set. Valid values are 1 (largest), 2 and
* 3 (smallest). The default value is 3.
*/
@Property(name = "labelLevel", displayName = "Label Level", category = "Appearance",
editorClassName = "com.sun.webui.jsf.component.propertyeditors.LabelLevelsEditor")
private int labelLevel = Integer.MIN_VALUE;
private boolean labelLevel_set = false;
/**
* Sets the style level for the generated label, provided the
* label attribute has been set. Valid values are 1 (largest), 2 and
* 3 (smallest). The default value is 3.
*/
@Override
public int getLabelLevel() {
if (this.labelLevel_set) {
return this.labelLevel;
}
ValueExpression _vb = getValueExpression("labelLevel");
if (_vb != null) {
Object _result = _vb.getValue(getFacesContext().getELContext());
if (_result == null) {
return Integer.MIN_VALUE;
} else {
return ((Integer) _result).intValue();
}
}
return 3;
}
/**
* Sets the style level for the generated label, provided the
* label attribute has been set. Valid values are 1 (largest), 2 and
* 3 (smallest). The default value is 3.
* @see #getLabelLevel()
*/
@Override
public void setLabelLevel(int labelLevel) {
this.labelLevel = labelLevel;
this.labelLevel_set = true;
}
/**
* Restore the state of this component.
*/
@Override
public void restoreState(FacesContext _context, Object _state) {
Object _values[] = (Object[]) _state;
super.restoreState(_context, _values[0]);
this.labelLevel = ((Integer) _values[1]).intValue();
this.labelLevel_set = ((Boolean) _values[2]).booleanValue();
}
/**
* Save the state of this component.
*/
@Override
public Object saveState(FacesContext _context) {
Object _values[] = new Object[3];
_values[0] = super.saveState(_context);
_values[1] = new Integer(this.labelLevel);
_values[2] = this.labelLevel_set ? Boolean.TRUE : Boolean.FALSE;
return _values;
}
}