valence-content-kit.md

Valence Content Kit

Current as of Valence 0.2.4

Introduction

Valence is the public-facing name for the Firefox Developer Tools Adapters, which extend the Firefox WebIDE to allow for remotely debugging pages in Chrome or Safari from within the Firefox Developer Tools. Valence is distributed as an add-on which is automatically downloaded and installed by Firefox Developer Edition, though the raw .xpi file is available on ftp.mozilla.org and its source code is on GitHub.

Valence debuted with Firefox Developer Edition on November 10th, 2014, and was developed under the nickname "fever dream."

Key Points

1. Learn and use one set of tools to debug the whole web, regardless of platform, device, or rendering engine.

2. Currently focusing on mobile web: Chrome for Android and Mobile Safari (iOS). Desktop Chrome is also supported.

3. Already usable for basic layout / CSS work, but not yet suitable for JavaScript debugging or advanced frontend work.

4. Unfinished and highly experimental, "but we care enough about this problem that we’re going to do what it takes to keep it going." Pull requests welcome.

5. Part of a broader effort to make the WebIDE suitable for general web development, not just Firefox OS apps.

Reference Materials

Valence:

• Source code: github.com/campd/valence
• Issue tracker: github.com/campd/valence/issues
• Builds: ftp.mozilla.org/pub/mozilla.org/labs/fxdt-adapters
• Docs: developer.mozilla.org/docs/Tools/Valence

Developer Tools:

• Docs: developer.mozilla.org/docs/Tools
• Wiki: wiki.mozilla.org/DevTools
• Feedback: ffdevtools.uservoice.com or mzl.la/devtools

Developer Edition:

• Landing: mozilla.org/firefox/developer
• Docs: developer.mozilla.org/Firefox/Developer_Edition

Presentation Setup and Materials

For any presentation:

• Internet connection for every device in the demo
• Backup plan if the network is down (local server, hotspot, pre-recorded videos, etc.)

If demoing on actual hardware (iOS or Android):

• Strategy for projecting your device's screen (USB webcam, document camera, etc.)
• Correct USB cable for the device
• Remote debugging enabled
  • iOS: Settings → Safari → Advanced → Web Inspector
  • Android: Settings → Developer → USB Debugging
• Sleep and screen lock disabled

If demoing on the iOS Simulator:

• Xcode installed and updated
• Simulator installed and launches

If demoing on Chrome for desktop:

• Launched Chrome with --remote-debugging-port=9222

  On OS X, the following command launches a temporary instance of Chrome with remote debugging enabled:

    open -na 'Google Chrome' --args  \
        --remote-debugging-port=9222 \
        --no-first-run               \
        --no-default-browser-check   \
        --user-data-dir=$(mktemp -d -t 'chrome-remote_data_dir')
  

Demoing: Things that are Broken

As mentioned above, Valence is still an in-development experiment. Many features are broken or incomplete. For instance, you only get a subset of panels, compared to working locally in Firefox.

