-
Notifications
You must be signed in to change notification settings - Fork 22.5k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Delete web-based protocol handler page; fold relevant content into AP…
…I method page (#35366) * Delete web-based protocol handler page; fold relevant content into API method page * Update files/en-us/web/api/navigator/registerprotocolhandler/index.md Co-authored-by: Joshua Chen <[email protected]> * Add mailto as a separate example * Update files/en-us/web/api/navigator/registerprotocolhandler/index.md Co-authored-by: Joshua Chen <[email protected]> * Update files/en-us/web/api/navigator/registerprotocolhandler/index.md Co-authored-by: Joshua Chen <[email protected]> --------- Co-authored-by: Joshua Chen <[email protected]>
- Loading branch information
Showing
8 changed files
with
78 additions
and
232 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -8,10 +8,16 @@ browser-compat: api.Navigator.registerProtocolHandler | |
|
|
||
| {{APIRef("HTML DOM")}}{{securecontext_header}} | ||
|
|
||
| The **{{domxref("Navigator")}}** method **`registerProtocolHandler()`** lets websites register their ability to open or handle particular URL schemes (aka protocols). | ||
| The **{{domxref("Navigator")}}** method **`registerProtocolHandler()`** lets websites register their ability to open or handle particular URL schemes (also known as protocols). | ||
|
|
||
| For example, this API lets webmail sites open `mailto:` URLs, or VoIP sites open `tel:` URLs. | ||
|
|
||
| To register a protocol handler, a website calls `registerProtocolHandler()`, passing in the protocol to register and a template URL. | ||
|
|
||
| When the user activates a link that uses the registered protocol, the browser will insert the [`href`](/en-US/docs/Web/HTML/Element/a#href) from the activated link into the URL template supplied during handler registration, and navigate the current page to the resulting URL. | ||
|
|
||
| The browser may ask the user to confirm that they want the page to be allowed to handle the protocol, either when the protocol is registered or when the user activates the link. | ||
|
|
||
| ## Syntax | ||
|
|
||
| ```js-nolint | ||
|
|
@@ -22,16 +28,49 @@ registerProtocolHandler(scheme, url) | |
|
|
||
| - `scheme` | ||
|
|
||
| - : A string containing the [permitted scheme](#permitted_schemes) for the protocol that the site wishes to handle. | ||
| For example, you can register to handle SMS text message links by passing the `"sms"` scheme. | ||
| - : A string containing the scheme for the protocol that the site wishes to handle. | ||
|
|
||
| This may be a custom scheme, in which case the scheme's name: | ||
|
|
||
| - Begins with `web+` | ||
| - Contains at least one letter after the `web+` prefix | ||
| - Contains only lowercase {{Glossary("ASCII")}} letters. | ||
|
|
||
| Otherwise, the scheme must be one of the following: | ||
|
|
||
| - `bitcoin` | ||
| - `ftp` | ||
| - `ftps` | ||
| - `geo` | ||
| - `im` | ||
| - `irc` | ||
| - `ircs` | ||
| - `magnet` | ||
| - `mailto` | ||
| - `matrix` | ||
| - `mms` | ||
| - `news` | ||
| - `nntp` | ||
| - `openpgp4fpr` | ||
| - `sftp` | ||
| - `sip` | ||
| - `sms` | ||
| - `smsto` | ||
| - `ssh` | ||
| - `tel` | ||
| - `urn` | ||
| - `webcal` | ||
| - `wtai` | ||
| - `xmpp` | ||
|
|
||
| <!-- This must match: https://html.spec.whatwg.org/multipage/system-state.html#safelisted-scheme --> | ||
|
|
||
| - `url` | ||
|
|
||
| - : A string containing the URL of the handler. | ||
| **This URL must include `%s`**, as a placeholder that will be replaced with the [escaped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) URL to be handled. | ||
| This URL must include `%s`, as a placeholder that will be replaced with the [escaped](/en-US/docs/Web/JavaScript/Reference/Global_Objects/encodeURIComponent) URL to be handled. | ||
|
|
||
| > [!NOTE] | ||
| > The handler URL must use the `https` scheme. Older browsers also supported `http`. | ||
| The handler URL must use the `https` scheme, and must be of the same {{glossary("origin")}} as the webpage that is attempting to register the handler. | ||
|
|
||
| ### Return value | ||
|
|
||
|
|
@@ -46,71 +85,49 @@ None ({{jsxref("undefined")}}). | |
|
|
||
| - The registered scheme (protocol) is invalid, such as a scheme the browser handles itself (`https:`, `about:`, etc.) | ||
| - The handler URL's {{Glossary("origin")}} does not match the origin of the page calling this API. | ||
| - The browser requires that this function is called from a secure context. | ||
| - The browser requires that the handler's URL be over HTTPS. | ||
| - The handler's URL's scheme is not `https`. | ||
|
|
||
| - `SyntaxError` {{domxref("DOMException")}} | ||
| - : The `%s` placeholder is missing from the handler URL. | ||
|
|
||
| ## Permitted schemes | ||
|
|
||
| For security reasons, `registerProtocolHandler()` restricts which schemes can be registered. | ||
|
|
||
| A **custom scheme** may be registered as long as: | ||
|
|
||
| - The custom scheme's name begins with `web+` | ||
| - The custom scheme's name includes at least 1 letter after the `web+` prefix | ||
| - The custom scheme has only lowercase {{Glossary("ASCII")}} letters in its name. | ||
|
|
||
| For example, `web+burger`, as shown in the [Example](#examples) below. | ||
|
|
||
| Otherwise, the scheme must be one of the following: | ||
|
|
||
| - `bitcoin` | ||
| - `ftp` | ||
| - `ftps` | ||
| - `geo` | ||
| - `im` | ||
| - `irc` | ||
| - `ircs` | ||
| - `magnet` | ||
| - `mailto` | ||
| - `matrix` | ||
| - `mms` | ||
| - `news` | ||
| - `nntp` | ||
| - `openpgp4fpr` | ||
| - `sftp` | ||
| - `sip` | ||
| - `sms` | ||
| - `smsto` | ||
| - `ssh` | ||
| - `tel` | ||
| - `urn` | ||
| - `webcal` | ||
| - `wtai` | ||
| - `xmpp` | ||
|
|
||
| <!-- This must match: https://html.spec.whatwg.org/multipage/system-state.html#safelisted-scheme --> | ||
|
|
||
| ## Examples | ||
|
|
||
| If your site is `burgers.example.com`, you can register a protocol handler for it to handle `web+burger:` links, like so: | ||
| ### Registering a handler for the mailto protocol | ||
|
|
||
| It's fairly common for web pages to link to resources using non-`https` protocols. An example is the `mailto:` protocol. Web authors can use a `mailto` link when they want to provide a convenient way for users to send an email directly from the webpage: | ||
|
|
||
| ```html | ||
| <a href="mailto:[email protected]">Web Master</a> | ||
| ``` | ||
|
|
||
| When the link is activated, the browser should launch the default desktop application for handling email. You can think of this as a _desktop-based_ protocol handler. | ||
|
|
||
| Web-based protocol handlers allow web-based applications to participate in the process too. An email web app at `mail.example.org` can register to handle `mailto` links with code like this: | ||
|
|
||
| ```js | ||
| navigator.registerProtocolHandler("mailto", "https://mail.example.org/?to=%s"); | ||
| ``` | ||
|
|
||
| After this, when the user clicks a `mailto` link on any website, the browser will (after possibly asking the browser for confirmation) navigate to `https://mail.example.org/?to=mailto:[email protected]`. This page could parse the URL parameter to extract the address, and use this to initialize an email. | ||
|
|
||
| ### Registering a handler for a custom protocol | ||
|
|
||
| In this example, a page registers a handler for the `web+burger` protocol with code like this: | ||
|
|
||
| ```js | ||
| navigator.registerProtocolHandler( | ||
| "web+burger", | ||
| "https://burgers.example.com/?burger=%s", | ||
| "https://burgers.example.org/?burger=%s", | ||
| ); | ||
| ``` | ||
|
|
||
| This creates a handler that lets `web+burger:` links send the user to your site, inserting the accessed burger URL into the `%s` placeholder. | ||
| Subsequently, the user visit a page containing a link like this: | ||
|
|
||
| This script must be run from the same origin as the handler URL (so any page at `https://burgers.example.com`), and the handler URL must be `http` or `https`. | ||
|
|
||
| The user will be notified that your code asked to register the protocol handler, so that they can decide whether or not to allow it. See the screenshot below for an example on `google.co.uk`: | ||
| ```html | ||
| <a href="web+burger:cheeseburger">cheeseburger</a> | ||
| ``` | ||
|
|
||
|  | ||
| If the user activates the `web+burger` link, the browser will (after possibly asking the user for confirmation) navigate to `https://burgers.example.org/?burger=web+burger:cheeseburger`. | ||
|
|
||
| ## Specifications | ||
|
|
||
|
|
@@ -119,8 +136,3 @@ The user will be notified that your code asked to register the protocol handler, | |
| ## Browser compatibility | ||
|
|
||
| {{Compat}} | ||
|
|
||
| ## See also | ||
|
|
||
| - [Web-based protocol handlers](/en-US/docs/Web/API/Navigator/registerProtocolHandler/Web-based_protocol_handlers) | ||
| - [RegisterProtocolHandler Enhancing the Federated Web](https://blog.mozilla.org/webdev/2010/07/26/registerprotocolhandler-enhancing-the-federated-web/) (Mozilla Webdev) | ||
137 changes: 0 additions & 137 deletions
137
.../web/api/navigator/registerprotocolhandler/web-based_protocol_handlers/index.md
This file was deleted.
Oops, something went wrong.
Binary file removed
BIN
-31.7 KB
...igator/registerprotocolhandler/web-based_protocol_handlers/protocolregister.png
Binary file not shown.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.