From 862c3187f58daae649d9c360147025e9f5909279 Mon Sep 17 00:00:00 2001
From: Cheng Zhao <zcbenz@gmail.com>
Date: Wed, 28 Oct 2015 21:14:00 +0800
Subject: [PATCH] docs: login event

---
 docs/api/app.md          | 47 +++++++++++++++++++++++++++++++++++++++--------
 docs/api/web-contents.md | 21 +++++++++++++++++++++
 2 files changed, 60 insertions(+), 8 deletions(-)

diff --git a/docs/api/app.md b/docs/api/app.md
index bb1509b..dbb4669 100644
--- a/docs/api/app.md
+++ b/docs/api/app.md
@@ -133,18 +133,23 @@ Emitted when a new [browserWindow](browser-window.md) is created.
 
 ### Event: 'select-certificate'
 
-Emitted when a client certificate is requested.
-
 Returns:
 
 * `event` Event
-* `webContents` [WebContents](browser-window.md#class-webcontents)
-* `url` String
+* `webContents` [WebContents](web-contents.md)
+* `url` URL
 * `certificateList` [Objects]
   * `data` PEM encoded data
   * `issuerName` Issuer's Common Name
 * `callback` Function
 
+Emitted when a client certificate is requested.
+
+The `url` corresponds to the navigation entry requesting the client certificate
+and `callback` needs to be called with an entry filtered from the list. Using
+`event.preventDefault()` prevents the application from using the first
+certificate from the store.
+
 ```javascript
 app.on('select-certificate', function(event, host, url, list, callback) {
   event.preventDefault();
@@ -152,10 +157,36 @@ app.on('select-certificate', function(event, host, url, list, callback) {
 })
 ```
 
-The `url` corresponds to the navigation entry requesting the client certificate
-and `callback` needs to be called with an entry filtered from the list. Using
-`event.preventDefault()` prevents the application from using the first
-certificate from the store.
+### Event: 'login'
+
+Returns:
+
+* `event` Event
+* `webContents` [WebContents](web-contents.md)
+* `request` Object
+  * `method` String
+  * `url` URL
+  * `referrer` URL
+* `authInfo` Object
+  * `isProxy` Boolean
+  * `scheme` String
+  * `host` String
+  * `port` Integer
+  * `realm` String
+* `callback` Function
+
+Emitted when `webContents` wants to do basic auth.
+
+The default behavior is to cancel all authentications, to override this you
+should prevent the default behavior with  `event.preventDefault()` and call
+`callback(username, password)` with the credentials.
+
+```javascript
+app.on('login', function(event, webContents, request, authInfo, callback) {
+  event.preventDefault();
+  callback('username', 'secret');
+})
+```
 
 ### Event: 'gpu-process-crashed'
 
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index 3113356..52a06b8 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -167,6 +167,27 @@ Emitted when DevTools is closed.
 
 Emitted when DevTools is focused / opened.
 
+### Event: 'login'
+
+Returns:
+
+* `event` Event
+* `request` Object
+  * `method` String
+  * `url` URL
+  * `referrer` URL
+* `authInfo` Object
+  * `isProxy` Boolean
+  * `scheme` String
+  * `host` String
+  * `port` Integer
+  * `realm` String
+* `callback` Function
+
+Emitted when `webContents` wants to do basic auth.
+
+The usage is the same with [the `login` event of `app`](app.md#event-login).
+
 ## Instance Methods
 
 The `webContents` object has the following instance methods:
-- 
2.7.4