Input

From Frontal Wiki

Introduction to the input Tag

The 'input' tag is used to add input fields to a form created with the 'form' tag. As an example, here is the basic form of an input of type "text:"

<!-- Load the input components. -->
<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<!-- Create a text input. -->
<input type="text" />

Implementation

The 'input' tag is implemented with the class ContainerInput which extends the Container class which is what implements the 'div' tag. Therefore, all the features of a 'div' tag are available with the 'input' tag. This is important to note because Frontal does not define the visual presentation of the 'input' tag any further than that. It is up to a particular Frontal definition to do that. Fortunately, a number of different inputs are defined in The Default Frontal Style Sheet. In the section #How Inputs are Defined below, we'll go into detail about how this is done which will lead to discussions about how new types may be added or how existing types may be customized.

Properties

These properties are particular to the ContainerInput class:

• input: The Flash InteractiveObject used to implement this input.
• value: This will get the value of the input. It does this through the getValue interaction.
• form: If this input is inside of a 'form' tag, then this property refers to that element.

Attributes

These attributes are particular to the 'input' tag:

• name: The 'form' tag will use the name attribute of its inputs to label the values that are sent to the server. So if the server is expecting a phone number to be submitted with a label of "home_phone_number," then you would set the "name" attribute of the appropriate input to be "home_phone_number."
• value: Many of the input types support a value attribute. See the individual type descriptions for more details.
• tabIndex: The tab index defines in what order the inputs will be selected as the user hits the tab key to cycle through them. Frontal uses the Flash FocusManager class to implement this functionality.

In the following sections, we describe all of the input types defined in The Default Frontal Style Sheet.

The "button" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="button">Button Label</input>

This will display a button input using the Flash Button class.

If the button has a "value" attribute then it is used as the value of this input. If it does not have this attribute, then the button's label is used. This input only has a value while it is clicked.

The "submit" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="submit">Button Label</input>

This will display a submit button input using the Flash Button class. When clicked, it will submit its form (if one exists).

If the tag has a "value" attribute then it is used as the value of this input. If it does not have this attribute, then the button's label is used. This input only has a value while it is clicked.

This input type supports this custom style:

• custom-default-button: By default, a submit button input will be made the default button of a form. The effect of this is that hitting enter in a form will be equivalent to clicking this button. Set this style to "false" to prevent this button from being set as the default button.

The "checkbox" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="checkbox">Label</input>

This will display a checkbox input using the Flash CheckBox class.

If the tag has a "value" attribute then it is used as the value of this input when it is checked otherwise it is undefined. If it does not have this attribute, then true or false is used.

This input type supports these custom styles:

• custom-label-placement: This maps directly to the labelPlacement property of the CheckBox class. See the documentation of that class for details.
• custom-selected: "true" or "false," this maps directly to the selected property of the CheckBox class.

The "radio" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<form>
    <input type="radio" name="group1">Label1</input>
    <input type="radio" name="group1">Label2</input>
    <input type="radio" name="group2">Label3</input>
    <input type="radio" name="group2">Label4</input>
</form>

This will display a radio button input using the Flash RadioButton class. Radio buttons with the same "name" attribute and in a 'form' tag will be grouped via the Flash class RadioButtonGroup.

If the tag has a "value" attribute then it is used as the value of the input when it is selected.

This input type supports these custom styles:

• custom-label-placement: This maps directly to the labelPlacement property of the RadioButton class. See the documentation of that class for details.
• custom-selected: "true" or "false," this maps directly to the selected property of the RadioButton class.

The "file" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="file" name="test1" style="custom-allow-multiple-selection: true;" />
<text name="test1FileSelection" />
 
<input type="file" fileSelectionNdx="fileSelection" buttonLabel="Choose File" />
<text name="fileSelection" />

This will display a file selection button using the Flash Button class. When this button is clicked, it will call the browse method of either the Flash FileReference or FileReferenceList class (depending on if the input allows multiple selections or not) to allow the user to choose one or more files.

The input is designed to work with a 'text' tag to display the current file choices. (It will work fine without this though.) A text tag will be associated with the file input in one of two ways. Either by setting the "fileSelectionNdx" attribute of the file input tag to the index of the text tag or by giving the text tag the same "name" attribute as the file input but with "FileSelection" added to it. In either case, the file input finds the text tag by calling "parent.gE()" with the calculated index. (See Accessing Frontal Tags for Scripting for more details about the "gE()" method.) See the example above for both cases in action.

