ColorEntry

Table of Contents

Overview

Since 4.2

ColorEntry is a component for entering a string that represents a color in various formats. Two default configurations are offered or a custom layout can be created. If renderAsPopup is false, an inline version of the component (minimalistic) is rendered and the title attribute can be used instead of a label. The popup is slightly larger but does not take a title and can be used with the label attribute. It is very easy to create a custom colorEntry layout or configuration with examples shown in the showcase.

When included in the release, you can see the ICEfaces Showcase Live Demo of this component, complete with source code.

Getting Started

<ace:colorEntry id="colorInput" value="#{colorEntryBean.value}" label="Choose Color:" labelPosition="left" />

Attributes

TagLib Documentation
This section covers attributes involved in the typical use-cases for this component. For reference, the complete taglib documentation for this component will be available once released here.

value is the String value in the format chosen by valueFormat.

label and labelPosition specify the label text and its position relative to the input field. Positions can be "left/right/top/bottom/none". Default is "none".

required indicates whether the user is required to provide a non-empty submitted value for this component. Default = "false". The color selector widget will allow the user to select no color when false. (a box with an X in it).

The colorFormat attribute requires a value from the org.icefaces.ace.component.colorentry.ColorFormat Enum class. Default = 'HEX'. Other values available are HEXA("HEXA"), HEXA4("HEXA4"), HEX3("HEX3"), HSL("HSL"), HSLA("HSLA"), HSLPERCENT("HSL%"), RGB("RGB"), RGBA("RGBA"), RGBPERCENT("RGB%"), NAME("NAME"), EXACT("EXACT");

The title attribute can be used to customize the title displayed on the header of the component. Note that the default popup (renderAsPopup=true) does not take a title attribute.

The customParts attribute can be used in tandem with the customLayout attribute to specify a customized version of this component. customParts takes a list of Strings representing part names (i.e. 'header', 'map', 'bar', 'hex', 'hsv', 'rgb', 'alpha', 'lab', 'cmyk', 'preview', 'swatches', 'footer'). A custom layout should correspond. The header and footer need no layout definition.

The customLayout attribute sets the position of elements in a table layout. You could create any layout possible with HTML tables by specifying cell position and size of each part. This attribute takes a list of org.icefaces.ace.model.colorEntry.ColorEntryLayout objects which contain a string (representing a part in the list of parts), as well as the table layout of column, row, columnspan, rowspan. These coordinates correspond to cells in a table, so if you want to have a part at top-left and spanning two rows and three columns, the value would be [0, 0, 3, 2]. (column, row, columspan, rowspan as per this object).

The buttonText attribute will allow users to use their own language/text on a button that triggers the popup.

The popupIcon attribute will allow users to use their own icon on the button that triggers the popup. It defaults to the one in the library

The popupIconOnly attribute means that only the popupIcon is rendered and clicking on it will open the panel containing the colorEntry component.

The buttonColorize attribute will fill in the default button with the currently selected color. It defaults to true

The renderAsPopup attribute determines if the component is inline (false) or a popup (true). The default is the inline version of the component.

The *showAlpha" attribute will show inputs for alpha if true (opacity). The colorFormat of HSL requires an alpha value. When opening the component if HSL is chosen as format, then the user may be see the transparency view to select a value, in order to calculate the HSL.

The showCancelButton attribute defaults to true. It can be set to false if this button is not required.

The showCloseButton attribute defaults to true. It can be set to false if this button is not required.

The showNoneButton attribute defaults to false. This button allows the user to clear the component and enter a none value to be submitted. It can be set to true if this button is required.

The styleClass attribute will allow an extra class of css styling attributes to be added to the existing styling.

