From 4dc431043fb54fac5bc0c4019b5b9c96ddd4e7e8 Mon Sep 17 00:00:00 2001 From: Cheng Zhao Date: Mon, 9 May 2016 10:20:08 +0900 Subject: [PATCH] docs: When to use protocol.registerStandardSchemes --- docs/api/protocol.md | 62 ++++++++++++++++++++++++++++++-------------- 1 file changed, 42 insertions(+), 20 deletions(-) diff --git a/docs/api/protocol.md b/docs/api/protocol.md index ab0bd7578894..18ce612d02f1 100644 --- a/docs/api/protocol.md +++ b/docs/api/protocol.md @@ -6,22 +6,21 @@ An example of implementing a protocol that has the same effect as the `file://` protocol: ```javascript -const electron = require('electron'); -const { app, protocol } = electron; -const path = require('path'); +const {app, protocol} = require('electron') +const path = require('path') -app.on('ready', function() { - protocol.registerFileProtocol('atom', function(request, callback) { - const url = request.url.substr(7); - callback({path: path.normalize(__dirname + '/' + url)}); - }, function (error) { - if (error) - console.error('Failed to register protocol') - }); -}); +app.on('ready', function () { + protocol.registerFileProtocol('atom', function (request, callback) { + const url = request.url.substr(7) + callback({path: path.normalize(__dirname + '/' + url)}) + }, function (error) { + if (error) + console.error('Failed to register protocol') + }) +}) ``` -**Note:** All methods unless specified can only be used after the `ready` -event in the `app` module is emitted. +**Note:** All methods unless specified can only be used after the `ready` event +of the `app` module gets emitted. ## Methods @@ -31,13 +30,36 @@ The `protocol` module has the following methods: * `schemes` Array - Custom schemes to be registered as standard schemes. -A standard `scheme` adheres to what RFC 3986 calls -[generic URI syntax](https://tools.ietf.org/html/rfc3986#section-3). This -includes `file:`, `filesystem:`, `http` etc. Registering a scheme as standard, will -allow relative and absolute resources to be resolved correctly when served. +A standard scheme adheres to what RFC 3986 calls [generic URI +syntax](https://tools.ietf.org/html/rfc3986#section-3). For example `http` and +`https` are standard schemes, while `file` is not. -**Note:** This method can only be used before the `ready` event in the -`app` module is emitted. +Registering a scheme as standard, will allow relative and absolute resources to +be resolved correctly when served. Otherwise the scheme will behave like the +`file` protocol, but without the ability to resolve relative URLs. + +For example when you load following page with custom protocol without +registering it as standard scheme, the image will not be loaded because +non-standard schemes can not recognize relative URLs: + +```html + + + +``` + +So if you want to register a custom protocol to replace the `http` protocol, you +have to register it as standard scheme: + +```javascript +protocol.registerStandardSchemes(['atom']) +app.on('ready', function () { + protocol.registerHttpProtocol('atom', ...) +}) +``` + +**Note:** This method can only be used before the `ready` event of the `app` +module gets emitted. ### `protocol.registerServiceWorkerSchemes(schemes)`