This input type supports these custom styles:

• custom-allow-multiple-selection: If "true" then the user will be given a file dialogue box that allows multiple choices. If "false" then the file dialogue box will only allow a single selection.

These attributes are particular to the file input:

• message: The value of this atribute will be shown in the associated text tag when no files have been chosen. The default value is "no files selected".
• buttonLabel: The value of this atribute will be used to label the button. The default value is "Choose Files".

Furthermore, you may use specially formatted attributes to restrict the file types that are selectable with the file input tag. For each file type that is selectable, three attributes are used:

• description: The description of the filter. This maps to the description property of the Flash FileFilter class.
• extension: The file extension to filter on. This maps to the extension property of the Flash FileFilter class.
• macType: The Macintosh file type to filter on. This maps to the macType property of the Flash FileFilter class.

To group these attributes together, you give each set of three the same arbitrary suffix. Each group of these attributes are then used to instantiate a Flash FileFilter class which is registered with the FileReference or FileReferenceList to filter the selections. For example, this file input only allows images or Flash movies to be selected:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<style><![CDATA[
    .imageAndSWFInput
        {
            @description1: Images (*.gif, *.jpg, *.png)
            @extension1: *.jpg;*.gif;*.png
            @macType1: JPEG;jp2_;GIFF
            @description2: Flash Movies (*.swf)
            @extension2: *.swf
            @macType2: SWF
        }
]]></style>
<input type="file" name="test1" class="imageAndSWFInput" />
<text name="test1FileSelection" />

The "list" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="list">
    <item value="1">Item 1</item>
    <item value="2">Item 2</item>
    <item value="3">Item 3</item>
    <item value="4">Item 4</item>
    <item value="5">Item 5</item>
    <item value="6">Item 6</item>
    <item value="7">Item 7</item>
</input>

This will display a list input using the Flash List class.

The internal "item" elements are specific to this input and are not formally Frontal tags. They are used to populate the list in the order that they occur. Each entry in a Flash List instance has a label and a value. The label is simply what is presented to the user and is not, for example, what would be submitted to the server if the entry were selected during submission. That is the value. Therefore, each item entry has a "value" attribute. It may be left off though in which case the label and the value are equivalent.

This input type supports this custom style:

• custom-allow-multiple-selection: "true" or "false," this maps directly to the allowMultipleSelection property of the List class.

The "select" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="select">
    <item>Item 1</item>
    <item>Item 2</item>
    <item>Item 3</item>
    <item>Item 4</item>
    <item>Item 5</item>
    <item>Item 6</item>
    <item>Item 7</item>
</input>

This will display a drop-down list selector using the Flash ComboBox class.

The internal "item" elements are specific to this input and are not formally Frontal tags. They are used to populate the list in the order that they occur. Each entry in a Flash List instance has a label and a value. The label is simply what is presented to the user and is not, for example, what would be submitted to the server if the entry were selected during submission. That is the value. Therefore, each item entry has a "value" attribute. It may be left off though in which case the label and the value are equivalent.

The "text" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="text">Input Label</input>

This will display a text input using the Flash TextInput class. The contents of the 'input' tag will be used to pre-populate the input. Clicking into the input will then clear this pre-populated text. Clicking out without making a change will restore it. In this sense it makes a sort of label for the input.

To add a default, editable value to a text input, you could use the onFirstRender interaction for example:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="text" onFirstRender="input.text = 'default value';" />

The "password" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="password">Input Label</input>

This will display a text input using the Flash TextInput class and with the "displayAsPassword" property set to true. The contents of the 'input' tag will be used to pre-populate the input. Clicking into the input will then clear this pre-populated text. Clicking out without making a change will restore it. In this sense it makes a sort of label for the input.

To add a default, editable value to a password input, you could use the onFirstRender interaction for example:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="password" onFirstRender="input.text = 'default value';" />

The "textarea" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="textarea">Input Label</input>

This will display a text input using the Flash TextArea class. The contents of the 'input' tag will be used to pre-populate the input. Clicking into the input will then clear this pre-populated text. Clicking out without making a change will restore it. In this sense it makes a sort of label for the input.

To add a default, editable value to a textarea input, you could use the onFirstRender interaction for example:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="textarea" onFirstRender="input.text = 'default value';" />

The "stepper" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="stepper" />

This will display a stepper input using the Flash NumericStepper class.

