Skip to content

WEmailField

Jump to bottom
Mark Reeves edited this page Jan 3, 2018 · 23 revisions

WEmailField is a component for creating a text input field with specific constraints for email addresses. When used within a user agent and platform which support alternate soft keyboards (such as tablets and smart phones) an email address optimised keyboard may be presented to the user.

For further information see WTextField; the remainder of this document is concerned with differences between WEmailField and WTextField.

Why use WEmailField

WEmailField should always be used when the user input is expected to be an email address. WEmailField has inbuilt validation for email addresses and, perhaps more importantly, on mobile devices and other systems that provide soft input abilities a WEmailField will present the user with an email address optimized keyboard.

When in a read-only state WEmailField provides an email link.

Accessibility

See accessibility notes of WTextField as they all apply to WEmailField.

HTML output

A WEmailField will output a HTML input element in the email state wrapped in a HTML span element. This contains an interactive, form bound control and therefore may not be used in any context where the content model forbids this content category.

When in a read-only state the output will be a HTML a element containing the text value of the component as a mailto: protocol link.

Sample appearance

WEmailField (when not in a read-only state) outputs a HTML input element in the email state. The appearance of this is dependent on the user agent. The illustrations in this document were all created using Google Chrome on OS X.

  • a WEmailField with no input

    A typical WEmailField with no input

  • a WEmailField with user input

    A typical WEmailField with user input

Input pattern

The pattern property is not applied in WEmailField. All WEmailFields implement a default pattern to determine if the entered content is likely to be an email address. This pattern is loosely based on common browser implementations of the HTML specification for a valid email address.

Read-only

See WTextField.

If the WEmailField has content and is in a read-only state then the output will be a HTML a element containing the text value of the component as a mailto: protocol link.

  • a WEmailField with content in a read-only state

    A typical WEmailField in a readOnly state

Testing

WEmailField may be tested using the com.github.bordertech.wcomponents.test.selenium.element.SeleniumWEmailFieldWebElement extension of org.openqa.selenium.WebElement.

The best way to get a WEmailField from a test view is by using SeleniumWComponentsWebDriver which has a method findWEmailField(By). This can be used in conjunction with com.github.bordertech.wcomponents.test.selenium.ByLabel, for example, to find a WEmailField using its label's text.

@Test
public void testFindByLabel() {
  SeleniumWComponentsWebDriver driver = getDriver();
  String labelText = "Email address";
  SeleniumWEmailFieldWebElement field = driver.findWEmailField(
    new ByLabel(labelText, false));
  Assert.assertNotNull("Unable to find email field by label text", field);
}

For more information on members provided by SeleniumWEmailFieldWebElement see:

Related components

Further information

Some start pages

Clone this wiki locally