From 242721312737eaf294cb534b7178fea4b5723406 Mon Sep 17 00:00:00 2001 From: Rami Yushuvaev Date: Tue, 4 Jul 2023 01:40:16 +0300 Subject: [PATCH 1/5] HTML `` element --- files/en-us/web/html/element/index.md | 1 + files/en-us/web/html/element/search/index.md | 161 +++++++++++++++++++ files/en-us/web/html/index.md | 2 +- 3 files changed, 163 insertions(+), 1 deletion(-) create mode 100644 files/en-us/web/html/element/search/index.md diff --git a/files/en-us/web/html/element/index.md b/files/en-us/web/html/element/index.md index e5382d0086790a5..aff868a92ff9609 100644 --- a/files/en-us/web/html/element/index.md +++ b/files/en-us/web/html/element/index.md @@ -53,6 +53,7 @@ Content sectioning elements allow you to organize the document content into logi | {{HTMLElement("main")}} | Represents the dominant content of the body of a document. The main content area consists of content that is directly related to or expands upon the central topic of a document, or the central functionality of an application. | | {{HTMLElement("nav")}} | Represents a section of a page whose purpose is to provide navigation links, either within the current document or to other documents. Common examples of navigation sections are menus, tables of contents, and indexes. | | {{HTMLElement("section")}} | Represents a generic standalone section of a document, which doesn't have a more specific semantic element to represent it. Sections should always have a heading, with very few exceptions. | +| {{HTMLElement("search")}} | Represents a part that contains a set of form controls or other content related to performing a search or filtering operation. | ## Text content diff --git a/files/en-us/web/html/element/search/index.md b/files/en-us/web/html/element/search/index.md new file mode 100644 index 000000000000000..b9d72790eaa1772 --- /dev/null +++ b/files/en-us/web/html/element/search/index.md @@ -0,0 +1,161 @@ +--- +title: ": The Generic search element" +slug: Web/HTML/Element/search +page-type: html-element +browser-compat: html.elements.search +--- + +{{HTMLSidebar}} + +The **``** [HTML](/en-US/docs/Web/HTML) element represents a part 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. + +## Attributes + +This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_attributes). + +## Usage notes + +It's not appropriate to use the `` 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. + +## Examples + +### Header search form + +Include a search form within a website header to perform a simple site-wide search. + +```html +
+

Movies website

+ +
+ + + +
+ +
+``` + +### Result + +{{EmbedLiveSample('Header search form')}} + +### Web app search + +JavaScript search functionality in a web application. No form element to perform a server-side submission, but for semantics a search element represents search and filtering capabilities. + +```html + + + + +
+

Results:

+
    + +
+ + + +
+ +``` + +### Result + +{{EmbedLiveSample('Web app search')}} + +### Multiple searches + +A page with two search features. The first is a global site search located on the header. The second is a search and filter based on the page context, in our example a car search. + +```html + +
+

Car rental agency

+ + ... + +
+
+

Cars available for rent

+ +

Filter results

