Adding search.query and search.search disposition (#24668)

* Adding search.query and search.search disposition * Default behavior correction * Review feedback Co-authored-by: Gregory Pappas <email.greg.email@gmail.com> * Removed bug macros * Advice on use of query versus search * Incorporate suggested change Co-authored-by: Rob Wu <rob@robwu.nl> --------- Co-authored-by: Gregory Pappas <email.greg.email@gmail.com> Co-authored-by: Rob Wu <rob@robwu.nl>
mdn · Mar 3, 2023 · ad20678 · ad20678
1 parent e6c5ee0
commit ad20678
Show file tree

Hide file tree

Showing 4 changed files with 124 additions and 18 deletions.
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/search/index.md b/files/en-us/mozilla/add-ons/webextensions/api/search/index.md
@@ -15,19 +15,26 @@ browser-compat: webextensions.api.search
 
 {{AddonSidebar}}
 
-Retrieves search engines and executes a search with a specific search engine.
+Use the search API to retrieve the installed search engines and execute searches.
 
 To use this API you need to have the `"search"` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
 
+When choosing between `search.query()` and `search.search()`, consider the following:
+
+- {{WebExtAPIRef("search.search()")}} is available on all the main browser engines and, therefore, is ideal for use in cross-browser extensions. However, it can only issue searches against the browser's default search engine.
+- {{WebExtAPIRef("search.query()")}} is available only on Firefox. However, it has the advantage of enabling you to issue a search against any search engines installed in the browser.
+
 ## Functions
 
 - {{WebExtAPIRef("search.get()")}}
   - : Retrieve all search engines.
+- {{WebExtAPIRef("search.query()")}}
+  - : Search using the browser's default search engine.
 - {{WebExtAPIRef("search.search()")}}
-  - : Search using the specified search engine.
-
-## Browser compatibility
+  - : Search using a specified search engine.
 
 {{WebExtExamples("h2")}}
 
+## Browser compatibility
+
 {{Compat}}
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/search/query/index.md b/files/en-us/mozilla/add-ons/webextensions/api/search/query/index.md
@@ -0,0 +1,94 @@
+---
+title: search.query()
+slug: Mozilla/Add-ons/WebExtensions/API/search/query
+tags:
+  - API
+  - Add-ons
+  - Extensions
+  - Reference
+  - Search
+  - Search Engines
+  - WebExtensions
+browser-compat: webextensions.api.search.query
+---
+
+{{AddonSidebar()}}
+
+Perform a search using the browser's default search engine.
+
+The results are displayed in the current tab, a new tab, or a new window according to the `disposition` property or in the tab specified in the `tabId` property. If neither is specified, the results display in a new tab.
+
+To use this function, your extension must have the `"search"` [manifest permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
+
+To get the installed search engines, use {{WebExtAPIRef("search.get()")}}.
+
+## Syntax
+
+```js-nolint
+browser.search.query(
+  queryInfo             // object
+)
+```
+
+### Parameters
+
+- `queryInfo`
+
+  - : `object`. An object with the following properties:
+
+    - `disposition` {{optional_inline}}
+      - : `string`. The location where the search results are displayed. Valid values are `CURRENT_TAB`, `NEW_TAB`, and `NEW_WINDOW`. Defaults to `NEW_TAB`. Cannot be specified with `tabId`.
+    - `tabId` {{optional_inline}}
+      - : `integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted, the search results are displayed in a new tab. Cannot be specified with `disposition`.
+    - `text`
+      - : `string`. The search query.
+
+### Return value
+
+None.
+
+## Examples
+
+A search with the results shown in the current tab (default):
+
+```js
+function search() {
+  browser.search.query({
+    text: "styracosaurus"
+  });
+}
+
+browser.browserAction.onClicked.addListener(search);
+```
+
+A search with the results shown in a new window:
+
+```js
+function search() {
+  browser.search.query({
+    text: "styracosaurus",
+    disposition: "NEW_WINDOW"
+  });
+}
+
+browser.browserAction.onClicked.addListener(search);
+```
+
+A search with the results shown in the current tab:
+
+```js
+function search(tab) {
+  browser.search.query({
+    query: "styracosaurus",
+    tabId: tab.id
+  });
+}
+
+browser.browserAction.onClicked.addListener(search);
+```
+
+{{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/search/search/index.md b/files/en-us/mozilla/add-ons/webextensions/api/search/search/index.md
@@ -15,11 +15,11 @@ browser-compat: webextensions.api.search.search
 
 {{AddonSidebar()}}
 
-Perform a search using the search engine specified, or the default search engine if no search engine is specified.
+Perform a search using the search engine specified or the default search engine if no search engine is specified.
 
-The results will be displayed in a new tab, or if the `tabId` argument is given, in the tab identified by this.
+The results are displayed in the current tab, a new tab, or a new window according to the `disposition` property or in the tab specified in the `tabId` property. If neither is specified, the results display in a new tab.
 
-To use this function in your extension you must ask for the `"search"` [manifest permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
+To use this function, your extension must have the `"search"` [manifest permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions).
 
 To get the installed search engines, use {{WebExtAPIRef("search.get()")}}.
 
@@ -37,24 +37,22 @@ browser.search.search(
 
   - : `object`. An object with the following properties:
 
+    - `disposition` {{optional_inline}}
+      - : `string`. The location where the search results are displayed. Valid values are `CURRENT_TAB`, `NEW_TAB`, and `NEW_WINDOW`. Defaults to `NEW_TAB`. Cannot be specified with `tabId`.
+    - `engine` {{optional_inline}}
+      - : `string`. The name of the search engine. If the search engine name doesn't exist, the function rejects the call with an error. If this property is omitted, the default search engine is used.
     - `query`
       - : `string`. The search query.
-    - `engine` {{optional_inline}}
-      - : `string`. The name of the search engine. If the search engine name you specify doesn't exist, the function throws an error. If this property is omitted the default search engine will be used.
     - `tabId` {{optional_inline}}
-      - : `integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted the search results will be displayed in a new tab.
+      - : `integer`. An optional identifier for the tab you want to execute the search in. If this property is omitted, the search results are displayed in a new tab. Cannot be specified with `disposition`.
 
 ### Return value
 
 None.
 
-## Browser compatibility
-
-{{Compat}}
-
 ## Examples
 
-Search using the default search engine. The results will be shown in a new tab:
+A search using the default search engine with the results shown in the current tab (default):
 
 ```js
 function search() {
@@ -66,20 +64,21 @@ function search() {
 browser.browserAction.onClicked.addListener(search);
 ```
 
-Search using Wikipedia. The results will be shown in a new tab:
+A search using Wikipedia with the results shown in a new window:
 
 ```js
 function search() {
   browser.search.search({
     query: "styracosaurus",
     engine: "Wikipedia (en)"
+    disposition: "NEW_WINDOW"
   });
 }
 
 browser.browserAction.onClicked.addListener(search);
 ```
 
-Search using Wikipedia. The results will be shown in the active tab:
+A search using Wikipedia with the results shown in the current tab:
 
 ```js
 function search(tab) {
@@ -94,3 +93,7 @@ browser.browserAction.onClicked.addListener(search);
 ```
 
 {{WebExtExamples}}
+
+## Browser compatibility
+
+{{Compat}}
diff --git a/files/en-us/mozilla/firefox/releases/111/index.md b/files/en-us/mozilla/firefox/releases/111/index.md
@@ -70,7 +70,9 @@ This article provides information about the changes in Firefox 111 that affect d
 
 ## Changes for add-on developers
 
-- `matchDiacritics` has been added to the {{WebExtAPIRef("Find.find")}} API. This option enables searches to distinguish between accented letters and their base letters. For example, when set to `true`, searching for "résumé" does not find a match for "resume" ([Firefox bug 1680606](https://bugzil.la/1680606))
+- `matchDiacritics` has been added to the {{WebExtAPIRef("Find.find")}} API. This option enables searches to distinguish between accented letters and their base letters. For example, when set to `true`, searching for "résumé" does not find a match for "resume" [Firefox bug 1680606](https://bugzil.la/1680606).
+- {{WebExtAPIRef("search.query")}} has been added, providing search API compatibility with Chromium-based browsers [Firefox bug 1804357](https://bugzil.la/1804357).
+- The `disposition` property has been added to {{WebExtAPIRef("search.search")}}, enabling results to be displayed in a new tab or window [Firefox bug 1811274](https://bugzil.la/1811274).
 
 ### Removals