textinput.xml

<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="../entries2html.xsl" ?>
<entry name="textinput" namespace="fn" type="widget" widgetnamespace="mobile" event-prefix="textinput" init-selector='"input[type=&#39;text&#39;], input[type=&#39;search&#39;], :jqmData(type=&#39;search&#39;), input[type=&#39;number&#39;], :jqmData(type=&#39;number&#39;), input[type=&#39;password&#39;], input[type=&#39;email&#39;], input[type=&#39;url&#39;], input[type=&#39;tel&#39;], textarea, input[type=&#39;time&#39;], input[type=&#39;date&#39;], input[type=&#39;month&#39;], input[type=&#39;week&#39;], input[type=&#39;datetime&#39;], input[type=&#39;datetime-local&#39;], input[type=&#39;color&#39;], input:not([type]), input[type=&#39;file&#39;]"'>
	<title>Textinput Widget</title>
    <desc>Creates a <placeholder name="name"/> widget for textinput, textarea or search input</desc>
    <longdesc>
		<h2>Text Input</h2>

		<p>Text inputs and textareas are coded with standard HTML elements, then enhanced by jQuery Mobile to make them more attractive and useable on a mobile device.</p>

		<p>To collect standard alphanumeric text, use an <code>input</code> with a <code>type="text"</code> attribute. Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>input</code> so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.</p>

		<xi:include href="../includes/widget-theming.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>

		<ul>
			<li>
				<code>ui-textinput</code>:  The outermost container for textinput. <code>ui-textinput-search</code> or <code>ui-textinput-text</code> classes will be applied if textinput has <code>type='search'</code> or not accordingly. <code>ui-textinput-clear-button</code> class will be applied when <code>clearBtn</code> option is true. <code>ui-textinput-autogrow</code> class will be applied when <code>autogrow</code> option is true.
				<ul>
					<li>
						<code>ui-textinput-search-icon</code>: Search icon's class when type of textinput is search
					</li>
				</ul>
			</li>
		</ul>


<pre><code><![CDATA[
<label for="basic">Text Input:</label>
<input type="text" name="name" id="basic" value="">
]]></code></pre>
		<p>This will produce a basic text input. The default styles set the width of the input to 100% of the parent container and stack the label on a separate line.
		<iframe src="/resources/textinput/example1.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Mini version</h3>

		<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version.</p>

<pre><code><![CDATA[
<label for="basic">Text Input:</label>
<input type="text" name="name" id="basic" value="" data-mini="true">
]]></code></pre>

		<p>This will produce an input that is not as tall as the standard version and has a smaller text size.
		<iframe src="/resources/textinput/example2.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Clear button option</h3>
		<p>The <code>clearButton</code> extension provides the <code>clearBtn</code> option.</p>
		<p>To add a clear button to any input (like the search input), add the <code>data-clear-btn="true"</code> attribute. The text for this clear button can be customized via the <code>data-clear-btn-text="clear input"</code> attribute. Search buttons have the clear button by default and cannot be controlled by this option. Note that this is available for all the input types below except for those coded via <code>textarea</code> elements.</p>

<pre><code><![CDATA[
<label for="clear-demo">Text Input:</label>
<input type="text" name="clear" id="clear-demo" value="" data-clear-btn="true">
]]></code></pre>

		<p>This markup creates a text input with a clear button that becomes visible as soon as a character has been entered.
		<iframe src="/resources/textinput/example7.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Field containers</h3>

		<p>Optionally wrap the text input in a container with class <code>ui-field-contain</code> to help visually group it in a longer form.</p>
		<p class="warning"><strong>Note:</strong> The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</p>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="name">Text Input:</label>
	<input type="text" name="name" id="name" value="">
