Example with POST (#58)

* Example with POST

We now have an example of receiving a POST, and state POST semantics.

resolves #57

Author: ewilligers

index.html

@@ -168,6 +168,46 @@ <h2>
         shared. If the ShareData contains no information for a given member,
         the query parameter is omitted.
       </p>
+      <p>
+        A share target might only be interested in a subset of the
+        <a data-cite="WebShare#dom-sharedata">ShareData</a> members. This
+        example also shows a share target that receives data as a
+        <code>POST</code> request, which should be the case if the request
+        causes an immediate side effect.
+      </p>
+      <pre class="example json" title="manifest.webmanifest">
+{
+  "name": "Bookmark",
+  "share_target": {
+    "action": "/bookmark",
+    "method": "POST",
+    "enctype": "multipart/form-data",
+    "params": {
+      "url": "link"
+    }
+  }
+}
+</pre>
+      <p>
+        The shared information might be read by a <a data-cite=
+        "service-workers-1#service-worker-concept">service worker</a>, rather
+        than being sent over the network to the server.
+      </p>
+      <pre class="example javascript" title="sw.js">
+self.addEventListener('fetch', event =&gt; {
+  if (event.request.method !== 'POST') {
+    event.respondWith(fetch(event.request));
+    return;
+  }
+
+  event.respondWith((async () =&gt; {
+    const formData = await event.request.formData();
+    const link = formData.get('link') || '';
+    saveBookmark(link);
+    return new Response('Bookmark saved: ' + link);
+  })());
+});
+</pre>
       <p>
         How the handler deals with the shared data is at the handler's
         discretion, and will generally depend on the type of app. Here are some
@@ -325,6 +365,12 @@ <h3>
           "https://tools.ietf.org/html/rfc7231#section-4">method</a> for the
           <a data-link-for="web share targets">web share target</a>.
         </p>
+        <p class="note">
+          A use case for <code>GET</code> requests is when the share target
+          drafts a message for subsequent user approval. If the share target
+          performs a side-effect without any user interaction,
+          <code>POST</code> requests should be used.
+        </p>
         <p>
           The <dfn>enctype</dfn> member specifies how the share data is encoded
           in the body of a <code>POST</code> request. It is ignored when