This input type supports this custom style:

• custom-minimum: This sets the minimum value for the stepper. It maps directly to the minimum property of the NumericStepper class.
• custom-maximum: This sets the minimum value for the stepper. It maps directly to the maximum property of the NumericStepper class.
• custom-step-size: This sets the step size for the stepper. It maps directly to the stepSize property of the NumericStepper class.

The "hidden" Input

The basic form for this input is:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="hidden" name="foo" value="bar" />

This will add a hidden input to the form.

The value this input will return is set with the "value" attribute.

Why custom styles?

You probably noticed how all of the styles for inputs begin with "custom-". The reason for this is that Frontal will complain whenever it sees a style that it doesn't know about except in the case that it starts with "custom-". So why doesn't Frontal know about these input styles? This is because the input implementations have been made solely through the default style sheet and so are not deeply integrated with Frontal. The reason is to make it straightforward to replace the input implementations as desired. In the next section, we'll illustrate how an input was implemented in order to make it clear how they could be customized or augmented. And if you do add a new input type, you can use "custom-" styles to configure it.

How Inputs are Defined

Earlier we saw the basic text input:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
<input type="text">Input Label</input>

The question is, how is this input implemented? The answer is with a ruleset in The Default Frontal Style Sheet. Let's look at that ruleset in detail as a deep understanding will allow us to customize or replace it.

First, the ruleset has a selector to match all 'input' tags with the attribute "type" set to "text." (It also matches those with type "password" or "textarea" as we use the same rule set for those inputs as well.)

<style><![CDATA[
    input[type=text], input[type=password], input[type=textarea]
        {
            ...
        }
]]></style>

It then defines interactions that are called during the rendering process to make what is essentially a 'div' look like the text input. We use the onFirstDocumentPreRender interaction to instantiate the Flash TextArea (for inputs of type "textarea") or TextInput (for inputs of type "text" or "password") UI component that will actually handle the user input. (Note that "input" in this context is a property of the ContainerInput class.)

@onFirstDocumentPreRender
	{
		input = gA ( "type" ) == "textarea" ? new fl.controls.TextArea ( ) : new fl.controls.TextInput ( );
		if ( gA ( "type" ) == "password" ) input.displayAsPassword = true;
		input.text = node.text ( ).toString ( );
		movie.addChildAt ( input, 0 ); 
		needsRender = true;
	}

Another render process interaction that we add is the onCustomRender interaction. This will be called after dimensions have been calculated for the element and so we can match the UI component's dimensions with those numbers. We also synch the drawing of the UI component with the Frontal render process.

@onCustomRender 
	{ 
		if ( ! isNaN ( width ) ) input.width = width;
		if ( ! isNaN ( width ) ) input.height = height;
		input.drawNow ( ); 
	}

Next, we add some usability interactions. These interactions allow us to define an entry for the text inputs that disappears when you click in the input and reappears if you click out without adding any input.

@onFocusInRaw { if ( input != null && input.text == node.text ( ).toString ( ) ) input.text = ""; }
@onFocusOutRaw { if ( input != null && input.text == "" ) input.text = node.text ( ).toString ( ); }

And finally we add an interaction that is unique to the 'input' tag and that is used to retrieve the value of the input:

@getValue { return input.text; }

Putting it all together then, this is the entire definition for the text-, textarea- and password-type inputs:

<include rel="assets" blocking="true" src="http://www.frontalcode.com/assets/swfs/input_components.swf" />
input[type=text], input[type=password], input[type=textarea]
	{
		@onFirstDocumentPreRender
			{
				input = gA ( "type" ) == "textarea" ? new fl.controls.TextArea ( ) : new fl.controls.TextInput ( );
				if ( gA ( "type" ) == "password" ) input.displayAsPassword = true;
				input.text = node.text ( ).toString ( );
				movie.addChildAt ( input, 0 ); 
				needsRender = true;
			}
		@onCustomRender 
			{ 
				if ( ! isNaN ( width ) ) input.width = width;
				if ( ! isNaN ( width ) ) input.height = height;
				input.drawNow ( ); 
			}
		@onFocusInRaw { if ( input != null && input.text == node.text ( ).toString ( ) ) input.text = ""; }
		@onFocusOutRaw { if ( input != null && input.text == "" ) input.text = node.text ( ).toString ( ); }
		@getValue { return input.text; }
	}

A similar approach is used to implement all of the standard Frontal input types.