The locale attribute allows regionalization of the labels on this component. the locales that are built into the component and included with just changing the string value of this attribute are 'de', 'el', 'en', 'en-GB', 'en-US', 'fr', 'nl', 'pt-br', 'sr', 'ru'. By using a full submit and changing the locale of the viewRoot, you can override the labels with a <message-bundle> in faces-config.xml configuration as per standard JSF. The keys are
org.icefaces.ace.component.colorentry.regional.ok=OK
org.icefaces.ace.component.colorentry.regional.cancel=Cancel
org.icefaces.ace.component.colorentry.regional.none=None
org.icefaces.ace.component.colorentry.regional.button=Color
org.icefaces.ace.component.colorentry.regional.title=Choose A Color
org.icefaces.ace.component.colorentry.regional.transparent=Transparent
org.icefaces.ace.component.colorentry.regional.hsvH=H
org.icefaces.ace.component.colorentry.regional.hsvS=S
org.icefaces.ace.component.colorentry.regional.hsvV=V
org.icefaces.ace.component.colorentry.regional.rgbR=R
org.icefaces.ace.component.colorentry.regional.rgbG=G
org.icefaces.ace.component.colorentry.regional.rgbB=B
org.icefaces.ace.component.colorentry.regional.labL=L
org.icefaces.ace.component.colorentry.regional.labA=a
org.icefaces.ace.component.colorentry.regional.labB=b
org.icefaces.ace.component.colorentry.regional.hslH=H
org.icefaces.ace.component.colorentry.regional.hslS=S
org.icefaces.ace.component.colorentry.regional.hslL=L
org.icefaces.ace.component.colorentry.regional.cmykC=C
org.icefaces.ace.component.colorentry.regional.cmykM=M
org.icefaces.ace.component.colorentry.regional.cmykY=Y
org.icefaces.ace.component.colorentry.regional.cmykK=K
org.icefaces.ace.component.colorentry.regional.alphaA=A

The swatchesName attribute allows indication of a defined palette of colours the user can choose from. Four pre-defined swatches are included and shown in the showcase example. They are 'html', 'pantone', 'crayola', 'ral-classic', 'x11'. Swatches can also be created and linked to this attribute. If a value other than these four is used, then the new swatch must be defined in the swatches attribute.

The swatches attribute is a list of <SwatchEntry>, where each SwatchEntry defines a color by name and RGB (where 0<R<1, 0<G<1, 0<B<1).

The swatchesWidth attribute allows a width in pixels to be used on the swatches part of the component layout.

Client Behavior Events

change Fired when the color input field changes value (default event).

JavaScript API

ICEfaces 4+

"ice.ace.instance()" client JavaScript object lookup API has been introduced. The reason for this change is to enable lazy-initialization of the ACE component JavaScript objects to improve runtime performance and reduce browser memory use.

var widget = ice.ace.instance('frm:componentId);
The ice.ace.instance function requires the full client id of the component to be specified, such as "j_idt77:componentId" instead of just "componentId". To reduce the complexity of working with complete IDs with this function it may be preferable in some cases to use prependId="false" in the enclosing form (e.g. <h:form prependId="false">).
This component doesn't have a client-side API made specifically to be used by application developers. However, the component's internal methods and variables can be accessed in this way, including the underlying jQuery object and objects from underlying Javascript libraries (if applicable), and can be used for whatever purpose a developer might have in mind.

Labels

This component supports built-in labels. The text specified in the label attribute will be rendered next to the main input field of this component. The position specified by labelPosition will determine where this label is going to be rendered; the possible values are left, right, top, bottom, none and inField (to render the label in the field itself).

Required Indicator

The requiredIndicator attribute specifies the text to be displayed next to the main input field when this component is marked as required. When, this component is not marked as required, then the text specified in the optionalIndicator is going to be rendered. The indicatorPosition attribute determines where this indicator text is going to the rendered; the possible values are left, right, top, bottom, labelLeft, labelRight, and none.

CSS Classes

This component conforms to jquery-ui styling.

Keyboard and ARIA Support

The following ARIA roles are supported: input.

Known Issues

Additional Resources

Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.

© Copyright 2018 ICEsoft Technologies Canada Corp.