Skip to content

Commit

Permalink
docs: modernize protocol-handler docs (#30057)
Browse files Browse the repository at this point in the history 
* docs: modernize protocol-handler docs

* docs: iadd contextIsolation

* docs: add guide for launch-app-from-URL-in-other-app

* docs: address comments

* chore: fix brackets

* chore: add escaped brackets

Co-authored-by: George Xu <gxu@slack-corp.com>
  • Loading branch information
@trop
trop[bot] and George Xu committed Jul 9, 2021
1 parent 84eea6f commit d09e7f8
Show file tree
Hide file tree
Showing 5 changed files with 307 additions and 144 deletions.
153 changes: 71 additions & 82 deletions docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/index.html
View file
@@ -1,92 +1,81 @@
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>Hello World!</title>
</head>

<head>
<meta charset="UTF-8">
<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'">
<meta http-equiv="X-Content-Security-Policy" content="default-src 'self'; script-src 'self'">
<title>app.setAsDefaultProtocol Demo</title>
</head>

<body>
<section>
<header>
<h1>
Protocol Handler
</h1>
<h3>The <code>app</code> module provides methods for handling protocols.</h3>
<p>These methods allow you to set and unset the protocols your app should be the default app for. Similar to when a browser asks to be your default for viewing web pages.</p>
<h1>App Default Protocol Demo</h1>

<p>The protocol API allows us to register a custom protocol and intercept existing protocol requests.</p>
<p>These methods allow you to set and unset the protocols your app should be the default app for. Similar to when a
browser asks to be your default for viewing web pages.</p>

<p>Open the <a href="https://www.electronjs.org/docs/api/protocol">full protocol API documentation</a> in your
browser.</p>

-----

<h3>Demo</h3>
<p>
First: Launch current page in browser
<button id="open-in-browser" class="js-container-target demo-toggle-button">
Click to Launch Browser
</button>
</p>

<p>
Then: Launch the app from a web link!
<a href="electron-fiddle://open">Click here to launch the app</a>
</p>

----

<p>Open the <a href="https://electronjs.org/docs/api/app">full app API documentation<span class="u-visible-to-screen-reader">(opens in new window)</span></a> in your browser.</p>
</header>
<p>You can set your app as the default app to open for a specific protocol. For instance, in this demo we set this app
as the default for <code>electron-fiddle://</code>. The demo button above will launch a page in your default
browser with a link. Click that link and it will re-launch this app.</p>

<div >
<button id="open-in-browser" class="js-container-target demo-toggle-button">Launch current page in browser
<div class="demo-meta u-avoid-clicks">Supports: Win, macOS <span class="demo-meta-divider">|</span> Process: Main</div>
</button>
<section id='open-app-link'>
<a href="electron-api-demos://open">Now... launch the app from a web link</a>
</section>
<div >
<p>You can set your app as the default app to open for a specific protocol. For instance, in this demo we set this app as the default for <code>electron-api-demos://</code>. The demo button above will launch a page in your default browser with a link. Click that link and it will re-launch this app.</p>
<h5>Packaging</h5>
<p>This feature will only work on macOS when your app is packaged. It will not work when you're launching it in development from the command-line. When you package your app you'll need to make sure the macOS <code>plist</code> for the app is updated to include the new protocol handler. If you're using <code>electron-packager</code> then you can add the flag <code>--extend-info</code> with a path to the <code>plist</code> you've created. The one for this app is below.</p>
<h5>Renderer Process</h5>
<pre><code>
const {shell} = require('electron')
const path = require('path')
const protocolHandlerBtn = document.getElementById('protocol-handler')
protocolHandlerBtn.addEventListener('click', () => {
const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
const pagePath = path.join('file://', pageDirectory, '../../sections/system/protocol-link.html')
shell.openExternal(pagePath)
})
</code></pre>
<h5>Main Process</h5>
<pre><code>
const {app, dialog} = require('electron')
const path = require('path')

if (process.defaultApp) {
if (process.argv.length >= 2) {
app.setAsDefaultProtocolClient('electron-api-demos', process.execPath, [path.resolve(process.argv[1])])
}
} else {
app.setAsDefaultProtocolClient('electron-api-demos')
}
<h3>Packaging</h3>
<p>This feature will only work on macOS when your app is packaged. It will not work when you're launching it in
development from the command-line. When you package your app you'll need to make sure the macOS <code>plist</code>
for the app is updated to include the new protocol handler. If you're using <code>electron-packager</code> then you
can add the flag <code>--extend-info</code> with a path to the <code>plist</code> you've created. The one for this
app is below:</p>

app.on('open-url', (event, url) => {
dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
})
<p>
<h5>macOS plist</h5>
<pre><code>
&lt;?xml version="1.0" encoding="UTF-8"?&gt;
&lt;!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd"&gt;
&lt;plist version="1.0"&gt;
&lt;dict&gt;
&lt;key&gt;CFBundleURLTypes&lt;/key&gt;
&lt;array&gt;
&lt;dict&gt;
&lt;key&gt;CFBundleURLSchemes&lt;/key&gt;
&lt;array&gt;
&lt;string&gt;electron-api-demos&lt;/string&gt;
&lt;/array&gt;
&lt;key&gt;CFBundleURLName&lt;/key&gt;
&lt;string&gt;Electron API Demos Protocol&lt;/string&gt;
&lt;/dict&gt;
&lt;/array&gt;
&lt;key&gt;ElectronTeamID&lt;/key&gt;
&lt;string&gt;VEKTX9H2N7&lt;/string&gt;
&lt;/dict&gt;
&lt;/plist&gt;
</code>
</pre>
<p>

</code></pre>
<h5>macOS plist</h5>
<pre><code>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>electron-api-demos</string>
</array>
<key>CFBundleURLName</key>
<string>Electron API Demos Protocol</string>
</dict>
</array>
<key>ElectronTeamID</key>
<string>VEKTX9H2N7</string>
</dict>
</plist>
</code>
</pre>
</div>
</div>
<script type="text/javascript">
require('./renderer.js')
</script>
</section>
<!-- You can also require other files to run in this process -->
<script src="./renderer.js"></script>
</body>
</html>

</body>
</html>
</html>
92 changes: 43 additions & 49 deletions docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/main.js
View file
@@ -1,69 +1,63 @@
// Modules to control application life and create native browser window
const { app, BrowserWindow, dialog } = require('electron')
const { app, BrowserWindow, ipcMain, shell } = require('electron')
const path = require('path')

// Keep a global reference of the window object, if you don't, the window will
// be closed automatically when the JavaScript object is garbage collected.
let mainWindow
let mainWindow;

if (process.defaultApp) {
if (process.argv.length >= 2) {
app.setAsDefaultProtocolClient('electron-fiddle', process.execPath, [path.resolve(process.argv[1])])
}
} else {
app.setAsDefaultProtocolClient('electron-fiddle')
}

const gotTheLock = app.requestSingleInstanceLock()

if (!gotTheLock) {
app.quit()
} else {
app.on('second-instance', (event, commandLine, workingDirectory) => {
// Someone tried to run a second instance, we should focus our window.
if (mainWindow) {
if (mainWindow.isMinimized()) mainWindow.restore()
mainWindow.focus()
}
})

// Create mainWindow, load the rest of the app, etc...
app.whenReady().then(() => {
createWindow()
})

app.on('open-url', (event, url) => {
dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
})
}

function createWindow () {
// Create the browser window.
mainWindow = new BrowserWindow({
width: 800,
height: 600,
webPreferences: {
nodeIntegration: true
preload: path.join(__dirname, 'preload.js'),
}
})

// and load the index.html of the app.
mainWindow.loadFile('index.html')

// Open the DevTools.
mainWindow.webContents.openDevTools()

// Emitted when the window is closed.
mainWindow.on('closed', function () {
// Dereference the window object, usually you would store windows
// in an array if your app supports multi windows, this is the time
// when you should delete the corresponding element.
mainWindow = null
})
}

// This method will be called when Electron has finished
// initialization and is ready to create browser windows.
// Some APIs can only be used after this event occurs.
app.whenReady().then(createWindow)

// Quit when all windows are closed.
// Quit when all windows are closed, except on macOS. There, it's common
// for applications and their menu bar to stay active until the user quits
// explicitly with Cmd + Q.
app.on('window-all-closed', function () {
// On macOS it is common for applications and their menu bar
// to stay active until the user quits explicitly with Cmd + Q
if (process.platform !== 'darwin') {
app.quit()
}
})

app.on('activate', function () {
// On macOS it is common to re-create a window in the app when the
// dock icon is clicked and there are no other windows open.
if (mainWindow === null) {
createWindow()
}
if (process.platform !== 'darwin') app.quit()
})

// In this file you can include the rest of your app's specific main process
// code. You can also put them in separate files and require them here.

if (process.defaultApp) {
if (process.argv.length >= 2) {
app.setAsDefaultProtocolClient('electron-api-demos', process.execPath, [path.resolve(process.argv[1])])
}
} else {
app.setAsDefaultProtocolClient('electron-api-demos')
}

app.on('open-url', (event, url) => {
dialog.showErrorBox('Welcome Back', `You arrived from: ${url}`)
// Handle window controls via IPC
ipcMain.on('shell:open', () => {
const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
const pagePath = path.join('file://', pageDirectory, 'index.html')
shell.openExternal(pagePath)
})
11 changes: 11 additions & 0 deletions docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/preload.js
View file
@@ -0,0 +1,11 @@
// All of the Node.js APIs are available in the preload process.
// It has the same sandbox as a Chrome extension.
const { contextBridge, ipcRenderer } = require('electron')

// Set up context bridge between the renderer process and the main process
contextBridge.exposeInMainWorld(
'shell',
{
open: () => ipcRenderer.send('shell:open'),
}
)
20 changes: 7 additions & 13 deletions docs/fiddles/system/protocol-handler/launch-app-from-URL-in-another-app/renderer.js
View file
@@ -1,14 +1,8 @@
const { shell } = require('electron')
const path = require('path')
// This file is required by the index.html file and will
// be executed in the renderer process for that window.
// All APIs exposed by the context bridge are available here.

const openInBrowserButton = document.getElementById('open-in-browser')
const openAppLink = document.getElementById('open-app-link')
// Hides openAppLink when loaded inside Electron
openAppLink.style.display = 'none'

openInBrowserButton.addEventListener('click', () => {
console.log('clicked')
const pageDirectory = __dirname.replace('app.asar', 'app.asar.unpacked')
const pagePath = path.join('file://', pageDirectory, 'index.html')
shell.openExternal(pagePath)
})
// Binds the buttons to the context bridge API.
document.getElementById('open-in-browser').addEventListener('click', () => {
shell.open();
});

0 comments on commit d09e7f8

Please sign in to comment.