NumInput Component Reference

Related documents

• Component Overview
• Component Reference
• Built-in Components
• Template Markup Language (TML) Reference
• NumOutput Component Reference
• Numeric Input State Variable Reference

Table of Contents

• Introduction
  • Numeric Input types
  • Plus-Minus layout
• Attributes
• Instance methods
  • Inherited methods
  • getValue()
  • setDisabled()
  • setFmt()
  • setValue()
  • setClassName()
• Children
• DOM element properties

Introduction

Syntax

tml`<NumInput .../>`

The NumInput component creates renders a numeric input. It is a separate component used by the Numeric Input state variable so that it can be reused by other components.

The numeric limits and format is set by the fmt attribute. See NumFmt Reference.

The NumInput component has several methods that can be used to allow parent components to dynamically manipulate the state of the rendered elements. See [Instance methods](#instance methods).

Numeric Input types

The input may be rendered in several forms depending on the inputType attribute. The inputType attribute may take on the following values:

• keyboard
  The standard device keyboard (either virtual or physical).
• keypad
  A popup numeric keypad.
• thumbwheel
  A popup numeric thumbwheel.

Plus-Minus layout

The rendered component also depends on the plusMinus, verticaland title attributes. If the plusMinus attribute is present and truthy, the input, as specified by the inputType attribute, is surrounded by a '-' button and a '+' button. These buttons will decrement or increment the input according to the rndMult property of the NumFmt specified in the fmt attribute. If the vertical attribute is present and truthy, the buttons appear above and below the input. Lastly, the title attribute specifies a title to appear above the plusMinus input.

Attributes

• Standard properties
  The NumInput component accepts the standard attributes.
• disabled
  If present and truthy, the input will appear greyed out and will not be user-changeable. For the keypad and thumbwheel input types, the attribute is not applied initially (clicks are not blocked until setDisabled() is called). For valueOnly, disabled is meaningless.
• fmt
  A NumFmt instance that specifies the format, rounding and limits of the number.
• max
  A number that overrides the maximum of the fmt. If omitted, fmt.max is used.
• min
  A number that overrides the minimum of the fmt. If omitted, fmt.min is used.
• onUserChange (required unless valueOnly)
  A function to call when the user changes the value, with the signature fn(value). For the keyboard input type, value is the string typed in the input (called on change and on blur); for keypad, thumbwheel and the plus/minus buttons it is a number.
• inputType
  A string that specifies the type of numeric input. It may take on one of the following values:
  • keyboard (default)
    The standard device keyboard (either virtual or physical).
  • keypad
    A popup numeric keypad.
  • thumbwheel
    A popup numeric thumbwheel.
• plusMinus
  If present and truthy, specifies rendering the input with '+' and '-' buttons. See Plus-Minus layout.
• title
  If present, specifies a string that appears above a Plus-Minus layout input. The title attribute is ignored if the plusMinus attribute is not present or falsey.
• units
  A string containing a unit abbreviation. If present, the units abbreviation is rendered after the numeric input.
• value
  The initial value of the displayed input.
• valueOnly
  If present and truthy, the input will be displayed as text and will not be user-changeable.
• vertical
  If present and truthy, specifies rendering the input with '+' and '-' buttons above and below the numeric input. See Plus-Minus layout.The vertical attribute is ignored if the plusMinus attribute is not present or falsey.

Instance methods

These methods are intended to be used by parent components to dynamically change the properties of the rendered components without re-rendering.

Inherited methods

• Component methods

getValue()

Syntax

getValue()

Returns the current value of the rendered element.

Return value

A Number, or a String if the user has typed into a keyboard input. Not available when valueOnly (a NumOutput is rendered, whose getValue() is not defined).

setDisabled()

Syntax

setDisabled(b)

Sets the rendered element's disabled property to b and adds or removes the input-disabled CSS class. Not available when valueOnly: it forwards to the NumOutput component, which has no setDisabled() method, so it throws.

Parameters

• b
  A Boolean.

setFmt()

Syntax

setFmt(fmt)

Sets the rendered element's min, max, and step from the fmt instance (step is fmt.step; the keypad and thumbwheel types set only min and max). Not available when valueOnly (it throws).

Parameters

• fmt
  A NumFmt instance.

setValue()

Syntax

setValue(value)

Sets the rendered element's value.

Parameters

• value
  A Number or a numeric String.

setClassName()

Syntax

setClassName(cn)

Replaces the rendered element's CSS class string with cn plus numInput (and input-disabled if the input is disabled). If cn is omitted, the component's current class name is used.

Parameters

• cn (optional)
  A CSS class string.

Children

The NumInput component ignores all children.

DOM element properties

The NumInput is rendered in several different ways:

• If the valueOnly attribute is truthy, the input is rendered using a NumOutput component.
• If the inputType attribute is keyboard, it will render an <input> element. The element type will be <input type=number> when the element has the focus and will be <input type=text> when it does not.
• If the inputType attribute is keypad or thumbwheel it will render an <span> element that, when clicked, will display a popup numeric keypad or numeric thumbwheel. The <span> will have input and popupInput CSS class strings.
• The numeric input element will have a numInput CSS class string.
• The width of the input field will be set according to the width property of the fmt attribute.
• When the rendered element is a <input type=number>, the min, max, and step properties will be set according to the min and max attributes (defaulting to the min and max properties of fmt) and the step property of the fmt attribute, respectively. The <input>element's disabled property will be set according to the current disabled state.
• If a units attribute is present, the numeric input and a <span> containing the unit abbreviation are contained in an NbSpan component. The <span> containing the unit abbreviation will have a numUnits CSS class string.