Skip to content

Commit

Permalink
Add "The search element" section
Browse files Browse the repository at this point in the history 
Defines:
- attr-aria-role-search

Credit for the explainer and examples:
@scottaohara
  • Loading branch information
@Kaleidea
Kaleidea committed Dec 1, 2021
1 parent 51bd17e commit ffb1210
Showing 1 changed file with 177 additions and 14 deletions.
191 changes: 177 additions & 14 deletions source
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3922,6 +3922,7 @@ a.setAttribute('href', 'https://example.com/'); // change the content attribute
<ul class="brief">
<li><dfn data-x-href="https://w3c.github.io/aria/#button"><code data-x="attr-aria-role-button">button</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/aria/#presentation"><code data-x="attr-aria-role-presentation">presentation</code></dfn></li>
<li><dfn data-x-href="https://w3c.github.io/aria/#search"><code data-x="attr-aria-role-search">search</code></dfn></li>
</ul>

<p>In addition, the following <dfn><code data-x="attr-aria-*">aria-*</code></dfn> content
Expand Down Expand Up @@ -42727,6 +42728,8 @@ interface <dfn interface>HTMLTableCellElement</dfn> : <span>HTMLElement</span> {

<h4>Introduction</h4>

<p>A <dfn data-x="concept-form">form</dfn> is either a <code>form</code> or a <code>search</code> element.</p>

<!-- NON-NORMATIVE SECTION -->

<p>A form is a component of a web page that groups form controls, such as text, buttons,
Expand All @@ -42748,7 +42751,9 @@ interface <dfn interface>HTMLTableCellElement</dfn> : <span>HTMLElement</span> {

<p>For the purposes of this brief introduction, we will create a pizza ordering form.</p>

<p>Any form starts with a <code>form</code> element, inside which are placed the controls. Most
<p>Any <span data-x="concept-form">form</span>
starts with a <code>form</code> or <code>search</code> element,
which then contains among others <span>form-associated element</span>s. Most
controls are represented by the <code>input</code> element, which by default provides a text
control. To label a control, the <code>label</code> element is used; the label text and the
control itself go inside the <code>label</code> element. Each part of a form is considered a
Expand Down Expand Up @@ -43419,9 +43424,11 @@ interface <dfn interface>HTMLTableCellElement</dfn> : <span>HTMLElement</span> {
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected.</dd>
<dd>Where <span>flow content</span> is expected, but not as a descendant of
another <code>form</code> or <code>search</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>form</code> element descendants.</dd>
<dd><span>Flow content</span>, but with no <code>form</code> or <code>search</code> element
descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><code data-x="attr-form-accept-charset">accept-charset</code></dd>
Expand Down Expand Up @@ -43487,8 +43494,8 @@ interface <dfn interface>HTMLFormElement</dfn> : <span>HTMLElement</span> {
represents the <span data-x="concept-form">form</span>'s
name within the <code data-x="dom-document-forms">forms</code>
collection. The value must not be the empty string, and the value must be unique amongst the
<code>form</code> elements in the <code data-x="dom-document-forms">forms</code> collection that
it is in, if any.</p>
<code>form</code> and <code>search</code> elements in the
<code data-x="dom-document-forms">forms</code> collection that it is in, if any.</p>

<p>The <dfn element-attr for="form"><code
data-x="attr-form-autocomplete">autocomplete</code></dfn> attribute is an <span>enumerated
Expand Down Expand Up @@ -43873,6 +43880,132 @@ interface <dfn interface>HTMLFormElement</dfn> : <span>HTMLElement</span> {



<h4>The <dfn element><code>search</code></dfn> element</h4>

<dl class="element">
<dt><span data-x="concept-element-categories">Categories</span>:</dt>
<dd><span>Flow content</span>.</dd>
<dd><span>Palpable content</span>.</dd>
<dt><span data-x="concept-element-contexts">Contexts in which this element can be used</span>:</dt>
<dd>Where <span>flow content</span> is expected, but not as a descendant of
another <code>form</code> or <code>search</code> element.</dd>
<dt><span data-x="concept-element-content-model">Content model</span>:</dt>
<dd><span>Flow content</span>, but with no <code>form</code> or <code>search</code> element
descendants.</dd>
<dt><span data-x="concept-element-attributes">Content attributes</span>:</dt>
<dd><span>Global attributes</span></dd>
<dd><span data-x="form">form attributes</span></dd>
<dd><code data-x="attr-search-action">action</code> — URL to use for
<span>form submission</span> or unspecified to disable <span>form submission</span></dd>
<dt><span
data-x="concept-element-accessibility-considerations">Accessibility considerations</span>:</dt>
<dd><a href="https://w3c.github.io/html-aria/#el-search">For authors</a>.</dd>
<dd><a href="https://w3c.github.io/html-aam/#el-search">For implementers</a>.</dd>
<dt><span data-x="concept-element-dom">DOM interface</span>:</dt>
<dd>Uses <code>HTMLFormElement</code>, as defined for <code>form</code> elements.</dd>
</dl>

<p>The <code>search</code> element <span>represents</span> a part of a document or application
that contains a set of form controls or other content related to performing a search or filtering
operation. This could be a search of the web site or application; a way of searching or filtering
search results on the current web page; or a global or Internet-wide search function.</p>

<p>The <code>search</code> element is almost identical to the <code>form</code>
element with the following differences:</p>

<ol>
<li><p>If the <code data-x="attr-search-action">action</code> attribute is unspecified then
<span>form submission</span> is disabled, only the
<code data-x="event-submit">submit event</code> is fired.</p></li>
<li><p>The <code>search</code> element has the <code data-x="attr-aria-role-search">search</code>
<code data-x="attr-aria-role">role</code>, screen readers announce it as the "search landmark" when focus navigates into it.</p></li>
</ol>

<p class="note">It's not appropriate to use the <code>search</code> element just for presenting
search results, though suggestions and links as part of "quick search" results can be
included as part of a search feature. Rather, a returned web page of search results would instead
be expected to be presented as part of the main content of that web page.</p>

<div class="example">
<p>In the following example, the author is including a search form within the
<code>header</code> of the web page:</p>

<pre><code class="html">&lt;header>
&lt;h1>&lt;a href="/">My fancy blog&lt;/a>&lt;/h1>
...
&lt;search action="search.php">
&lt;label for="query">Find an article&lt;/label>
&lt;input id="query" name="q" type="search">
&lt;button type="submit">Go!&lt;/button>
&lt;/search>
&lt;/header></code></pre>
</div>

<div class="example">
<p>In this example, the author has implemented their web application's search functionality
entirely with JavaScript. There is no use of the <code data-x="attr-search-action">action</code> attribute to perform
server-side submission. The containing <code>search</code> element semantically identifies
the purpose of the descendant content as representing search capabilities.</p>

<pre><code class="html">&lt;search>
&lt;label>
Find and filter your query
&lt;input type="search" id="query">
&lt;/label>
&lt;label>
&lt;input type="checkbox" id="exact-only">
Exact matches only
&lt;/label>

&lt;section>
&lt;h3>Results found:&lt;/h3>
&lt;ul id="results">
&lt;li>
&lt;p>&lt;a href="services/consulting">Consulting services&lt;/a>&lt;/p>
&lt;p>
Find out how we can help you improve your business with our integrated consultants, Bob and Rob.
&lt;/p>
&lt;/li>
...
&lt;/ul>
&lt;!--
when a query returns or filters out all results
render the no results message here
-->
&lt;output id="no-results">&lt;/output>
&lt;/section>
&lt;/search></code></pre>
</div>

<div class="example">
<p>In the following example, the page has two search features. The first is located in the
web page's <code>header</code> and serves as a global mechanism to search the web site's
content. Its purpose is indicated by its specified <code>title</code> attribute. The results
are presented on a new page at the URL set by the <code data-x="attr-search-action">action</code>
attribute. The second search is included as part of the main content of the page, as it
represents a mechanism to search and filter the content of the current page without loading a
new page. It contains a heading to indicate its purpose.</p>

<pre><code class="html">&lt;body>
&lt;header>
...
&lt;search title="Website" action="/search">
...
&lt;/search>
&lt;/header>
&lt;main>
&lt;h1>Hotels near your location&lt;/h1>
&lt;search>
&lt;h2>Filter results&lt;/h2>
...
&lt;/search>
&lt;article>
&lt;!-- search result content -->
&lt;/article>
&lt;/main>
&lt;/body></code></pre>
</div>

<h4>The <dfn element><code>label</code></dfn> element</h4>

<dl class="element">
Expand Down Expand Up @@ -53694,9 +53827,15 @@ form.method === input; // => true</code></pre>

<p>The <dfn element-attr for="form,button"><code data-x="attr-fs-action">action</code></dfn> and
<dfn element-attr for="form,button"><code data-x="attr-fs-formaction">formaction</code></dfn>
content attributes, if specified, must have a value that is a <span>valid non-empty URL
content attributes of a <code>form</code> or <code>button</code>, if specified,
must have a value that is a <span>valid non-empty URL
potentially surrounded by spaces</span>.</p>

<p>The <dfn element-attr for="search"><code data-x="attr-search-action">action</code></dfn>
content attribute of a <code>search</code> element, if specified,
must have a value that is a <span>valid URL potentially surrounded by spaces</span>.<br>
If not specified, the <code>search</code> element disables <span>form submission</span>.</p>

<p>The <dfn data-x="concept-fs-action">action</dfn> of an element is the value of the element's
<code data-x="attr-fs-formaction">formaction</code> attribute, if the element is a <span
data-x="concept-submit-button">submit button</span> and has such an attribute, or the value of its
Expand Down Expand Up @@ -123065,6 +123204,19 @@ interface <dfn interface>External</dfn> {
<td><code>HTMLScriptElement</code></td>
</tr>

<tr>
<th><code>search</code></th>
<td>Form container for search controls, optionally user-submittable </td>
<td><span data-x="Flow content">flow</span>;
<span data-x="Palpable content">palpable</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="Flow content">flow</span></td>
<td><span data-x="global attributes">globals</span>;
<span data-x="form">form attributes</span>;
<code data-x="attr-search-action">action</code>;
<td><code>HTMLFormElement</code></td>
</tr>

<tr>
<th><code>section</code></th>
<td>Generic document or application section</td>
Expand Down Expand Up @@ -123967,9 +124119,10 @@ interface <dfn interface>External</dfn> {
<td> <span>Ordered set of unique space-separated tokens</span>, none of which are <span>identical to</span> another, each consisting of one code point in length
<tr>
<th> <code data-x="">action</code>
<td> <code data-x="attr-fs-action">form</code>
<td> <code data-x="attr-fs-action">form</code>;
<code data-x="attr-search-action">search</code>
<td> <span>URL</span> to use for <span>form submission</span>
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>
<td> <span>Valid non-empty URL potentially surrounded by spaces</span>, can be empty for <code data-x="">search</code> element
<tr>
<th> <code data-x="">allow</code>
<td> <code data-x="attr-iframe-allow">iframe</code>
Expand Down Expand Up @@ -124009,7 +124162,8 @@ interface <dfn interface>External</dfn> {
"<code data-x="attr-autocapitalize-characters">characters</code>"
<tr>
<th> <code data-x="">autocomplete</code>
<td> <code data-x="attr-form-autocomplete">form</code>
<td> <code data-x="attr-form-autocomplete">form</code>;
<code data-x="attr-form-autocomplete">search</code>
<td> Default setting for autofill feature for controls in the form
<td> "<code data-x="">on</code>"; "<code data-x="">off</code>"
<tr>
Expand Down Expand Up @@ -124191,7 +124345,8 @@ interface <dfn interface>External</dfn> {
<td> "<code data-x="">true</code>"; "<code data-x="">false</code>"
<tr>
<th> <code data-x="">enctype</code>
<td> <code data-x="attr-fs-enctype">form</code>
<td> <code data-x="attr-fs-enctype">form</code>;
<code data-x="attr-fs-enctype">search</code>
<td> <span>Entry list</span> encoding type to use for <span>form submission</span>
<td> "<code data-x="attr-fs-enctype-urlencoded">application/x-www-form-urlencoded</code>"; "<code data-x="attr-fs-enctype-formdata">multipart/form-data</code>"; "<code data-x="attr-fs-enctype-text">text/plain</code>"
<tr>
Expand Down Expand Up @@ -124457,7 +124612,8 @@ interface <dfn interface>External</dfn> {
<td> <span>Valid media query list</span>
<tr>
<th> <code data-x="">method</code>
<td> <code data-x="attr-fs-method">form</code>
<td> <code data-x="attr-fs-method">form</code>;
<code data-x="attr-fs-method">search</code>
<td> Variant to use for <span>form submission</span>
<td> "<code data-x="attr-fs-method-GET-keyword">GET</code>";
"<code data-x="attr-fs-method-POST-keyword">POST</code>";
Expand Down Expand Up @@ -124503,7 +124659,8 @@ interface <dfn interface>External</dfn> {
<td> <a href="#attribute-text">Text</a>*
<tr>
<th> <code data-x="">name</code>
<td> <code data-x="attr-form-name">form</code>
<td> <code data-x="attr-form-name">form</code>;
<code data-x="attr-form-name">search</code>
<td> Name of form to use in the <code data-x="dom-document-forms">document.forms</code> API
<td> <a href="#attribute-text">Text</a>*
<tr>
Expand Down Expand Up @@ -124544,7 +124701,8 @@ interface <dfn interface>External</dfn> {
<td> <a href="#attribute-text">Text</a>
<tr>
<th> <code data-x="">novalidate</code>
<td> <code data-x="attr-fs-novalidate">form</code>
<td> <code data-x="attr-fs-novalidate">form</code>;
<code data-x="attr-fs-novalidate">search</code>
<td> Bypass form control validation for <span>form submission</span>
<td> <span>Boolean attribute</span>
<tr>
Expand Down Expand Up @@ -124784,7 +124942,8 @@ interface <dfn interface>External</dfn> {
<td> <span>Valid browsing context name or keyword</span>
<tr>
<th> <code data-x="">target</code>
<td> <code data-x="attr-fs-target">form</code>
<td> <code data-x="attr-fs-target">form</code>;
<code data-x="attr-fs-target">search</code>
<td> <span>Browsing context</span> for <span>form submission</span>
<td> <span>Valid browsing context name or keyword</span>
<tr>
Expand Down Expand Up @@ -125768,6 +125927,10 @@ interface <dfn interface>External</dfn> {
<td> <code>samp</code>
<td> <code>HTMLElement</code>

<tr>
<td> <code>search</code>
<td> <code>HTMLFormElement</code>

<tr>
<td> <code>script</code>
<td> <code>HTMLScriptElement</code> : <code>HTMLElement</code>
Expand Down

0 comments on commit ffb1210

Please sign in to comment.