Text input 2.3 implementation

This article needs a technical review. How you can help.

This page details how to implement Firefox OS 2.3 text input web components ( <gaia-text-input>, <gaia-text-input-multiline>, and <gaia-text-input-pin>) in your own app.

Installation

First of all, make sure you have followed the preliminary setup instructions. Next, cd into the directory containing your web app. You can install the gaia-text-input component with:

bower install gaia-components/gaia-text-input

The command installs not only the gaia-text-input component (broken up into gaia-text-input, gaia-text-input-multiline, and gaia-text-input-pin), but also the base gaia-component code that all gaia components need to run, plus the Gaia icons set that many Gaia web components make use of.

Examples

The following gives you an idea of what rendered gaia text inputs would look like:

You can find the gaia-text-input source code on Github, plus a detailed live example.

Note: Remember that you need to be using a browser that supports web components (see the preliminary setup instructions for details.)

Code

This section details all the code you need.

CSS and JavaScript

To include all of the styles and script that these components make use of, you need to add the following to your document head:

<script src="bower_components/gaia-icons/gaia-icons.js"></script>
<link rel="stylesheet" type="text/css" href="bower_components/gaia-icons/gaia-icons.css"></link>
<script src="bower_components/gaia-component/gaia-component.js"></script>
<script src="bower_components/gaia-text-input/gaia-text-input.js"></script>
<script src="bower_components/gaia-text-input/gaia-text-input-multiline.js"></script>
<script src="bower_components/gaia-text-input/gaia-text-input-pin.js"></script>

gaia-text-input HTML

The following shows example code for standard text inputs:

<gaia-text-input id="field" placeholder="Default"></gaia-text-input>
<gaia-text-input placeholder="Search" type="search"></gaia-text-input>
<gaia-text-input placeholder="Email" type="email" clearable></gaia-text-input>
<gaia-text-input placeholder="Disabled" disabled></gaia-text-input>
<gaia-text-input placeholder="Search" type="search" disabled></gaia-text-input>
<gaia-text-input placeholder="Email" type="email" clearable disabled></gaia-text-input>

The <gaia-text-input> element has the following specialist attributes available:

  • type: Specifies that you want this text input to be a specialist type (omit this attribute for a standard text input) — the available types are:
    • search
    • e-mail
  • placeholder="placeholder": Specifies placeholder text that will appear inside the input before it has text entered into it.
  • clearable: If this is set, then the text input will be clearable — when focused, a cross icon will appear at the right hand side of the input that when pressed will clear all the contents.
  • value="value": Specifies some text that will be prefilled into the field when the view first loads.
  • required: If specified, the containing dialog box/form won't submit until the field is filled in.
  • maxlength=number: Specifies a max length for the text string that can be entered into the field.
  • disabled: If specified, the input is disabled.

gaia-text-input-multiline HTML

The following shows example code for multiline text inputs:

<gaia-text-input-multiline placeholder="Multiline"></gaia-text-input-multiline>
<gaia-text-input-multiline placeholder="Multiline" disabled></gaia-text-input-multiline>

The <gaia-text-input-multiline> element has the following specialist attributes available:

  • placeholder="placeholder": Specifies placeholder text that will appear inside the input before it has text entered into it.
  • value="value": Specifies some text that will be prefilled into the field when the view first loads.
  • required: If specified, the containing dialog box/form won't submit until the field is filled in.
  • disabled: If specified, the input is disabled.

gaia-text-input-pin HTML

The following shows example code for pin text inputs — that is, inputs for entering pin numbers/passwords:

<gaia-text-input-pin length="4"></gaia-text-input-pin>
<gaia-text-input-pin length="4" disabled></gaia-text-input-pin>

The <gaia-text-input-pin> element has the following specialist attributes available:

  • length=number: Sets the number of characters that must be filled in for the pin/password — an appropriate number of boxes will be shown. The default is 4 if the attribute is not specified.
  • value="value": Specifies some text that will be prefilled into the field when the view first loads.
  • disabled: If specified, the input is disabled.

Document Tags and Contributors

 Contributors to this page: chrisdavidmills, kscarfone
 Last updated by: chrisdavidmills,