Specifically, the following panels are missing when using Valence: Performance, Timeline (#16), Network, Storage, Web Audio, Canvas, and the Shader Editor.

Disconnecting and reconnecting from a browser, idling for a very long time (#86), or navigating in an attached debugging session (#13) may break the whole suite of tools and require restarting the WebIDE and target browser.

Notable limitations of the remaining panels include:

Inspector

Mostly functional, except for:

• No "font" subpane
• No "animations" subpane
• Hovering over background-image values doesn't show a thumbnail of the image
• Links from rules to their source stylesheet don't work (they all point to line "-1")
• No event handler indicators attached to DOM nodes (#24)

Console

Mostly broken, including:

• Doesn't log network requests, css issues, or really much of anything
• No auto-complete
• Not responsive or reliable. Commands tend to execute only after long pauses, if at all

Debugger

Mostly broken, including:

• Automatically pretty printing / black boxing minified sources doesn't work (#92)
• Neither stepping through code nor moving around in the call stack work properly.
• Watch expressions don't work.

Style Editor

Mostly functional, except for:

• Toggling visibility of stylesheets
• The New / Import buttons
• No "media query" sidebar

Scratchpad

Mostly functional, except for:

• Slow or no response to JavaScript execution

Demoing: The Good Parts

Introduction / Setup

1. Open a browser on your target platform with two tabs: XKCD (1195: Flowchart or 1144: Tags) and TodoMVC (Vanilla JavaScript).

   XKCD is great because it's a real world page with relatively simple markup. A small, single-pane comic is best as it avoids distracting the audience or taking up too much space on screen.

   TodoMVC will be familiar to most frontend developers, it's well designed, and it tends to have clean code.

2. Open the WebIDE

   WebIDE started as a tool for developing Firefox OS applications. Valence is a step toward making it a more general purpose editor for the Web.

3. Connect to your target platform

   Note the option to install Firefox OS simulators, if the audience is interested in that.

4. Show how tabs appear under the "Open App" menu.

   The "App" label is from the WebIDE's origin as a tool for Firefox OS app development.

Inspector

Goal: Demonstrate the basic use of the Inspector pane for examining, selecting, modifying, and restyling objects in the DOM. Use XKCD for the demo (bring that tab to the front on-device, then open it in the WebIDE).

Manipulating the DOM

1. Hover over various elements and observe the browser screen.

   This shows that the box model highlighter works. E.g., on #middleContainer or #topLeft (inside #topContainer), the green strip represents padding.

   You can also select one DOM node and then use arrow keys to navigate.

2. Expand the #ctitle element inside #middleContainer, double click on the text content, edit it, and then click outside.

   This shows that content can be changed, and it updates immediately on device.

   You can also edit the div's id to show that properties can be modified, too.

3. Right click on #topContainer and "Edit as HTML." Change the "Blag" link to say "Blog." Click outside to apply the change.

   This shows how to edit large chunks of content or deeply nested trees.

Editing Styles

1. Scroll down in the page, select #bottom in the WebIDE, then point out the CSS sidebar.

   You can see what CSS rules apply to the element, and where they came from.

2. Toggle padding off and on by clicking the checkbox next to that rule.

   Content updates immediately.

3. Click on the padding value (25px 15px) and change the numbers.

   The content updates immediately, without waiting for you to click out of the editor field.

4. Click on the little color swatch next to the background rule. Drag the sliders around.

   Notice that the values update immediately both in the style inspector and on the page.

   When you drag the transparency bar, the color automatically changes to rgba(...) instead of #rrggbb.

Picking Elements

1. Click the "pick an element" button (on the far left of the Inspector / Console / Debugger / etc. toolbar), then tap the comic on the device.

   Wow! The inspector has now highlighted the appropriate DOM node!

2. Ensure the img tag is expanded / visible and hover over its src attribute.

   Note the image thumbnail.

Style Editor

Goal: Demonstrate using the Style Editor to make freeform changes to CSS.

1. Switch to the Style Editor tab, select the main stylesheet, then change the body's background color to rebeccapurple.

   If you pause after typing "re" you'll see an auto-completion prompt for the color. The arrow keys switch between entries.

2. Save the modified stylesheet to disk in an arbitrary location.

   Normally, you'd save this back into your project directory.

3. Change the body's text-align to left, click save again.

   There's no location prompt; the destinations for each stylesheet are temporarily remembered during your session.

4. Reset the page by clicking the refresh button in the WebIDE toolbar.

   Reloading the page has a side effect of discarding local changes from the style editor.

Console

Currently extremely unreliable. Demoing not recommended. However, if you manage to get it working, you should be able to show off a few things with XKCD open:

1. Run document.querySelectorAll('body > div'). Hover over a result to see it highlight in content.

   This shows that the console output isn't inert.

2. Click on a tag in the NodeList to open up the DOM properties subpanel. Hover over its children members.

   This shows how to inspect a node's DOM properties, as well as demonstrating that the DOM properties panel is interactive.

3. Click on the target next to a node in the NodeList.

   This shows how you can quickly go from the console to selecting an element in the Inspector.

Debugger

Currently very limited. Demoing not recommended, but you can do a few interesting things with TodoMVC:

1. Add a few todo items.

   Just for the sake of having content.

2. Set a breakpoint inside the function body for newTodo in controller.js, then try to add another item.

   The breakpoint worked and execution paused, giving you a moment to inspect the application's state.

   If things are working, there should be a few entries in the Call Stack subpanel, as well as information in the Variables subpanel.

3. Click "Step Out" to resume execution, toggle the breakpoint in the Sources list, and try to add another item.

   This shows that breakpoints can be enabled or disabled quickly, without removing them altogether.

   The button in the far bottom left can also be used to enable or disable all breakpoints in the application.

Frequently Asked Questions (FAQs)

What about Chrome for iOS?

Apple requires that all mobile browsers use iOS's built-in version of WebKit instead of their own engines. This means that Google cannot ship Blink or V8 on iOS, and is instead embedding an iOS web view and wrapping it in the Chrome interface. Because the internals are the same, debugging in Mobile Safari should yield identical results.

What about Internet Explorer?

Nice to have, but no current timeline. Pull requests welcome! Current focus is on the mobile web, which is dominated by Chrome on Android and Safari on iOS.

Do I have to wait for new Firefox releases to get updates?

No. Because Valence is distributed as a separate add-on, you'll get updates as soon as they're ready.

Do I need a Mac to debug content on iOS?

No. Valence makes it possible to debug content on an iPhone or iPod Touch without owning a Mac.

We should link to bugs on file, or maybe the commit hash of when this content kit was written, that way as bugs are fixed we can update this to reflect when a previously broken feature is fixed.