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)` diff --git a/lib/browser/api/protocol.js b/lib/browser/api/protocol.js index 2507acddc83d..b146931a2b48 100644 --- a/lib/browser/api/protocol.js +++ b/lib/browser/api/protocol.js @@ -1,39 +1,16 @@ -const app = require('electron').app +const {app} = require('electron') const {createProtocolObject, registerStandardSchemes} = process.atomBinding('protocol') -let protocol = null - -// Warn about removed APIs. -var logAndThrow = function (callback, message) { - console.error(message) - if (callback) { - return callback(new Error(message)) - } else { - throw new Error(message) - } -} exports.registerStandardSchemes = function (schemes) { if (app.isReady()) { - throw new Error('protocol.registerStandardSchemes should be called before app is ready') + console.warn('protocol.registerStandardSchemes should be called before app is ready') + return } registerStandardSchemes(schemes) } app.once('ready', function () { - protocol = createProtocolObject() - // Be compatible with old APIs. - protocol.registerProtocol = function (scheme, handler, callback) { - return logAndThrow(callback, 'registerProtocol API has been replaced by the register[File/Http/Buffer/String]Protocol API family, please switch to the new APIs.') - } - - protocol.isHandledProtocol = function (scheme, callback) { - return logAndThrow(callback, 'isHandledProtocol API has been replaced by isProtocolHandled.') - } - - protocol.interceptProtocol = function (scheme, handler, callback) { - return logAndThrow(callback, 'interceptProtocol API has been replaced by the intercept[File/Http/Buffer/String]Protocol API family, please switch to the new APIs.') - } - + let protocol = createProtocolObject() for (let method in protocol) { exports[method] = protocol[method].bind(protocol) } diff --git a/spec/api-protocol-spec.js b/spec/api-protocol-spec.js index cfbbc6608e06..2a1d158c3dfd 100644 --- a/spec/api-protocol-spec.js +++ b/spec/api-protocol-spec.js @@ -841,12 +841,6 @@ describe('protocol module', function () { }) }) - it('throws when called after ready event', function () { - assert.throws(function () { - protocol.registerStandardSchemes(['some-scheme']) - }, 'protocol.registerStandardSchemes should be called before app is ready') - }) - it('resolves relative resources', function (done) { var handler = function (request, callback) { if (request.url === imageURL) {