changes.
| | h2. 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 is optionsl. The popup is slightly larger but does not take a title. It is very easy to create a custom colorEntry layout with examples shown in the showcase. |
| | | _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. |
| | |
| | |
| | {tip}When included in the release, you can see the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=colorEntryBean] of this component, complete with source code.{tip} |
| | |
| | h2. Getting Started |
| | {panel} |
| | {code:xml|borderStyle=dashed}<ace:colorEntry id="colorInput" value="#{colorEntryBean.value}" label="Choose Color:" labelPosition="left" /> |
| | {code} |
| | {panel} |
| | |
| | h2. Attributes |
| | |
| | {tip:title=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|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/colorEntry.html].{tip}{panel} |
| | *value* is the String value in the format chosen by valueFormat. |
| | {panel} |
| | {panel} |
| | *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". |
| | {panel} |
| | {panel} |
| | *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). |
| | {panel} |
| | {panel} |
| | 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"); |
| | {panel} |
| | |
| | {panel} |
| | 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. |
| | {panel} |
| | {panel} |
| | 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. |
| | {panel} |
| | {panel} |
| | 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). |
| | {panel} |
| | {panel} |
| | The *buttonText* attribute will allow users to use their own language/text on a button that triggers the popup. |
| | {panel} |
| | {panel} |
| | 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 |
| | {panel} |
| | {panel} |
| | The *popupIconOnly* attribute means that only the popupIcon is rendered and clicking on it will open the panel containing the colorEntry component. |
| | {panel} |
| | {panel} |
| | The *buttonColorize* attribute will fill in the default button with the currently selected color. It defaults to true |
| | {panel} |
| | {panel} |
| | The *renderAsPopup* attribute determines if the component is inline (false) or a popup (true). |
| | {panel} |
| | {panel} |
| | The *alpha" 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. |
| | {panel} |
| | {panel} |
| | The *showCancelButton* attribute defaults to true. It can be set to false if this button is not required. |
| | {panel} |
| | {panel} |
| | The *showCloseButton* attribute defaults to true. It can be set to false if this button is not required. |
| | {panel} |
| | {panel} |
| | 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. |
| | {panel} |
| | {panel} |
| | The *styleClass* attribute will allow an extra class of css styling attributes to be added to the existing styling. |
| | {panel} |
| | {panel} |
| | 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 |
| | {panel} |
| | {panel} |
| | 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. |
| | {panel} |
| | {panel} |
| | 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). |
| | {panel} |
| | {panel} |
| | The *swatchesWidth* attribute allows a width in pixels to be used on the swatches part. |
| | {panel} |
| | |
| | |
| | h2. Client Behavior Events |
| | |
| | | change | Fired when the color input field changes value (default event). | |
| | |
| | h2. JavaScript API |
| | |
| | |
| | h4. 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. |
| | |
| | {code}var widget = ice.ace.instance('frm:componentId);{code} |
| | |
| | {tip}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">_).{tip} |
| | |
| | {info}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. |
| | {info} |
| | |
| | h2. 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). |
| | |
| | h2. 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. |
| | |
| | |
| | |
| | h2. CSS Classes |
| | |
| | This component conforms to jquery-ui styling. |
| | |
| | |
| | h2. Keyboard and ARIA Support |
| | |
| | The following ARIA roles are supported: input. |
| | |
| | h2. Known Issues |
| | |
| | |
| | |
| | h2. Additional Resources |
ColorEntry