From 5214ef1c72621d0969991b047dac613c13a2a767 Mon Sep 17 00:00:00 2001 From: Eric Willigers Date: Tue, 20 Feb 2018 14:06:55 +1100 Subject: [PATCH] Extract 'Extensibility of the API' The chapter 'Extensibility of the API' is moved into a separate document. It remains available as a resource for informing future evolution of the specification, without itself being part of the specification. resolves #61 --- README.md | 1 + extending.html | 79 ++++++++++++++++++++++++++++++++++++++++++++++++++ index.html | 50 -------------------------------- 3 files changed, 80 insertions(+), 50 deletions(-) create mode 100644 extending.html diff --git a/README.md b/README.md index d39900a..86336ec 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/extending.html b/extending.html new file mode 100644 index 0000000..8c3abc3 --- /dev/null +++ b/extending.html @@ -0,0 +1,79 @@ + + + + + + Extending the Web Share API + + + + +
+

+ Dependencies +

+

+ TypeError + is defined by [[!ECMASCRIPT]]. +

+
+
+

+ Extending the Web Share API +

+

+ The Web Share API is designed to be extended in the future by way of + new members added to the + ShareData + dictionary, to allow both + sharing of new types of data (e.g., images) and strings + with new semantics (e.g. author). +

+
+ 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. +
+

+ The three members title, + text, + and url, are part + of the base feature set, and implementations that provide + navigator.share() + need to accept all three. Any new members that + are added in the future will be individually + feature-detectable, 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. +

+
+ There is an open + discussion about how to provide feature-detection for dictionary + members. Web Share will use the mechanism produced by that discussion. +
+

+ The share() + method returns a rejected promise + with a TypeError 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 + only new members (e.g., navigator.share({image: + x})), it will be valid in future user agents, but a + TypeError 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. +

+

+ 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. +

+
+ + diff --git a/index.html b/index.html index 49dc713..84eff2a 100644 --- a/index.html +++ b/index.html @@ -421,56 +421,6 @@

-
-

- Extensibility of this API -

-

- The Web Share API is designed to be extended in the future by way of - new members added to the ShareData dictionary, to allow both - sharing of new types of data (e.g., images) and strings - with new semantics (e.g. author). -

-
- 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. -
-

- The three members title, text, and url, are part - of the base feature set, and implementations that provide - navigator.share() need to accept all three. Any new members that - are added in the future will be individually - feature-detectable, 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. -

-
- There is an open - discussion about how to provide feature-detection for dictionary - members. Web Share will use the mechanism produced by that discussion. -
-

- The share() method returns a rejected promise - with a TypeError 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 - only new members (e.g., navigator.share({image: - x})), it will be valid in future user agents, but a - TypeError 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. -

-

- 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. -

-

Acknowledgments