TextEntry

Version 8 by Yip Ng
on Jul 20, 2012 16:19.

<< Changes from 7 to 8
compared with
Current by Arturo Zambrano
on Dec 11, 2014 04:24.

 
Key
These lines were removed. This word was removed.
These lines were added. This word was added.

View page history


There are 18 changes. View first change.

 h2. Overview
 _Since 3.1_
  
_TextEntry_ is a component for entering single line text. It has additional styling and functional feature.
  _TextEntry_ is a component for entering single line text. It has additional styling and functional features. Styling is controlled via the theme style sheet using predefined style classes. Additional attributes add functional features.
  
{tip}See the ICEfaces Showcase [Live Demo|http://icefaces-showcase.icesoft.org/showcase.jsf?grp=aceMenu&exp=textEntryBean] of this component, complete with source code.{tip}
  
 h2. Getting Started
 {panel}
 {code:xml|borderStyle=dashed}<ace:textEntry id="firstNameInput" value="#{textEntryBean.firstName}" label="First Name" labelPosition="left" required="true" requiredIndicator="(*)" indicatorPosition="right"/>
 {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 is available [here|http://www.icefaces.org/docs/v3_latest/ace/tld/ace/TextEntry.html].{tip}{panel}
  {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 is available [here|http://www.icefaces.org/docs/v4_latest/ace/tld/ace/textEntry.html].{tip}{panel}
 *value* is the input text.
 {panel}
 {panel}
*renderAsPopup* determines whether the calendar is displayed inline or as a popup. Default is false, i.e. inline.
  *label* and *labelPosition* specify the label text and its position relative to the input field. Positions can be "left/right/top/bottom/inField/none". Default is "none".
 {panel}
 {panel}
The *pattern* attribute&nbsp; is used to specify the date/time format of the text input field. It also affects whether the time entry sliders appear in the calendar. The pattern characters are as detailed in the [java.text.SimpleDateFormat javadoc|http://download.oracle.com/javase/1.5.0/docs/api/java/text/SimpleDateFormat.html]. (Some uncommon pattern characters may not be translatable to pattern characters for the client side date/time object.) When an hour field is present in the pattern, the time entry sliders will appear.
  *required* indicates whether the user is required to provide a non-empty submitted value for this component. Default = "false".
 {panel}
 {panel}
*timeZone* is used to set the date's time zone. It can be a string or java.util.TimeZone object.
  The *secret* boolean attribute can be set to "true" to display asterisks in place of the actual entered text, such as when capturing a password, etc. Default = 'false'.
 {panel}
 
 {panel}
Month/year navigation is by left and right arrow images, one month at a time. To also navigate by month/year drop down lists, set *navigator* to true.
  The *type* attribute for the input element. Currently supports text, phone, url, email, number, date, time, datetime. Depending on device capability, a type-specific keyboard may be displayed.
 {panel}
 {panel}
To enter time only, set *timeOnly* to true.
  The *autotab* attribute (when true) causes the component to automatically tab to the next component once the maxLength number of characters have been entered.
 {panel}
{panel}
 Multiple months can be displayed by specifying the no. of months in *pages*.
 {panel}
   
 h2. Event Listeners
  
 | valueChangeListener | Listener method that will be notified when a new value has been set for this input component. |
  
 h2. Client Behavior Events
  
| dateSelect | Fired when a date is selected from the calendar (default event). |
  | blur | Fired when the text input field loses focus (default event). |
  
 h2. JavaScript API
  
The client side date/time object is exposed through the global variable named by the *widgetVar* attribute, but currently there is no API useful to the user.
  h4. ICEfaces 3.x
  
h2. Keyboard Support
  The client side component object is exposed through the global variable name specified in the *widgetVar* attribute.
  
These keyboard shortcuts work only in a popup calendar without the time component. Some of them may conflict with browser keyboard shortcuts.
 || Keypress || Result ||
 | page up/down | previous/next month |
 | ctrl+page up/down | previous/next year |
 | ctrl+home | current month or open when closed |
 | ctrl+left/right | previous/next day |
 | ctrl+up/down | previous/next week |
 | enter | select the focused day |
 | ctrl+end | close and erase the date |
 | escape | close the calendar without selection |
  h4. ICEfaces 4+
  
The "widgetVar" attribute on the ACE components has been removed in ICEfaces 4 and in its place a new "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. Required Styling
  
 Then this component is marked as {{required}}, the main input field receives the CSS class {{ui-state-required}}, otherwise, it receives the CSS class {{ui-state-optional}}. When this component is marked as invalid by the app, it will be rendered with the CSS class {{ui-state-error}}. These CSS classes can be used to add custom styling to this component, in order indicate its current state in a more visual way.
  
 h2. CSS Classes
  
 The following markup represents the basic HTML structure of the component and the CSS classes it uses.
  
 {code:xml}
 <span>
  <span>
  <input class="ui-inputfield ui-textentry ui-widget ui-state-default ui-corner-all [user defined classes]" style="[user defined styles]" />
  <span class="ui-required-indicator ui-required-indicator-right">*</span>
  </span>
 </span>
 {code}
 h2. Keyboard and ARIA Support
  
 The following ARIA roles are supported: textbox.
  
 h2. Known Issues
  
 {info}The "secret" attribute is not supported on IE8 browsers.{info}
  
 h2. Additional Resources

© Copyright 2021 ICEsoft Technologies Canada Corp.