docs: URL protocol handler example

Author: molant

.vscode/settings.json

@@ -0,0 +1,5 @@
+{
+    "files.associations": {
+        "*.pmd": "markdown"
+    }
+}

README.md

@@ -92,17 +92,26 @@ They live under the [`/src/transformers`][transformers] folder:
 
   <Tabs>
     <TabItem value="electron" label="Electron" default>
+
       {@import ./electron.pmd}
+
     </TabItem>
     <TabItem value="pwa" label="PWA">
+
       {@import ./pwa.pmd}
+
     </TabItem>
     <TabItem value="wv2" label="WebView2">
+
       {@import ./wv2.pmd}
+
     </TabItem>
   </Tabs>;
    ```
 
+**CAUTION:** It is important to leave a blank link before and after `{@import}, otherwise it
+will not work.
+
 `partial-content` files can also make use of `import-code`.
 
 

data/examples/index.json

@@ -423,8 +423,8 @@
     "name": "URL protocol handler",
     "electron": {
       "gist": "",
-      "status": "",
-      "documentation": ""
+      "status": "✅",
+      "documentation": "https://www.electronjs.org/docs/latest/tutorial/launch-app-from-url-in-another-app"
     },
     "pwa": {
       "gist": "",

docs/examples-list.pmd

@@ -17,7 +17,7 @@
 | Run on OS login | | | | |
 | Serial access |✅ | | | |
 | URL handler | | | | |
-| URL protocol handler | | | | |
+| [URL protocol handler](/docs/examples/url-protocol-handler) |✅ ([Docs](https://www.electronjs.org/docs/latest/tutorial/launch-app-from-url-in-another-app)) | | | |
 | USB access | | | | |
 | Using local fonts | | | | |
 | Video codecs | | | | |

docs/examples.md

@@ -4,4 +4,4 @@ These are all the features we have planned to have examples for. Those that are
 are linked from the feature name. There are also links to more in depth documentation for each
 technology when found.
 
-{@import ./examples-list.pmd}
+{@import ./examples-list.pmd}

docs/examples/url-protocol-handler.mdx

@@ -0,0 +1,39 @@
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import LaunchButton from '../../src/components/LaunchButton';
+
+# URL protocol handler
+
+It's fairly common to find web pages link to resources using non-http protocols. An example is the `mailto:` protocol:
+
+```html
+<a href="mailto:[email protected]">Web Master</a>
+```
+
+You might want your application to become the handler for a particular protocol well-known protocol (if you are an email
+application, for example) or even create your own custom protocol to handle links that navigate to particular
+places or states in your application. This is particularly useful when sharing some content with contacts and a common
+scenario many applications need to implement.
+
+## Implementation
+
+<Tabs>
+  <TabItem value="electron" label="Electron" default>
+
+{@import ./url-protocol-handler/electron.pmd}
+
+If you have Fiddle installed, you can run a full example by clicking the following button:
+<LaunchButton url="https://fiddle.electronjs.org/launch?target=electron/v14.0.1/docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app"></LaunchButton>
+
+  </TabItem>
+  <TabItem value="pwa" label="PWA">
+
+{@import ./url-protocol-handler/pwa.pmd}
+
+  </TabItem>
+  <TabItem value="wv2" label="WebView2">
+
+{@import ./url-protocol-handler/webview2.pmd}
+
+  </TabItem>
+</Tabs>

docs/examples/url-protocol-handler/electron.pmd

@@ -0,0 +1,49 @@
+To register a custom protocol in your Electron application you can use the
+[`setAsDefaultProtocolClient`][protocol] method of the [`app`][app] module.
+
+```js {4}
+const { app } = require('electron');
+
+app.whenReady().then(() => {
+  app.setAsDefaultProtocolClient('mycustomprotocol');
+});
+```
+
+Once registered, your application will be opened anytime a user interacts with a link
+similar to `mycustomprotocol://custom/path`. How the application access the URI is
+different depending on the platform.
+
+For macOS is via the [`open-url`][open-url] event
+
+```js
+const { app } = require('electron');
+
+app.on('open-url', (event, url) => {
+  // Your code handling here
+});
+```
+
+On Windows the URI is passed as part of the arguments (`process.argv`) when starting the
+application. Because the position could change, it is recommended to iterate to find the
+right one. An optimistic implementation would be:
+
+```js
+const protocolArg = process.argv.find((arg) => arg.startsWith('mycustomprotocol://'));
+if(!protocolArg){
+  return;
+}
+
+// Your code handling here
+```
+
+:::caution
+Depending on the platform there might be some extra steps to do (like add the protocol to
+the app's `info.plist` on macOS). Make sure to read the [official documentation][protocol].
+:::
+
+Contrary to the PWA case, there are no limitations on the name of the protocol, thus
+why the name is `mycustomprotocol` and not `web+mycustomprotocol`.
+
+[app]: https://www.electronjs.org/docs/latest/api/app/
+[open-url]: https://www.electronjs.org/docs/latest/api/app/#event-open-url-macos
+[protocol]: https://www.electronjs.org/docs/latest/api/app/#appsetasdefaultprotocolclientprotocol-path-args

docs/examples/url-protocol-handler/pwa.pmd

@@ -0,0 +1,50 @@
+When building a PWA there are 2 ways to register the applications as a protocol handler:
+
+The first one is specifying the `protocol_handlers` property in the [Web app manifest] of the PWA:
+
+```json {12-17}
+{
+  "name": "My PWA",
+  "orientation": "any",
+  "icons": [
+    {
+      "src": "icon.png",
+      "sizes": "512x512",
+      "type": "image/png"
+    }
+  ],
+  //...
+  "protocol_handlers": [
+    {
+      "protocol": "web+mycustomprotocol",
+      "url": "index.html?custom=%s"
+    }
+  ]
+}
+```
+
+Or you can do it programatically via JavaScript calling
+`navigator.registerProtocolHandler`:
+
+```js {2}
+document.addEventListener('DOMContentLoaded', (event) => {
+  navigator.registerProtocolHandler('web+mycustomprotocol', 'index.html?custom=%s');
+})
+```
+
+The value of the protocol can be one of the following 2 options:
+
+1. One of the [safelisted schemes]
+1. Or begin with `web+` followed by at least one or more lowercase ASCII letters
+
+You can learn more in [this article in web.dev][web.dev].
+
+:::caution
+This feature is currently being tested in Chromium browsers. Websites can opt-in via
+[origin trials]
+:::
+
+[origin trials]: https://developer.chrome.com/origintrials/#/view_trial/1136033006004207617
+[safelisted schemes]: https://html.spec.whatwg.org/multipage/system-state.html#safelisted-scheme
+[web.dev]: https://web.dev/url-protocol-handler/
+[Web app manifest]: https://web.dev/add-manifest/

docs/examples/url-protocol-handler/webview2.pmd

@@ -0,0 +1,103 @@
+As mentioned in [its page][wv2], WebView2 is available on Windows platforms and can be used from C#
+on a WPF or WinForms application, or in a Win32 with C++.
+
+:::caution
+While the macOS version of WebView2 is in development, there is no preview available. That said,
+registering the application to handle a custom protocol will require calling to OS APIs the same
+way it is done on Windows.
+:::
+
+To handle the
+On a WPF application the URL is passed as part of the parameters when invoking it so you have to
+look for it:
+
+```csharp
+class Program
+{
+  [STAThread]
+  static void Main(string[] args)
+  {
+    if (args != null && args.Length > 0)
+    {
+      if (args[0].StartsWith("mycustomprotocol://"))
+      {
+        //handle URI activation
+      }
+
+      App application = new App();
+      application.InitializeComponent();
+      application.Run();
+  }
+}
+```
+
+If you are using it on a Win32 application with C++, then your could will look similar to:
+
+```cpp
+// Parameters are assumed to be valid
+
+HRESULT GetPropVariantForUrlAndTime
+    (PCWSTR pszUrl, const FILETIME &ftLastModified, PROPVARIANT **ppPropValue)
+{
+    *ppPropValue = NULL;
+
+    // Allocate the propvariant pointer.
+    size_t const cbAlloc = sizeof(**ppPropValue);
+    *ppPropValue = (PROPVARIANT *)CoTaskMemAlloc(cbAlloc));
+
+    HRESULT hr = *ppPropValue ? S_OK : E_OUTOFMEMORY;
+
+    if (SUCCEEDED(hr))
+    {
+        PropVariantInit(*ppPropValue);  // Zero init the value
+
+        // Now allocate enough memory for 2 nested PropVariants.
+        // PKEY_Search_UrlToIndexWithModificationTime is an array of two PROPVARIANTs.
+        PROPVARIANT *pVector = (PROPVARIANT *)CoTaskMemAlloc(sizeof(*pVector) * 2);
+        hr = pVector ? S_OK : E_OUTOFMEMORY;
+
+        if (SUCCEEDED(hr))
+        {
+            // Set the container PROPVARIANT to be a vector of two PROPVARIANTS.
+            (*ppPropValue)->vt = VT_VARIANT | VT_VECTOR;
+            (*ppPropValue)->capropvar.cElems = 2;
+            (*ppPropValue)->capropvar.pElems = pVector;
+            PWSTR pszUrlAlloc;
+            hr = SHStrDup(pszUrl, &pszUrlAlloc);
+
+            if (SUCCEEDED(hr))
+            {
+                // Now fill the array of PROPVARIANTS.
+                // Put the pointer to the URL into the vector.
+                (*ppPropValue)->capropvar.pElems[0].vt = VT_LPWSTR;
+                (*ppPropValue)->capropvar.pElems[0].pwszVal = pszUrlAlloc;
+
+                 // Put the FILETIME into vector.
+                (*ppPropValue)->capropvar.pElems[1].vt = VT_FILETIME;
+                (*ppPropValue)->capropvar.pElems[1].filetime = ftLastModified;
+            }
+
+            else
+            {
+                CoTaskMemFree(pVector);
+            }
+        }
+
+        if (FAILED(hr))
+        {
+            CoTaskMemFree(*ppPropValue);
+            *ppPropValue = NULL;
+        }
+    }
+    return S_OK;
+}
+```
+
+:::info
+Depending on how your application is packaged and distributed (i.e.: MSIX, squirrel, etc.) you might
+have to do some extra steps like modifying the registry or a manifest.
+:::
+You can read more in [Installing and Registering Protocol Handlers].
+
+[Installing and Registering Protocol Handlers]: https://docusaurus.io/docs/markdown-features/admonitions
+[wv2]: /docs/webview2

docs/snippets.md

@@ -34,6 +34,12 @@ module.exports = {
           position: 'left',
           label: 'Rendering strategies',
         },
+        {
+          type:'doc',
+          docId: 'examples',
+          position: 'left',
+          label: 'Examples'
+        },
         // {to: '/blog', label: 'Blog', position: 'left'},
         {
           href: 'https://github.com/crossplatform-dev/crossplatform.dev',

docusaurus.config.js

@@ -181,12 +181,12 @@ const normalizeStatus = (status) => {
     // TODO: Check if it has been merged
     return '🛠';
   }
-  if(status.includes('crbug')){
+  if (status.includes('crbug')) {
     // TODO: Get the resolution of the issue via Playwright because x-xsrf-token and other stuff :(
     return 'TBD';
   }
 
-  return '❓';
+  return status;
 };
 
 /**
@@ -201,14 +201,13 @@ const technologyStateMarkdown = (technology) => {
   }
 
   if (technology.status) {
+    let status = normalizeStatus(technology.status);
+
     if (technology.documentation) {
       // TODO: Resolve status links from crbug
-      return `[${normalizeStatus(technology.status)}](${
-        technology.documentation
-      })`;
-    } else {
-      return normalizeStatus(technology.status);
+      status += ` ([Docs](${technology.documentation}))`;
     }
+    return status;
   } else {
     return '';
   }

scripts/process-examples-sources.js

@@ -8,4 +8,5 @@ module.exports = {
       items: ['browser-engine', 'platform-controls', 'direct-drawing'],
     },
   ],
+  examples: ['examples', 'examples/url-protocol-handler'],
 };