</div>
]]></code></pre>

		<p>The text input is now displayed like this:
		<iframe src="/resources/textinput/example3.html" style="width:100%;height:90px;border:0px"></iframe></p>

        <h3>More text input types</h3>
		<p>In jQuery Mobile, you can use existing and new HTML5 input types such as <code>password</code>, <code>email</code>, <code>tel</code>, <code>number</code>, and more.  Some type values are rendered differently across browsers. For example, Chrome renders the <code>range</code> input as a slider. jQuery Mobile standardizes the appearance of <code>range</code> and <code>search</code> by dynamically changing their type to <code>text</code>. You can configure which input types are degraded to <code>text</code> with the <code>page</code> plugin's options.</p>

		<p>One major advantage of using these more specific input types if that on mobile devices, specialized keyboards that speed data entry are offered in place of the standard text keyboard. Try the following inputs on a mobile device to see which display custom keyboards on various platforms.
		<iframe src="/resources/textinput/example4.html" style="width:100%;height:730px;border:0px"></iframe></p>

		<h3 id="search-outside-page">Search input outside the page</h3>
		<p>jQuery Mobile-styled <code><placeholder name="name"/></code> widgets can be placed outside jQuery Mobile pages. To do so, specify their input type as <code>type="text"</code>, add the attribute <code>data-type="search"</code>, and manually call the <code><placeholder name="name"/></code> plugin on the element.</p>
		<p>The markup:</p>
<pre><code><![CDATA[
<input id="the-search-input" type="text" data-type="search">
]]></code></pre>
		<p>The script:</p>
<pre><code><![CDATA[
$( function() {
	$( "#the-search-input" ).textinput();
});
]]></code></pre>

        <h2>Textareas</h2>

		<p>For multi-line text inputs, use a <code>textarea</code> element. The <code>autogrow</code> extension provides functionality for auto-growing the height of the textarea to avoid the need for an internal scrollbar. </p>
		<p>Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>textarea</code> so they are semantically associated, and wrap them in a <code>div</code> with class <code>ui-field-contain</code> to group them.</p>
		<p class="warning"><strong>Note:</strong> The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</p>

<pre><code><![CDATA[
<label for="textarea-a">Textarea:</label>
<textarea name="textarea" id="textarea-a">
I'm a basic textarea. If this is pre-populated with content, the height will be automatically adjusted to fit without needing to scroll. That is a pretty handy usability feature.
</textarea>
]]></code></pre>

		<p>This will produce a basic textarea with the width set to 100% of the parent container and the label stacked on a separate line. The textarea will grow to fit new lines as you type:
		<iframe src="/resources/textinput/example5.html" style="width:100%;height:190px;border:0px"></iframe></p>

<pre><code><![CDATA[
<div class="ui-field-contain">
<label for="textarea">Textarea:</label>
	<textarea name="textarea" id="textarea"></textarea>
</div>
]]></code></pre>

		<p>The textarea is displayed like this and will grow to fit new lines as you type:
		<iframe src="/resources/textinput/example6.html" style="width:100%;height:190px;border:0px"></iframe></p>

        <h3>Calling the <placeholder name="name"/> plugin</h3>

		<p>This plugin will auto initialize on any page that contains a textarea or any of the text input types listed above without any need for a <code>data-role</code> attribute in the markup. However, if needed, you can directly call the <code><placeholder name="name"/></code> plugin on any selector, just like any jQuery plugin:</p>
<pre><code><![CDATA[
$( "input" ).textinput();
]]></code></pre>

		<h3>Degraded input types</h3>

		<p class="warning">The location of the map of input type degradations in the page plugin is deprecated as of 1.4.0. As of 1.5.0 the input type degradation functionality will be implemented by the <code>degradeInputs</code> module.</p>

		<p>jQuery Mobile degrades several HTML5 input types back to type=text or type=number after adding enhanced controls. For example, inputs with a type of range are enhanced with a custom slider control, and their type is set to number to offer a usable form input alongside that slider. Inputs with a type of search are degraded back to type=text after we add our own themeable search input styling.</p>
		<p>The <code>degradeInputs</code> module contains a list of input types that are set to either true which means they'll degrade to type=text, false which means they'll be left alone, or a string such as "number", which means they'll be converted to that type (such as the case of type=range).</p>

		<p>You can configure which types are changed via <code>$.mobile.degradeInputs</code>, which has properties: color, date, datetime, "datetime-local", email, month, number, range, search, tel, time, url, and week. Be sure to configure this inside an event handler bound to the <code>mobileinit</code> event, so that it applies to the first page as well as subsequent pages that are loaded.</p>

		<h2>Search Input</h2>
		<p>Search inputs are a new HTML type styled with pill-shaped corners and an "x" icon to clear the field once you start typing. Start with an input with a type="search" attribute in your markup.</p>
		<p>Set the <code>for</code> attribute of the <code>label</code> to match the <code>id</code> of the <code>input</code> so they are semantically associated. It's possible to accessibly hide the label if it's not desired in the page layout, but we require that it is present in the markup for semantic and accessibility reasons.</p>

