1 | # Inspector Overlay
|
2 |
|
3 | Inspector Overlay provides JS/CSS modules which are responsible for rendering the overlay content when you inspect an element in DevTools.
|
4 |
|
5 | ## How build works
|
6 |
|
7 | - Overlay modules are built using rollup and copied to $root_gen_dir.
|
8 | - CSS files are imported using a custom rollup plugin that transforms CSS into a CSSStyleSheet. *Only use CSS imports in the bundle entrypoint*.
|
9 | - `inspector_overlay_resources.grd` file is copied as well and it defines how modules are packaged in a `.pak` file.
|
10 | - The Chromium build uses `inspector_overlay_resources.grd` and produces a `.pak` file.
|
11 | - `inspector_overlay_agent.cc` extracts the modules and inlines them onto the overlay page.
|
12 |
|
13 | ## Inspector overlay constraints
|
14 |
|
15 | Inspector overlay resources are packaged into a single JS file, and, therefore, require all resources like CSS
|
16 | or images to be bundled into JS files. Unlike DevTools themselves, inspector overlay does not have an ability to
|
17 | handle dynamic number of resources because it does not have an embedded server. The backend references a particular
|
18 | bundle using a generated static resource ID. Therefore, inspector overlay is using a custom rollup plugin to bundle
|
19 | CSS and that approach should not be used in DevTools itself because importing CSS this way is not standard and DevTools
|
20 | does not require bundling CSS in JS.
|
21 |
|
22 | ## Local Development
|
23 |
|
24 | To iterate on the overlay UI locally, start a web server in the root folder and open one of the `debug/*.html` files.
|
25 |
|
26 | For example:
|
27 |
|
28 | - `python -m SimpleHTTPServer 8000`
|
29 | - Go to `http://localhost:8000/inspector_overlay/debug/tool_highlight_top_arrow.html`
|
30 | - Run `autoninja -C out/Default` to rebuild.
|
31 |
|
32 | In this mode, JS modules will be served without bundling.
|
33 |
|
34 | ## Importing modules from DevTools
|
35 |
|
36 | It's possible to re-use modules from DevTools for the overlay implementation.
|
37 | To import a module, use the `import` statement with a relative path to the module.
|
38 | It's important to keep the size of the shipped overlay modules minimal so it's better to
|
39 | include only small standalone utilities. The build tooling will also check the size of the
|
40 | generated modules and notify you if they are too big.
|
41 |
|
42 | ## Tests
|
43 |
|
44 | Overlay modules can be unit tested like other parts of DevTools. For an example, see `test/unittests/front_end/inspector_overlay/common_test.ts`.
|
45 |
|
46 | ## Lifecycle of the overlay
|
47 |
|
48 | When the backend installs an overlay bundle, it installs a global `InspectorOverlayHost` object that
|
49 | allows the overlay to communicate with the backend. Then it makes the following calls in order:
|
50 |
|
51 | - `setPlatform('windows'|'mac'|'linux'|'other')` to notify the overlay about the current platform.
|
52 | - `setOverlay(toolName)` to notify the overlay about what tool is currently enabled.
|
53 |
|
54 | Then when the overlay is being painted, the following calls are made by the backend:
|
55 |
|
56 | - `reset(params)` to notify the overlay about actual params of the page such as viewport size, device scale factor and others.
|
57 | - Invokes tool-specific methods such as `drawHighlight`.
|
58 |
|
59 | In the overlay code, these calls are received through a global `dispatch(methodName, ...args)` function. |
\ | No newline at end of file |