Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Extract 'Extensibility of the API' #72

Closed
wants to merge 1 commit into from
Closed

Extract 'Extensibility of the API' #72

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ navigator.share({title: 'Example Page', url: 'https://example.com'});
* [Web platform
tests](https://github.com/w3c/web-platform-tests/tree/master/web-share), for
automatic and manual testing against an implementation.
* [Extensibility of the Web Share API](https://wicg.github.io/web-share/extending.html).

This is a product of the [Ballista
project](https://github.com/chromium/ballista), which aims to explore
Expand Down
79 changes: 79 additions & 0 deletions extending.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
<!DOCTYPE html>
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If this is going to go in a separate, informal, document, then:

  1. It should go in /docs.
  2. I think it should just be a plain Markdown file (like the other informal docs in that directory), rather than a Respec-formatted doc.

<html lang="en">
<head>
<meta charset="utf-8">
<title>
Extending the Web Share API
</title>
<script src="https://www.w3.org/Tools/respec/respec-w3c-common" class=
"remove"></script>
</head>
<body>
<section style="display:none;">
<h2>
Dependencies
</h2>
<p>
<code><dfn data-cite=
"!ECMASCRIPT#sec-native-error-types-used-in-this-standard-typeerror">TypeError</dfn></code>
is defined by [[!ECMASCRIPT]].
</p>
</section>
<section class="appendix informative">
<h2>
Extending the Web Share API
</h2>
<p>
The Web Share API is designed to be extended in the future by way of
new members added to the
<a href="https://wicg.github.io/web-share/#sharedata-dictionary">ShareData</a>
dictionary, to allow both
sharing of new types of data (<i>e.g.</i>, <a href=
"https://github.com/WICG/web-share/issues/12">images</a>) and strings
with new semantics (<i>e.g.</i> author).
</p>
<div class="warning">
This doesn't mean user agents can add whatever members they like. It
means that new members can be added to the standard in the future.
</div>
<p data-link-for="ShareData">
The three members <a href="https://wicg.github.io/web-share/#dom-sharedata-title">title</a>,
<a href="https://wicg.github.io/web-share/#dom-sharedata-text">text</a>,
and <a href="https://wicg.github.io/web-share/#dom-sharedata-url">url</a>, are part
of the base feature set, and implementations that provide
<a href="https://wicg.github.io/web-share/#dom-navigator-share">navigator.share()</a>
need to accept all three. Any new members that
are added in the future will be <em>individually
feature-detectable</em>, to allow for backwards-compatibility with
older implementations that don't recognize those members. These new
members might also be added as optional "MAY" requirements.
</p>
<div class="note">
There is <a href="https://github.com/heycam/webidl/issues/107">an open
discussion</a> about how to provide feature-detection for dictionary
members. Web Share will use the mechanism produced by that discussion.
</div>
<p data-link-for="Navigator">
The <a href="https://wicg.github.io/web-share/#dom-navigator-share">share()</a>
method returns a rejected promise
with a <a>TypeError</a> if none of the
specified members are present. The intention is that when a new member
is added, it will also be added to this list of recognized members.
This is for future-proofing implementations:
if a web site written against a future version of this spec uses
<em>only</em> new members (<i>e.g.</i>, <code>navigator.share({image:
x})</code>), it will be valid in future user agents, but a
<a>TypeError</a> on user agents implementing an older version of the
spec. Developers will be asked to feature-detect any new fields they
rely on, to avoid having errors surface in their program.
</p>
<p>
Editors of this spec will want to carefully consider the genericity of
any new members being added, avoiding fields that are closely
associated with a particular service, user agent or operating system,
in favour of fields that can potentially be applied to a wide range of
platforms and targets.
</p>
</section>
</body>
</html>
50 changes: 0 additions & 50 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -421,56 +421,6 @@ <h2>
</li>
</ul>
</section>
<section class="appendix informative">
<h2>
Extensibility of this API
</h2>
<p>
The Web Share API is designed to be extended in the future by way of
new members added to the <a>ShareData</a> dictionary, to allow both
sharing of new types of data (<i>e.g.</i>, <a href=
"https://github.com/WICG/web-share/issues/12">images</a>) and strings
with new semantics (<i>e.g.</i> author).
</p>
<div class="warning">
This doesn't mean user agents can add whatever members they like. It
means that new members can be added to the standard in the future.
</div>
<p data-link-for="ShareData">
The three members <a>title</a>, <a>text</a>, and <a>url</a>, are part
of the base feature set, and implementations that provide
<a>navigator.share()</a> need to accept all three. Any new members that
are added in the future will be <em>individually
feature-detectable</em>, to allow for backwards-compatibility with
older implementations that don't recognize those members. These new
members might also be added as optional "MAY" requirements.
</p>
<div class="note">
There is <a href="https://github.com/heycam/webidl/issues/107">an open
discussion</a> about how to provide feature-detection for dictionary
members. Web Share will use the mechanism produced by that discussion.
</div>
<p data-link-for="Navigator">
The <a>share()</a> method returns a rejected promise
with a <a>TypeError</a> if none of the
specified members are present. The intention is that when a new member
is added, it will also be added to this list of recognized members.
This is for future-proofing implementations:
if a web site written against a future version of this spec uses
<em>only</em> new members (<i>e.g.</i>, <code>navigator.share({image:
x})</code>), it will be valid in future user agents, but a
<a>TypeError</a> on user agents implementing an older version of the
spec. Developers will be asked to feature-detect any new fields they
rely on, to avoid having errors surface in their program.
</p>
<p>
Editors of this spec will want to carefully consider the genericity of
any new members being added, avoiding fields that are closely
associated with a particular service, user agent or operating system,
in favour of fields that can potentially be applied to a wide range of
platforms and targets.
</p>
</section>
<section class="appendix">
<h2>
Acknowledgments
Expand Down