mozilla

Revision 72347 of Web-based protocol handlers

  • Revision slug: Web-based_protocol_handlers
  • Revision title: Web-based protocol handlers
  • Revision id: 72347
  • Created:
  • Creator: Dabear
  • Is current revision? No
  • Comment make php example code safe for x-site attacks

Revision Content

{{template.Fx_minversion_header(3)}}

Background

It's fairly common to find web pages link to resources using non-http protocols. An example is the mailto: protocol:

<a href="mailto:webmaster@example.com">Web Master</a>

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. 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. This is becoming more important as more types of applications migrate to the web. In fact, there are many web-based email handling applications that could process a mailto link.

Registering

Setting up a web application as a protocol handler is not a difficult process. Basically, the web application uses registerProtocolHandler() to register itself with the browser as a potential handler for a given protocol. For example:

navigator.registerProtocolHandler("mailto",
                                  "https://www.example.com/?uri=%s",
                                  "Example Mail");

Where the parameters are:

  • The protocol.
  • The URL template, used as the handler. The "%s" is replaced with the href of the link and a GET is executed on the resultant URL.
  • The user friendly name for the protocol handler.

When a browser executes this code, it should display a prompt to the user, asking permission to allow the web application to register as a handler for the protocol. Firefox displays a prompt in the notification bar area:

Image:wph-notification.png