+ ... + +
+ +
+
+ +``` + +### Result + +{{EmbedLiveSample('Multiple searches')}} + +## Technical summary + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Content categories + + Flow content, + palpable content. +
Permitted content + Flow content. +
Tag omission{{no_tag_omission}}
Implicit ARIA role + search +
Permitted ARIA roles + form, + group, + none, + presentation, + region, + search +
DOM interface{{domxref("HTMLElement")}}
+ +## Specifications + +{{Specifications}} + +## Browser compatibility + +{{Compat}} + +## See also + +- Other search-related elements: {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("aside")}}, {{HTMLElement("nav")}}, {{HTMLElement("form")}} +- [ARIA: Search role](/en-US/docs/Web/Accessibility/ARIA/Roles/search_role) diff --git a/files/en-us/web/html/index.md b/files/en-us/web/html/index.md index 841f1584d4358dd..b5da77bfce24891 100644 --- a/files/en-us/web/html/index.md +++ b/files/en-us/web/html/index.md @@ -10,7 +10,7 @@ page-type: landing-page "Hypertext" refers to links that connect web pages to one another, either within a single website or between websites. Links are a fundamental aspect of the Web. By uploading content to the Internet and linking it to pages created by other people, you become an active participant in the World Wide Web. -HTML uses "markup" to annotate text, images, and other content for display in a Web browser. HTML markup includes special "elements" such as {{HTMLElement("head")}}, {{HTMLElement("title")}}, {{HTMLElement("body")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("p")}}, {{HTMLElement("div")}}, {{HTMLElement("span")}}, {{HTMLElement("img")}}, {{HTMLElement("aside")}}, {{HTMLElement("audio")}}, {{HTMLElement("canvas")}}, {{HTMLElement("datalist")}}, {{HTMLElement("details")}}, {{HTMLElement("embed")}}, {{HTMLElement("nav")}}, {{HTMLElement("output")}}, {{HTMLElement("progress")}}, {{HTMLElement("video")}}, {{HTMLElement("ul")}}, {{HTMLElement("ol")}}, {{HTMLElement("li")}} and many others. +HTML uses "markup" to annotate text, images, and other content for display in a Web browser. HTML markup includes special "elements" such as {{HTMLElement("head")}}, {{HTMLElement("title")}}, {{HTMLElement("body")}}, {{HTMLElement("header")}}, {{HTMLElement("footer")}}, {{HTMLElement("article")}}, {{HTMLElement("section")}}, {{HTMLElement("p")}}, {{HTMLElement("div")}}, {{HTMLElement("span")}}, {{HTMLElement("img")}}, {{HTMLElement("aside")}}, {{HTMLElement("audio")}}, {{HTMLElement("canvas")}}, {{HTMLElement("datalist")}}, {{HTMLElement("details")}}, {{HTMLElement("embed")}}, {{HTMLElement("nav")}}, {{HTMLElement("search")}}, {{HTMLElement("output")}}, {{HTMLElement("progress")}}, {{HTMLElement("video")}}, {{HTMLElement("ul")}}, {{HTMLElement("ol")}}, {{HTMLElement("li")}} and many others. An HTML element is set off from other text in a document by "tags", which consist of the element name surrounded by "`<`" and "`>`". The name of an element inside a tag is case-insensitive. That is, it can be written in uppercase, lowercase, or a mixture. For example, the `` tag can be written as `<Title>`, `<TITLE>`, or in any other way. However, the convention and recommended practice is to write tags in lowercase. From 1c32564179a4ce140178ab9c395a1aec921aa925 Mon Sep 17 00:00:00 2001 From: Rami Yushuvaev <r_a_m_i@hotmail.com> Date: Tue, 4 Jul 2023 01:49:04 +0300 Subject: [PATCH 2/5] Fix lint issues --- files/en-us/web/html/element/search/index.md | 12 +++--------- 1 file changed, 3 insertions(+), 9 deletions(-) diff --git a/files/en-us/web/html/element/search/index.md b/files/en-us/web/html/element/search/index.md index b9d72790eaa1772..8ff12a741d83dc6 100644 --- a/files/en-us/web/html/element/search/index.md +++ b/files/en-us/web/html/element/search/index.md @@ -7,7 +7,7 @@ browser-compat: html.elements.search {{HTMLSidebar}} -The **`<search>`** [HTML](/en-US/docs/Web/HTML) element represents a part 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. +The **`<search>`** [HTML](/en-US/docs/Web/HTML) element represents a part 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 website or application, a way of searching or filtering search results on the current web page, or a global or internet-wide search function. ## Attributes @@ -109,8 +109,7 @@ A page with two search features. The first is a global site search located on th <a href="/en-US/docs/Web/HTML/Content_categories">Content categories</a> </th> <td> - <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, - <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content">palpable content</a>. + <a href="/en-US/docs/Web/HTML/Content_categories#flow_content">Flow content</a>, <a href="/en-US/docs/Web/HTML/Content_categories#palpable_content">palpable content</a>. </td> </tr> <tr> @@ -132,12 +131,7 @@ A page with two search features. The first is a global site search located on th <tr> <th scope="row">Permitted ARIA roles</th> <td> - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/form_role"><code>form</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/region_role"><code>region</code></a>, - <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/search_role"><code>search</code></a> + <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/form_role"><code>form</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/group_role"><code>group</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/none_role"><code>none</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/presentation_role"><code>presentation</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/region_role"><code>region</code></a>, <a href="/en-US/docs/Web/Accessibility/ARIA/Roles/search_role"><code>search</code></a> </td> </tr> <tr> From ef43dacf74c15b38fd13c26891991ae9ff81b24f Mon Sep 17 00:00:00 2001 From: Rami Yushuvaev <r_a_m_i@hotmail.com> Date: Sat, 8 Jul 2023 10:55:47 +0300 Subject: [PATCH 3/5] Apply suggestions from code review Co-authored-by: Estelle Weyl <estelle@openwebdocs.org> --- files/en-us/web/html/element/search/index.md | 24 +++++++++++--------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/files/en-us/web/html/element/search/index.md b/files/en-us/web/html/element/search/index.md index 8ff12a741d83dc6..9dbe1200870e013 100644 --- a/files/en-us/web/html/element/search/index.md +++ b/files/en-us/web/html/element/search/index.md @@ -1,5 +1,5 @@ --- -title: "<search>: The Generic search element" +title: "<search>: The generic search element" slug: Web/HTML/Element/search page-type: html-element browser-compat: html.elements.search @@ -7,7 +7,7 @@ browser-compat: html.elements.search {{HTMLSidebar}} -The **`<search>`** [HTML](/en-US/docs/Web/HTML) element represents a part 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 website or application, a way of searching or filtering search results on the current web page, or a global or internet-wide search function. +The **`<search>`** [HTML](/en-US/docs/Web/HTML) element is a container representing the parts of the document or application with form controls or other content related to performing a search or filtering operation. The `<search>` element semantically identifies the purpose of the element's contents as having search or filtering capabilities. The search or filtering functionality can be for the website or application, the current web page or document, or the entire Internet or subsection thereof. ## Attributes @@ -15,34 +15,34 @@ This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_a ## Usage notes -It's not appropriate to use the `<search>` 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. +The `<search>` element is not for presenting search results. Rather, search or filtered results should be presented as part of the main content of that web page. That said, suggestions and links that are part of "quick search" functionality within the search or filtering functionality are appropriately nested within the contents of the `<search>` element as they are search features. ## Examples ### Header search form -Include a search form within a website header to perform a simple site-wide search. +This example demonstrates the use of `<search>` as the container for a search within a website header to perform a simple site-wide search. The `<search>` is a semantic container for the {{HTMLElement("form")}} that submits the user-entered search query to a server. ```html <header> - <h1>Movies website</h1> + <h1>Movie website</h1> <search> <form action="./search/"> <label for="movie">Find a Movie</label> - <input type="search" id="movie" name="q"> + <input type="search" id="movie" name="q" /> <button type="submit">Search</button> </form> </search> </header> ``` -### Result +#### Result {{EmbedLiveSample('Header search form')}} ### Web app search -JavaScript search functionality in a web application. No form element to perform a server-side submission, but for semantics a search element represents search and filtering capabilities. +This example demonstrates potential DOM content when dynamically including JavaScript search functionality in a web application. When search functionality is implemented entirely with JavaScript, if no form is submitted, neither a {{HTMLElement("form")}} element nor a submit {{HTMLElement("button")}} is required. For semantics, the `<search>` element is included to contain the search and filtering capabilities. ```html <search> @@ -67,13 +67,15 @@ JavaScript search functionality in a web application. No form element to perform </search> ``` -### Result +#### Result {{EmbedLiveSample('Web app search')}} +> **Note:** Remember that some users don't have JavaScript, and none of your users have JavaScript running until the JavaScript is successfully downloaded, parsed, and executed, ensure your users can access the content of your site with JavaScript disabled. + ### Multiple searches -A page with two search features. The first is a global site search located on the header. The second is a search and filter based on the page context, in our example a car search. +This example demonstrates a page with two search features. The first is a global site search located on the header. The second is a search and filter based on the page context, in our example a car search. ```html <body> @@ -96,7 +98,7 @@ A page with two search features. The first is a global site search located on th </body> ``` -### Result +#### Result {{EmbedLiveSample('Multiple searches')}} From 056ad42c9c711450757ef952ab88bc4dcf519988 Mon Sep 17 00:00:00 2001 From: Rami Yushuvaev <r_a_m_i@hotmail.com> Date: Sat, 8 Jul 2023 10:59:10 +0300 Subject: [PATCH 4/5] lint --- files/en-us/web/html/element/search/index.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/files/en-us/web/html/element/search/index.md b/files/en-us/web/html/element/search/index.md index 9dbe1200870e013..38a03445e20d472 100644 --- a/files/en-us/web/html/element/search/index.md +++ b/files/en-us/web/html/element/search/index.md @@ -7,7 +7,7 @@ browser-compat: html.elements.search {{HTMLSidebar}} -The **`<search>`** [HTML](/en-US/docs/Web/HTML) element is a container representing the parts of the document or application with form controls or other content related to performing a search or filtering operation. The `<search>` element semantically identifies the purpose of the element's contents as having search or filtering capabilities. The search or filtering functionality can be for the website or application, the current web page or document, or the entire Internet or subsection thereof. +The **`<search>`** [HTML](/en-US/docs/Web/HTML) element is a container representing the parts of the document or application with form controls or other content related to performing a search or filtering operation. The `<search>` element semantically identifies the purpose of the element's contents as having search or filtering capabilities. The search or filtering functionality can be for the website or application, the current web page or document, or the entire Internet or subsection thereof. ## Attributes @@ -15,7 +15,7 @@ This element only includes the [global attributes](/en-US/docs/Web/HTML/Global_a ## Usage notes -The `<search>` element is not for presenting search results. Rather, search or filtered results should be presented as part of the main content of that web page. That said, suggestions and links that are part of "quick search" functionality within the search or filtering functionality are appropriately nested within the contents of the `<search>` element as they are search features. +The `<search>` element is not for presenting search results. Rather, search or filtered results should be presented as part of the main content of that web page. That said, suggestions and links that are part of "quick search" functionality within the search or filtering functionality are appropriately nested within the contents of the `<search>` element as they are search features. ## Examples @@ -23,6 +23,8 @@ The `<search>` element is not for presenting search results. Rather, search or f This example demonstrates the use of `<search>` as the container for a search within a website header to perform a simple site-wide search. The `<search>` is a semantic container for the {{HTMLElement("form")}} that submits the user-entered search query to a server. +#### HMTL + ```html <header> <h1>Movie website</h1> @@ -44,6 +46,8 @@ This example demonstrates the use of `<search>` as the container for a search wi This example demonstrates potential DOM content when dynamically including JavaScript search functionality in a web application. When search functionality is implemented entirely with JavaScript, if no form is submitted, neither a {{HTMLElement("form")}} element nor a submit {{HTMLElement("button")}} is required. For semantics, the `<search>` element is included to contain the search and filtering capabilities. +#### HMTL + ```html <search> <label> @@ -77,6 +81,8 @@ This example demonstrates potential DOM content when dynamically including JavaS This example demonstrates a page with two search features. The first is a global site search located on the header. The second is a search and filter based on the page context, in our example a car search. +#### HMTL + ```html <body> <header> From 45769cd9aa845112d7ee14c84e81982597148e6d Mon Sep 17 00:00:00 2001 From: Estelle Weyl <estelle@openwebdocs.org> Date: Sun, 9 Jul 2023 18:33:25 -0700 Subject: [PATCH 5/5] ran prettier --- files/en-us/web/html/element/search/index.md | 18 ++++++++---------- 1 file changed, 8 insertions(+), 10 deletions(-) diff --git a/files/en-us/web/html/element/search/index.md b/files/en-us/web/html/element/search/index.md index 38a03445e20d472..ebda3ad7343240a 100644 --- a/files/en-us/web/html/element/search/index.md +++ b/files/en-us/web/html/element/search/index.md @@ -52,10 +52,10 @@ This example demonstrates potential DOM content when dynamically including JavaS <search> <label> Find and filter your query - <input type="search" id="query"> + <input type="search" id="query" /> </label> <label> - <input type="checkbox" id="exact-only"> + <input type="checkbox" id="exact-only" /> Exact matches only </label> @@ -87,17 +87,15 @@ This example demonstrates a page with two search features. The first is a global <body> <header> <h1>Car rental agency</h1> - <search title="Website"> - ... - </search> + <search title="Website"> ... </search> </header> <main> <h2>Cars available for rent</h2> - <search title="Cars"> - <h3>Filter results</h3> - ... - </search> - <article> + <search title="Cars"> + <h3>Filter results</h3> + ... + </search> + <article> <!-- search result content --> </article> </main>