From 39b37be788c4a985986387a931726192049acb03 Mon Sep 17 00:00:00 2001
From: Andrey Lushnikov <aslushnikov@gmail.com>
Date: Mon, 20 Apr 2020 09:46:36 -0700
Subject: [PATCH] docs(core-concepts.md): add section regarding object &
 element handles (#1871)

---
 docs/README.md        |  4 ++--
 docs/core-concepts.md | 44 ++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 45 insertions(+), 3 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index dee85ca51a..567d11c000 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -6,7 +6,7 @@
     - [Pages and frames](./core-concepts.md#pages-and-frames)
     - [Selectors](./core-concepts.md#selectors)
     - [Auto-waiting](./core-concepts.md#auto-waiting)
-    - [Execution contexts](./core-concepts.md#execution-contexts)
+    - [Node.js and browser execution contexts](./core-concepts.md#node-js-and-browser-execution-contexts)
     - [Object & element handles](./core-concepts.md#object--element-handles)
 1. [Input](./input.md)
     - [Text input](./input.md#text-input)
@@ -47,4 +47,4 @@
 1. Continuous integration
     - Git Hub Action
     - Docker images
-    - Troubleshooting
\ No newline at end of file
+    - Troubleshooting
diff --git a/docs/core-concepts.md b/docs/core-concepts.md
index 3647361cfc..8bf10feb13 100644
--- a/docs/core-concepts.md
+++ b/docs/core-concepts.md
@@ -162,7 +162,7 @@ await page.click('#search');
 
 <br/>
 
-## Execution contexts
+## Node.js and browser execution contexts
 
 Playwright scripts run in your Node.js environment. You page scripts run in the page environment. Those environments don't intersect, they are running in different virtual machines in different processes and potentially on different computers.
 
@@ -199,5 +199,47 @@ You can pass primitive types, JSON-alike objects and remote object handles recei
 
 ## Object & element handles
 
+Playwright has an API to create **node.js references** to DOM elements or objects inside the page. These
+references are called "handles" and live in node.js process, whereas the actual objects reside in browser.
+
+IMAGE PLACEHOLDER
+
+There are two types of handles:
+- [`JSHandle`](./api.md#class-jshandle) to reference any javascript objects in the page
+- [`ElementHandle`](./api.md#class-elementhandle) to reference DOM elements in the page
+
+Note that since any DOM element in the page is also a javascript object,
+Playwright's [`ElementHandle`](./api.md#class-elementhandle) extends
+[`JSHandle`](./api.md#class-jshandle).
+
+Handles Lifetime:
+- Handles can we aquired using page methods [`page.evaluteHandle`](./api.md#pageevaluatehandlepagefunction-arg), [`page.$`](./api.md#pageselector) or [`page.$$`](./api.md#pageselector-1) or
+  their frame counterparts [`frame.evaluateHandle`](./api.md#frameevaluatehandlepagefunction-arg), [`frame.$`](./api.md#frameselector) or [`frame.$$`](./api.md#frameselector-1).
+- Once created, handles will retain object from [grabage collection](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Memory_Management)
+- Handles will be **automatically disposed** once the page or frame they belong to navigates or closes.
+- Handles can be **manually disposed** using [`jsHandle.dispose`](./api.md#jshandledispose) method.
+
+Handles dereferencing can be done with [`jsHandle.evaluate`](./api.md#jshandleevaluatepagefunction-arg) method:
+
+```js
+const handle = await page.$('ul');
+await handle.evaluate(element => getComputedStyle(element).getPropertyValue('display'));
+```
+
+Alternatively, handles can be passed as arguments to [`page.evaluate`](./api.md#pageevaluatepagefunction-arg) function:
+```js
+const handle = await page.$('ul');
+await page.evaluate(element => getComputedStyle(element).getPropertyValue('display'), handle);
+```
+
+
+#### API reference
+- [`JSHandle`](./api.md#class-jshandle)
+- [`ElementHandle`](./api.md#class-elementhandle)
+- [`page.evaluteHandle`](./api.md#pageevaluatehandlepagefunction-arg)
+- [`page.$`](./api.md#pageselector)
+- [`page.$$`](./api.md#pageselector-1)
+- [`jsHandle.evaluate`](./api.md#jshandleevaluatepagefunction-arg)
+
 <br/>