<pre><code><![CDATA[
<label for="search-basic">Search Input:</label>
<input type="search" name="search" id="search-basic" value="">
]]></code></pre>
		<p>This will produce a basic search input. The default styles set the width of the input to 100% of the parent container and stack the label on a separate line.
		<iframe src="/resources/search-input/example1.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Mini version</h3>

		<p>For a more compact version that is useful in toolbars and tight spaces, add the <code>data-mini="true"</code> attribute to the element to create a mini version.</p>

<pre><code><![CDATA[
<label for="search-mini">Search Input:</label>
<input type="search" name="search-mini" id="search-mini" value="" data-mini="true">
]]></code></pre>

		<p>This will produce a search input that is not as tall as the standard version and has a smaller text size.
		<iframe src="/resources/search-input/example2.html" style="width:100%;height:90px;border:0px"></iframe></p>

		<h3>Field containers</h3>

		<p>Optionally wrap the search input in a container with tlass <code>ui-field-contain</code> to help visually group it in a longer form.</p>
		<p class="warning"><strong>Note:</strong> The <code>data-</code> attribute <code>data-role="fieldcontain"</code> is deprecated as of jQuery Mobile 1.4.0 and will be removed in 1.5.0. Add class <code>ui-field-contain</code> instead.</p>

<pre><code><![CDATA[
<div class="ui-field-contain">
	<label for="search-2">Search Input:</label>
	<input type="search" name="search-2" id="search-2" value="">
</div>
]]></code></pre>

		<p>The search input is now displayed like this:
		<iframe src="/resources/search-input/example3.html" style="width:100%;height:90px;border:0px"></iframe>
		</p>

		<h3>Theming</h3>
		<p>The <code>data-theme</code> attribute can be added to the search input to set the theme to any swatch letter.
		<iframe src="/resources/search-input/example4.html" style="width:100%;height:90px;border:0px"></iframe>
		</p>

		<h3>Setting the clear button text</h3>

		<p>The text for the button used to clear the search input of text can be configured for all search inputs by binding to the <code>mobileinit</code> event and setting the
		<code>$.mobile.textinput.prototype.options.clearBtnText</code> property to a string of your choosing.</p>
		<p>This option is provided by the <code>clearButton</code> extension.</p>

		<h3>Calling the <placeholder name="name"/> plugin</h3>

		<p>This plugin will auto-initialize on any page that contains a text input with the <code>type="search"</code> attribute without any need for a <code>data-role</code> attribute in the markup. However, if needed, you can directly call the <code><placeholder name="name"/></code> plugin on a selector, just like any jQuery plugin:</p>

<pre><code><![CDATA[
$( ".mySearchInput" ).textinput();
]]></code></pre>

		<xi:include href="../includes/pre-rendered-common.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<p>The <placeholder name="name"/> widget wraps <code>input</code>-based widgets in  <code>div</code> used for creating the style. <code>textarea</code> elements are not wrapped in such a <code>div</code>.</p>
		<p>In the example below, we add the attribute <code>data-corners="false"</code> to the input, because the class <code>ui-corner-all</code> is absent from the wrapper, indicating that the value of the "corners" option should be false.</p>
