Add Web Inspector docs (WIP) #58
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,144 @@ | ||
| # Introduction | ||
|
|
||
| The Web Inspector allows you to view the page source, live DOM hierarchy, script debugging, profiling and more! | ||
|
|
||
| ## Enabling the Web Inspector | ||
|
|
||
| ### Safari | ||
|
|
||
| * Enable the Develop menu option in the Advanced preferences. | ||
| * Use the optional toolbar button, Develop menu or Inspect Element context menu to access the Web Inspector. | ||
|
|
||
| ### Other WebKit clients | ||
|
|
||
| * Find the application's bundle identifier. | ||
| * Enter the following command once in Terminal (inserting the bundle identifier) | ||
|
|
||
| ``` | ||
| defaults write "bundle-identifier-here" WebKitDeveloperExtras -bool true | ||
| ``` | ||
|
|
||
| * Relaunch the application in order to use the Web Inspector | ||
|
|
||
| ## Using the Web Inspector | ||
|
|
||
| The Web Inspector can be opened by '''right clicking anywhere on a web page''' and choosing '''Inspect Element'''. Once open, it highlights the node on the page as it is selected in the hierarchy. You can also search for nodes by node name, id and CSS class name. | ||
|
|
||
| The Node pane shows the current node type and name, as well as any element attributes. | ||
|
|
||
| Under the Style pane we show all the CSS rules that apply to the focused node. These rules are listed in cascade order with overridden properties striked-out—letting you truly see how cascading stylesheets affect the page layout. All shorthand properties have a disclosure-triangle to show and hide the expanded properties created by the shorthand. | ||
|
|
||
| The Metrics pane provides a quick visual look at how margins, borders and padding affect the current node. | ||
|
There was a problem hiding this comment. Metrics are now under the Computed pane. Personally, I would just remove all this info and link to the documentation as a single source of truth to avoid it getting outdated again, but I’m a new contributor so those are just my thoughts. There was a problem hiding this comment. I tend to agree. A paragraph or two about the general scope of Web Inspector is sufficient, then a add a link to the canonical Web Inspector Reference: https://webkit.org/web-inspector/ There was a problem hiding this comment. I would add a question mark in the help links, as it may not be obvious for people unfamiliar with Web Inspector. "help links with a question mark" |
||
|
|
||
| Various HTML and JavaScript properties, including length of text nodes, offsetWidth/Height, class names, and parent/sibling information are vieweable in the Properties pane. | ||
|
|
||
| See [Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html) for more details on other panels of the Web Inspector. | ||
|
There was a problem hiding this comment. This link is out of date and leads to a 404. The most up to date WI documentation is at https://webkit.org/web-inspector/ afaik. There was a problem hiding this comment. There's a overview of Web Inspector at: But I agree, we should point to the Web Inspector Reference at: |
||
|
|
||
| ## Hacking on the Web Inspector | ||
|
|
||
| Most of the Web Inspector's code is HTML, JavaScript, and CSS—so it's very easy to implement new features and fix bugs! | ||
|
|
||
| [List Web Inspector bugs and feature requests](http://tinyurl.com/2vqypl) | ||
|
|
||
| ## Related Blog Posts | ||
|
|
||
| * [Introducing the Web Inspector](http://webkit.org/blog/41/introducing-the-web-inspector) | ||
| * [Yet another one more thing… a new Web Inspector!](http://webkit.org/blog/108/yet-another-one-more-thing-a-new-web-inspector) | ||
| * [Web Inspector Redesign](http://webkit.org/blog/197/web-inspector-redesign) | ||
| * [Web Inspector Updates](http://webkit.org/blog/829/web-inspector-updates/) | ||
| * [State of Web Inspector](https://www.webkit.org/blog/2518/state-of-web-inspector/) | ||
|
|
||
| ## Shortcut Keys | ||
|
|
||
| ### Safari | ||
|
|
||
| | | Mac | Windows / Linux | | ||
| |----------------------------|-------|------------------| | ||
| | Toggle Web Inspector | ⌥⌘I | Ctrl-Alt-I | | ||
| | Show Error Console | ⌥⌘C | Ctrl-Alt-C | | ||
| | Start Profiling Javascript | ⌥⇧⌘P | Ctrl-Alt-P | | ||
|
|
||
| ### Web Inspector | ||
|
|
||
| | | Mac | Windows / Linux | | ||
| |-----------------------------|-----|-----------------| | ||
| | Next Panel | ⌘] | Ctrl-] | | ||
|
There was a problem hiding this comment. This should be This information is quite similar to here. |
||
| | Previous Panel | ⌘[ | Ctrl-[ | | ||
| | Toggle Console | ⎋ | Esc | | ||
| | Focus Search Box | ⌘F | Ctrl-F | | ||
| | Find Next | ⌘G | Ctrl-G | | ||
| | Find Previous | ⇧⌘G | Ctrl-Shift-G | | ||
|
|
||
| ### Console | ||
|
|
||
| | | Mac | Windows / Linux | | ||
| |-----------------------------|----------|-----------------| | ||
| | Next Suggestion | ⇥ | Tab | | ||
| | Previous Suggestion | ⇧⇥ | Shift-Tab | | ||
| | Accept Suggestion | → | Right | | ||
| | Previous Command / Line | ↑ | Up | | ||
| | Next Command / Line | ↓ | Down | | ||
| | Previous Command | ⌃P | | | ||
| | Next Command | ⌃N | | | ||
| | Clear History | ⌘K or ⌃L | Ctrl-L | | ||
| | Execute | ⏎ | Enter | | ||
|
|
||
| ### Elements Panel | ||
|
|
||
| | | Mac | Windows / Linux | | ||
| |-----------------------------|--------|-----------------| | ||
| | Navigate | ↑ ↓ | Up/Down | | ||
| | Expand/Collapse Node | ← → | Right/Left | | ||
| | Expand Node | Double-Click on tag | Double-Click on tag | | ||
| | Edit Attribute | ⏎ or Double-Click on attribute | Enter or Double-Click on attribute | | ||
|
|
||
| ### Styles Pane | ||
|
|
||
| | | Mac | Windows / Linux | | ||
| |-----------------------------------|----------------------------|-----------------| | ||
| | Edit Rule | Double-Click | Double-Click | | ||
| | Edit Next/Previous Property | ⇥ / ⇧⇥ | Tab/Shift-Tab | | ||
| | Insert New Property | Double-Click on whitespace | Double-Click on whitespace | | ||
| | Increment/Decrement Value | ⌥↑ /⌥ ↓ | Alt- Up/Alt-Down | | ||
| | Increment/Decrement Value by 10 | ⌥⇧↑ / ⌥⇧↓ | Alt-Shift-Up/Alt-Shift-Down | | ||
| | Increment/Decrement Value by 10 | ⌥PageUp / ⌥PageDown | Alt-PageUp/Alt-PageDown | | ||
| | Increment/Decrement Value by 100 | ⌥⇧PageUp / ⌥⇧PageDown | Shift-PageUp/Shift-PageDown | | ||
| | Increment/Decrement Value by 0.1 | ⌃⌥↑ / ⌃⌥↓ | Control-Alt-Up/Control-Alt-Down | | ||
|
|
||
| ### Debugger | ||
|
|
||
| | | Mac | Windows / Linux | | ||
| |-------------------------------|--------------|------------------| | ||
| | Select Next Call Frame | ⌃. | Ctrl-. | | ||
| | Select Previous Call Frame | ⌃, | Ctrl-, | | ||
| | Continue | F8 or ⌘/ | F8 or Ctrl-/ | | ||
| | Step Over | F10 or ⌘' | F10 or Ctrl-' | | ||
| | Step Into | F11 or ⌘; | F11 or Ctrl-; | | ||
| | Step Out | ⇧F11 or ⇧⌘; | Shift-F11 or Ctrl-Shift-; | | ||
| | Evaluate Selection | ⇧⌘E | Ctrl-Shift-E | | ||
| | Toggle Breakpoint Condition | Click on line number | Click on line number | | ||
| | Edit Breakpoint Condition | Right-Click on line number | Right-Click on line number | | ||
|
|
||
|
|
||
| ## Using the Web Inspector remotely | ||
|
|
||
| ### Remote Web Inspector on GTK+ and EFL ports | ||
|
|
||
| * For the GTK and EFL ports, this can be enabled with an environment variable. Check the documentation on EnvironmentVariables | ||
|
|
||
|
|
||
| ``` | ||
| Computer1 # export WEBKIT_INSPECTOR_SERVER=${ip.ad.dre.ss}:${port} | ||
| Computer1 # MiniBrowser http://google.com | ||
| # | ||
| Computer2 # MiniBrowser http://${ip.ad.dre.ss}:${port} | ||
| ``` | ||
|
|
||
| * The very same version of WebKit has to be used on the other side | ||
|
|
||
|
|
||
| ### Apple Web Inspector Remote Experiment | ||
|
|
||
| [Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html) | ||
|
There was a problem hiding this comment. I think we can remove the link altogether and keep the other two paragraphs for historical reference. -[Safari User Guide for Web Developers](http://developer.apple.com/safari/library/documentation/AppleApplications/Conceptual/Safari_Developer_Guide/UsingtheWebInspector/UsingtheWebInspector.html) |
||
| In early 2010, an experiment was made to get Web Inspector to run in a plain old web page, debugging a remote web browsing session in another browser window. | ||
|
|
||
| A write-up is available here: | ||
| [weinre - Web Inspector Remote](http://muellerware.org/papers/weinre/manual.html), and the relevant source and demo archives are attached to this page. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| # Contributing to Web Inspector | ||
|
|
||
| ## Modifying the Web Inspector | ||
|
|
||
| The Web Inspector user interface is implemented using JavaScript, CSS, and HTML. So, it's relatively easy to dig into the Web Inspector's sources and fix bugs or add new features. | ||
|
|
||
| This wiki page documents the minimal steps required to modify styles used by the Web Inspector and submit your changes as a patch for review. | ||
|
|
||
| Let's say, we don't like red color for CSS property names, and we would prefer property names to be purple instead. Let's get started! | ||
|
|
||
| ## Inspect The Inspector | ||
|
|
||
| Since the Web Inspector UI is just another web page, we can inspect the Web Inspector with a second-level Web Inspector instance to quickly see what's going on. This requires a few magic settings to enable the "Inspect..." context menu on the Web Inspector window. | ||
|
|
||
| For the Mac port, set the following defaults to allow inspecting the inspector. | ||
|
|
||
| ``` | ||
| defaults write NSGlobalDomain WebKitDebugDeveloperExtrasEnabled -bool YES | ||
|
There was a problem hiding this comment. IDK if this still works but this can now be done from the web inspector UI. There was a problem hiding this comment. That's correct. Developers can now enable "Allow Inspecting Web Inspector" in the Web Inspector Settings > Experimental tab. I don't know if the |
||
| ``` | ||
|
|
||
|
|
||
| After updating these settings, run the [https://developer.apple.com/safari/technology-preview/ Safari Technology Preview]. Then, open the Web Inspector and right-click to inspect the inspector itself. | ||
|
|
||
| By inspecting the CSS property names in the second-level inspector, we quickly find that the colors are defined by rules in `Source/WebInspectorUI/UserInterface/Views/SpreadsheetCSSStyleDeclarationEditor.css`. | ||
| To create and submit a patch with our changes, we must to create an accompanying Bugzilla bug, and compute the diff of our changes against WebKit trunk. | ||
|
|
||
| ## Create / Update a Bug Report | ||
|
There was a problem hiding this comment. I think we already have the content on how to build WebKit elsewhere, but this is not a big deal. |
||
|
|
||
| * [Existing Web Inspector Bugs](https://bugs.webkit.org/buglist.cgi?query_format=advanced&short_desc_type=allwordssubstr&short_desc=&component=Web+Inspector&long_desc_type=substring&long_desc=&bug_file_loc_type=allwordssubstr&bug_file_loc=&keywords_type=allwords&keywords=&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&emailassigned_to1=1&emailtype1=substring&email1=&emailassigned_to2=1&emailreporter2=1&emailcc2=1&emailtype2=substring&email2=&bugidtype=include&bug_id=&votes=&chfieldfrom=&chfieldto=Now&chfieldvalue=&cmdtype=doit&order=Reuse+same+sort+as+last+time&field0-0-0=noop&type0-0-0=noop&value0-0-0=) | ||
|
|
||
| * [Create New Web Inspector Bug](http://webkit.org/new-inspector-bug) | ||
|
|
||
| The WebKit project uses "bugs" in Bugzilla for fixes, new features, and any other code changes. Every commit must have an accompanying Bugzilla bug. | ||
|
|
||
| So, the first step is to ensure that your proposed enhancement or fix has an associated bug. | ||
|
|
||
| Once you find or create a bug report, make sure to add a comment stating your intent to work on the bug. | ||
| This step is very important; comments on bugs in the Web Inspector Bugzilla component will automatically notify Web Inspector reviewers. | ||
|
|
||
| This will allow them to answer any questions you may have about a proposed fix, and give feedback, pointers, and guidance for solving the issue. | ||
|
|
||
| ## Now Do Your Hacking | ||
|
|
||
| 1. [Get the Code](https://webkit.org/getting-the-code/) | ||
|
|
||
| ``` | ||
| git clone https://github.com/WebKit/WebKit.git WebKit | ||
| cd WebKit | ||
| git checkout -b purple_css_values | ||
| ``` | ||
|
|
||
| 2. [Build WebKit](http://webkit.org/building/build.html) | ||
|
|
||
| ``` | ||
| Tools/Scripts/build-webkit --release | ||
| ``` | ||
|
|
||
| A clean build takes 20-80 minutes depending on the vintage of your machine. | ||
|
|
||
| 3. [Run it](http://webkit.org/building/run.html) | ||
|
|
||
| ``` | ||
| Tools/Scripts/run-minibrowser --release | ||
| ``` | ||
|
|
||
| 4. Edit `Source/WebInspectorUI/UserInterface/Views/SpreadsheetCSSStyleDeclarationEditor.css` within the repo. | ||
|
|
||
| 5. Run `make -C Source/WebInspectorUI release` to copy files from `Source/WebInspectorUI/UserInterface` to the build directory. Do it after every time you modify Inspector's files. | ||
|
There was a problem hiding this comment. This is super helpful though. We should keep this. |
||
|
|
||
| 6. Look at your changes | ||
|
|
||
| ``` | ||
| git status | ||
| git diff Source/WebInspectorUI/ | ||
| ``` | ||
|
|
||
| 7. [Submit a PR](https://webkit.org/contributing-code/#overview) and wait for a review! | ||
|
|
||
| ``` | ||
| git add -u | ||
| git commit | ||
| Tools/Scripts/git-webkit pull-request | ||
| ``` | ||
|
|
||
| If you have any questions there are always people willing to help! Just jump onto [webkit.slack.com](https://webkit.slack.com), #webkit-inspector channel. | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| # Using the Remote Inspector with WebKitGTK+ and WPE | ||
|
|
||
| The remote inspector enables debugging of web pages in environment where you might not be able to run the web inspector directly, such as WPE running in embedded targets. | ||
|
|
||
| To run the remote inspector, you need to: | ||
|
|
||
| - set the environment variable `WEBKIT_INSPECTOR_SERVER=ip:port` before running jsc or a browser/launcher powered by WPE or WebKitGTK+ | ||
| - enable the WebKitSettings `enable-developer-extras` | ||
|
|
||
| For example: | ||
|
|
||
| ``` | ||
| export WEBKIT_INSPECTOR_SERVER=192.168.0.50:5000 | ||
| MiniBrowser --enable-developer-extras=true https://wpewebkit.org | ||
| ``` | ||
|
|
||
| Then, open another browser with the same version of WebKitGTK+ (matching the WPE version if it's the case) and open `inspector://ip:port`: | ||
|
|
||
|
|
||
| ``` | ||
| MiniBrowser inspector://192.168.0.50:5000 | ||
| ``` |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.