{{wiki.template('Note', mediawiki.args(['The URL template supplied when registering <b>must</b> be of the same domain as the webpage attempting to perform the registration or the registration will fail. For example, <code><span class=\"plain\">' .. http://example.com/homepage.html .. '</span></code> can register a protocol handler for <code><span class=\"plain\">' .. http://example.com/handle_mailto/%s .. '</span></code>, but not for <code><span class=\"plain\">' .. http://example. .. '</span><b>org</b><span class=\"plain\">' .. /handle_mailto/%s .. '</span></code>.']))}}

Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
  <title>Web Protocol Handler Sample - Register</title>
  <script type="text/javascript">
    navigator.registerProtocolHandler("fake", "http://starkravingfinkle.org/projects/wph/handler.php?value=%s", "Fake Protocol");
  </script>
</head>
<body>
  <h1>Web Protocol Handler Sample</h1>
  <p>This web page will install a web protocol handler for the <code>fake:</code> protocol.</p>
</body>
</html>

Activating

Now, anytime the user activates a link that uses the registered protocol, the browser will route the action to the URL supplied when the web application registered. Firefox will, by default, prompt the user before handing off the action.

Image:wph-launch.png

Example

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
  <title>Web Protocol Handler Sample - Test</title>
</head>
<body>
  <p>Hey have you seen <a href="fake:this%20is%20fake">this</a> before?</p>
</body>
</html>

Example

<?php
$value = "";
if ( isset ( $_GET["value"] ) ) {
  $value = $_GET["value"];
}
?>

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<html lang="en">
<head>
    <title>Web Protocol Handler Sample</title>
</head>
<body>
  <h1>Web Protocol Handler Sample - Handler</h1>
  <p>This web page is called when handling a <code>fake:</code> protocol action. The data sent:</p>
  <textarea>
<?php echo htmlspecialchars(urldecode($value)) ?>
  </textarea>
</body>
</html>




Web Protocol Handler Sample - Handler

This web page is called when handling a fake: protocol action. The data sent:

 <textarea>

<?php echo(urldecode($value)) ?>

 </textarea>

</body> </html> </pre>




{{ wiki.languages( { "fr": "fr/Gestionnaires_de_protocoles_web", "ja": "ja/Web-based_protocol_handlers", "pl": "pl/Obs\u0142uga_protoko\u0142\u00f3w_przez_aplikacje_WWW", "fr": "fr/Gestionnaires_de_protocoles_web", "ja": "ja/Web-based_protocol_handlers", "pl": "pl/Obs\u0142uga_protoko\u0142\u00f3w_przez_aplikacje_WWW" } ) }}

Revision Source

<p>
{{template.Fx_minversion_header(3)}}
</p>
<h3 name="Background">Background</h3>
<p>It's fairly common to find web pages link to resources using non-<code>http</code> protocols. An example is the <code>mailto:</code> protocol:
</p>
<pre>&lt;a href="mailto:webmaster@example.com"&gt;Web Master&lt;/a&gt;
</pre>
<p>Web authors can use a <code>mailto:</code> link when they want to provide a convenient way for users to send an email, directly from the webpage. When the link is activated, the browser should launch the default desktop application for handling email. You can think of this as a <i>desktop-based</i> protocol handler.
</p><p>Web-based protocol handlers allow web-based applications to participate in the process too. This is becoming more important as more types of applications migrate to the web. In fact, there are many web-based email handling applications that could process a <code>mailto</code> link.
</p>
<h3 name="Registering">Registering</h3>
<p>Setting up a web application as a protocol handler is not a difficult process. Basically, the web application uses <code><a href="en/DOM/window.navigator.registerProtocolHandler">registerProtocolHandler()</a></code> to register itself with the browser as a potential handler for a given protocol. For example:
</p>
<pre>navigator.registerProtocolHandler("mailto",
                                  "https://www.example.com/?uri=%s",
                                  "Example Mail");
</pre>
<p>Where the parameters are:
</p>
<ul><li> The protocol.
</li><li> The URL template, used as the handler. The "%s" is replaced with the <code>href</code> of the link and a GET is executed on the resultant URL.
</li><li> The user friendly name for the protocol handler.
</li></ul>
<p>When a browser executes this code, it should display a prompt to the user, asking permission to allow the web application to register as a handler for the protocol. Firefox displays a prompt in the notification bar area:
</p><p><img alt="Image:wph-notification.png" src="File:en/Media_Gallery/Wph-notification.png">
</p><p>{{wiki.template('Note', mediawiki.args(['The URL template supplied when registering &lt;b&gt;must&lt;/b&gt; be of the same domain as the webpage attempting to perform the registration or the registration will fail. For example, &lt;code&gt;&lt;span class=\"plain\"&gt;' .. http://example.com/homepage.html .. '&lt;/span&gt;&lt;/code&gt; can register a protocol handler for &lt;code&gt;&lt;span class=\"plain\"&gt;' .. http://example.com/handle_mailto/%s .. '&lt;/span&gt;&lt;/code&gt;, but not for &lt;code&gt;&lt;span class=\"plain\"&gt;' .. http://example. .. '&lt;/span&gt;&lt;b&gt;org&lt;/b&gt;&lt;span class=\"plain\"&gt;' .. /handle_mailto/%s .. '&lt;/span&gt;&lt;/code&gt;.']))}}
</p>
<h4 name="Example">Example</h4>
<pre>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"&gt;
&lt;html lang="en"&gt;
&lt;head&gt;
  &lt;title&gt;Web Protocol Handler Sample - Register&lt;/title&gt;
  &lt;script type="text/javascript"&gt;
    navigator.registerProtocolHandler("fake", "http://starkravingfinkle.org/projects/wph/handler.php?value=%s", "Fake Protocol");
  &lt;/script&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;h1&gt;Web Protocol Handler Sample&lt;/h1&gt;
  &lt;p&gt;This web page will install a web protocol handler for the &lt;code&gt;fake:&lt;/code&gt; protocol.&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<h3 name="Activating">Activating</h3>
<p>Now, anytime the user activates a link that uses the registered protocol, the browser will route the action to the URL supplied when the web application registered. Firefox will, by default, prompt the user before handing off the action.
</p><p><img alt="Image:wph-launch.png" src="File:en/Media_Gallery/Wph-launch.png">
</p>
<h4 name="Example_2">Example</h4>
<pre>&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"&gt;
&lt;html lang="en"&gt;
&lt;head&gt;
  &lt;title&gt;Web Protocol Handler Sample - Test&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;p&gt;Hey have you seen &lt;a href="fake:this%20is%20fake"&gt;this&lt;/a&gt; before?&lt;/p&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<h4 name="Example_3">Example</h4>
<pre>&lt;?php
$value = "";
if ( isset ( $_GET["value"] ) ) {
  $value = $_GET["value"];
}
?&gt;

&lt;!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"&gt;
&lt;html lang="en"&gt;
&lt;head&gt;
    &lt;title&gt;Web Protocol Handler Sample&lt;/title&gt;
&lt;/head&gt;
&lt;body&gt;
  &lt;h1&gt;Web Protocol Handler Sample - Handler&lt;/h1&gt;
  &lt;p&gt;This web page is called when handling a &lt;code&gt;fake:&lt;/code&gt; protocol action. The data sent:&lt;/p&gt;
  &lt;textarea&gt;
&lt;?php echo htmlspecialchars(urldecode($value)) ?&gt;
  &lt;/textarea&gt;
&lt;/body&gt;
&lt;/html&gt;
</pre>
<p><br>
</p><p><br>
</p><p><br>
</p>
<div class="noinclude">
</div>
<h2 name="Web_Protocol_Handler_Sample_-_Handler">Web Protocol Handler Sample - Handler</h2>
  <p>This web page is called when handling a <code>fake:</code> protocol action. The data sent:</p>
<pre class="eval"> &lt;textarea&gt;
</pre>
<p>&lt;?php echo(urldecode($value)) ?&gt;
</p>
<pre class="eval"> &lt;/textarea&gt;
</pre>
<p>&lt;/body&gt;
&lt;/html&gt;
&lt;/pre&gt;
</p><p><br>
</p><p><br>
</p><p><br>
</p>
<div class="noinclude">
</div>
{{ wiki.languages( { "fr": "fr/Gestionnaires_de_protocoles_web", "ja": "ja/Web-based_protocol_handlers", "pl": "pl/Obs\u0142uga_protoko\u0142\u00f3w_przez_aplikacje_WWW", "fr": "fr/Gestionnaires_de_protocoles_web", "ja": "ja/Web-based_protocol_handlers", "pl": "pl/Obs\u0142uga_protoko\u0142\u00f3w_przez_aplikacje_WWW" } ) }}
Revert to this revision