<pre><code><![CDATA[
<label for="pre-rendered-text-field">Pre-rendered input:</label>
<div class="ui-input-text ui-body-inherit ui-shadow-inset">
	<input type="text" data-enhanced="true" data-corners="false" name="pre-rendered-text-field" id="pre-rendered-text-field">
</div>
]]></code></pre>
			<iframe src="/resources/textinput/example8.html" style="width:100%;height:90px;border:0px"></iframe>

	</longdesc>
	<added>1.0</added>
	<options>
		<option name="autogrow" default="true" example-value="false">
			<desc>This option is provided by the <code>autogrow</code> extension.
				<p>Whether to update the size of the <code>textarea</code> element upon first appearance, as well as upon a change in the content of the element.</p>
				<p>This option applies only to <placeholder name="name"/> widgets based on <code>textarea</code> elements.</p>
				<p>This option is also exposed as a data attribute: <code>data-autogrow="false"</code>.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<option name="classes" type="Object">
			<default>{
				"ui-textinput": "ui-corner-all ui-shadow-inset",
				"ui-textinput-search-icon": "ui-icon ui-alt-icon ui-icon-search",
				"ui-textinput-clear-button": "ui-corner-all"
			}</default>
			<xi:include href="../includes/classes-option-desc.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
			<xi:include href="../includes/classes-option-example.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		</option>
		<option name="keyupTimeoutBuffer" default="100" example-value="150">
			<desc>This option is provided by the <code>autogrow</code> extension.
				<p>The amount of time (in milliseconds) to wait between the occurence of a keystroke and the resizing of the <code>textarea</code> element. If another keystroke occurs within this time, the resizing is postponed by another period of time of the same length.</p>
				<p>This option applies only to <placeholder name="name"/> widgets based on <code>textarea</code> elements.</p>
				<p>This option is also exposed as a data attribute: <code>data-keyup-timeout-buffer="150"</code>.</p>
			</desc>
			<type name="Number" />
		</option>
		<option name="clearBtn" default="false" example-value="true">
			<desc>This option is provided by the <code>clearButton</code> extension.
				<p>Adds a clear button to the input when set to <code>true</code>.</p>
				<p>This option applies only to <placeholder name="name"/> widgets based on <code>input</code> elements.</p>
				<p>This option is also exposed as a data attribute: <code>data-clear-btn="true"</code>.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<option name="clearBtnText" default='"Clear text"' example-value='"Clear value"'>
			<desc>This option is provided by the <code>clearButton</code> extension.
				<p>The text description for the optional clear button, useful for assistive technologies like screen readers.</p>
				<p>This option applies only to <placeholder name="name"/> widgets based on <code>input</code> elements.</p>
				<p>This option is also exposed as a data attribute: <code>data-clear-btn-text="Clear value"</code>.</p>
			</desc>
			<type name="String" />
		</option>
		<option name="corners" default="true" example-value="false">
			<desc>Applies the theme border radius if set to <code>true</code> by adding the class <code>ui-corner-all</code> to the <placeholder name="name"/> widget's outermost element.
				<p>This option is also exposed as a data attribute: <code>data-corners="false"</code>.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<xi:include href="../includes/widget-option-defaults.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-disabled.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-enhanced.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-initSelector.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-option-mini.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<option name="preventFocusZoom" default="true on iOS platforms" example-value="true">
			<desc>Attempts to prevent the device from focusing in on the input element when the element receives the focus.
				<p>This option is also exposed as a data attribute: <code>data-prevent-focus-zoom="true"</code>.</p>
			</desc>
			<type name="Boolean" />
		</option>
		<xi:include href="../includes/widget-option-theme.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<option name="wrapperClass" default='""' example-value='"custom-class"'>
			<desc>The value of this option is a string containing a space-separated list of classes to be applied to the outermost element of the <placeholder name="name"/> widget.
				<p>This option is also exposed as a data attribute: <code>data-wrapper-class="true"</code>.</p>
			</desc>
			<type name="String" />
		</option>
	</options>
	<events>
		<xi:include href="../includes/widget-event-create.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
	</events>
	<methods>
		<xi:include href="../includes/widget-method-destroy.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-method-disable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-method-enable.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<xi:include href="../includes/widget-method-option.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/>
		<method name="refresh">
			<desc>Refresh a text input.
				<p>This method is provided by the autogrow extension, and it sets the height of the <code>textarea</code> element based on its contents. You should call this method when the <code>textarea</code> element becomes visible to make sure that its initial height matches its contents.</p>
			</desc>
		</method>
	</methods>
	<example>
		<desc>A basic example of a search input field</desc>
		<html><![CDATA[
<div data-role="page" id="page1">
	<div data-role="header">
		<h1>jQuery Mobile Example</h1>
	</div>
	<div role="main" class="ui-content">
		<label for="basic">Text Input:</label>
		<input type="text" name="name" id="basic" value="">
	</div>
</div>
]]></html>
	</example>
	<example>
		<desc>A basic example of a search input field</desc>
		<html><![CDATA[
<div data-role="page" id="page1">
	<div data-role="header">
		<h1>jQuery Mobile Example</h1>
	</div>
	<div role="main" class="ui-content">
		<label for="search-basic">Search Input:</label>
		<input type="search" name="search" id="search-basic" value="">
	</div>
</div>
]]></html>
	</example>
	<category slug="widgets"/>
</entry>