Jash: JavaScript Shell

A Cross-Browser Javascript Command-Line Debugging Tool

Documentation

  1. Technical Documentation (JsDoc output)

    Technical documentation on every single method can be found in the JsDoc section.

  2. Installation

    Installation of Jash is fairly straightforward, and involves just a few steps: copying source code, modifying configuration information, placing source code on a web server, and creating a script tag or bookmarklet to use it.

    • Copying source code

      To get the latest version of Jash source code, visit the download page.

    • Hosting source code

      You will need to place the Jash source code (Jash.js and Jash.css) in a public directory on a web server in order to host it. You can use a web server on your computer or you can use a public web server if you have access to one.

    • Changing configuration information

      After downloading the source and moving it to your server, you should change a few variables in the Jash.js file in order to reflect its new location.

    • Installing bookmarklet

      Installing a bookmarklet is as simple as creating a new bookmark (or "favorite") in the browser of choice and pasting the following URL in the location field, replacing {YOUR_SERVER_URL} with the location you uploaded the Jash source files:

      javascript:(function(){document.body.appendChild(document.createElement('script')).src='{YOUR_SERVER_URL}/Jash.js';})();

      You can then load Jash on any page by simply clicking on this bookmarklet. The bookmarklet simply adds a new script tag to your page and sets the source to the URL where Jash can be found.

    • Using a script tag

      You can also source in Jash by embedding a script tag on the page you wish to debug. This is required if you wish to debug scripts that run before or during the window.load event. The script tag should simply refer to the location in which you have uploaded the Jash source code:

      < script type="text/javascript" src="{YOUR_SERVER_URL}/Jash.js">< /script>
  3. Usage

    • Command-line Javascript

      To evaluate arbitrary Javascript, enter the code you wish to evaluate into the input console by typing or copying and pasting your command(s) and pressing the Enter key. You may also evaluate input by clicking on the "Evaluate" button or using the "Evaluate" button's access key stroke (see Hotkeys).

    • Inspecting Objects using jash.dump() and jash.show()

      • jash.dump()

        To quickly see all of the members of a particular Object, you can pass the object into the Jash.dump() function. For example, typing this simple command into the input console and pressing the Enter key will show all of the members of the window object (i.e. all objects, functions, variables in the global scope):

        jash.dump(window);

        The jash.dump() function will show as much as possible about the members of an object. If the member is a function that is native to the browser (such as alert()), Jash can only show that it is native code (i.e. cannot show the internal workings of the function). Environmental functions and variables, though, are fully expanded to show their values.

        jash.dump() does not expand child members that are Objects - though you can then pass such an object into jash.dump() to see its members.

      • jash.show()

        The show() method will only display an object's members and their types (i.e. function, object, number, etc.). This can be more useful than using dump() when inspecting objects with many members (such as the window object).

    • CSS entry mode

      1. How CSS entry mode works

        CSS entry mode takes advantage of the DOM stylesheet capabilities of the supported browsers in order to add new style rules to the document.

        It is important to note that CSS entry in Jash is only additive. When entering new style rules into the console, the rules are added to the DOM; previous CSS entries are not overwritten or deleted.

        CSS entry is currently supported in IE6+ (Windows) and FF1.5+ (Windows, Mac, Linux). Due to DOM incompatibilities, this feature is not supported in Safari or Opera at the time of this writing.

      2. Evaluating css

        To evaluate CSS, one must first enable CSS entry mode (using the hotkey combination or by pressing the button). Once activated, arbitrary CSS can be entered into the console and evaluated.

        body { background: pink; }
        a { color: blue; }
        div.myThing { filter:alpha(opacity=30); text-indent: 30px; _padding-left: -230px; }
        						

        Unlike Javascript entry mode, CSS entry mode allows for multiple lines to be typed in - i.e. pressing the Enter key while the cursor is in the input area does not evaluate the CSS. To evaluate the input, the Evaluate button must be clicked or the Evaluate hotkey combination must be entered on the keyboard.

        There is no limitation on what kind of CSS rules can be entered into the input console in CSS entry mode. Any CSS entry that is valid CSS will be successfully added to the DOM.

        CSS rules are added to the bottom of the document's list of stylesheets, after all other existing rules.

      3. Clearing css entries

        In Firefox, clearing custom CSS entries from the DOM is as simple as turning CSS entry mode off (by clicking on the CSS entry mode button or by using the CSS entry mode hotkey combination). When you turn on CSS entry mode once again, the rules you entered before will reapply to the current document.

        Unfortunately, there is no way to turn on / off custom rules in Internet Explorer.

        To clear all CSS rules entered on the page altogether, you must reload the page.

    • Hotkeys (i.e., Access Keys)

      The use of hotkey combinations makes using Jash a much easier proposition. For example, using the hotkey combination to enable/disable the mouseover DOM inspector makes perfect sense when you wish to capture the element underneath the mouse cursor. The following is a list of the supported hotkey combinations in Jash.

      Hotkeys take advantage of the accessKey property of HTML nodes; therefore, the key combinations used for hotkeys will vary from browser to browser. Quick reference tables have been constructed below for your reference.

      1. General
        Internet Explorer Firefox / Win Firefox / Mac Firefox / Linux Opera Function
        ESC ESC ESC ESC ESC show/hide Jash
        Alt-Z Alt-Shift-Z Ctrl-Z Alt-Z Shift-Esc-Z Evaluate input
        Alt-X Alt-Shift-X Ctrl-X Alt-X Shift-Esc-X Activate/deactivate DOM inspector
        Alt-A Alt-Shift-A Ctrl-A Alt-A Shift-Esc-A Activate/deactivate innerHTML dump (only works w/ DOM inspector)
        Alt-C Alt-Shift-C Ctrl-C Alt-C Shift-Esc-C Clear output
        Alt-S Alt-Shift-S Ctrl-S Alt-S Shift-Esc-S Alt-S toggle CSS entry mode on / off
      2. Javascript Entry Mode
        Key stroke (All Browsers) Function
        up arrow retrieve last input
        down arrow retrieve next input
        Enter Evaluate input
        Tab auto-complete input
      3. CSS Entry Mode
        Key stroke (All Browsers) Function
        Tab (while typing selector only) auto-complete class name or id
    • Using the DOM mouseover tool

      The DOM mouseover tool allows you to quickly see the parent nodes of any "top layer" HTML element. In addition, it captures the element under the mouse pointer in scope and places a reference to it in the input console. This provides the ability to quickly grab an element and manipulate it as you wish.

      1. Activating and using DOM mouseover

        To activate the DOM mouseover tool, click on the "Mouseover DOM" button or use the Mouseover Dom hotkey combination (see the Hotkeys section).

        When the tool is active, you may hover your mouse over any element on a web page to see information about that element's parent tree. The tool also displays a basic set of attributes: id, class name, and href (when hovering over anchors).

        You may also view a "prettified" (tab-indented) version of the innerHTML property of any element by switching on the InnerHTML Dump feature (see below).

      2. Storing element under mouse pointer

        To capture the current element - in other words, to pause the tool - simply enter the hotkey combination for the mouseover tool once again to toggle it off.

    • InnerHTML Dump

      The InnerHTML Dump feature provides a properly-indented, readable view of an element's innerHTML property.

      • Activating and using InnerHTML Dump
      • Caution
    • Tab-completion

      When pressing the tab key after the current javascript input, Jash attempts name completion of the item in the scope of the browser window. It attempts to complete javascript objects, functions, element ids, and element class names. This feature allows extremely quick visibility into the guts of the Javascript and/or DOM on a particular page.

      1. Javascript object completion

        In Javascript entry mode (i.e., the default mode), one can enter a partial name of a function, object, or variable and press tab to attempt tab completion. If multiple matches are found, an alphabetized list of possible matches will be listed in the output console after pressing tab. If only one match is found, it will automatically be entered into the input console. If multiple matches are found but all begin with the same series of characters, that series will be entered into the input console and a list of matches will display in the output console.

      2. HTML element id, class name completion in Javascript Mode
      3. HTML element id, class name completion in CSS Mode
      4. A word about scope
      5. How to add your custom HTML element id, class name function
    • Showing/hiding Jash

      Jash can be hidden by pressing the Escape (Esc) key, by clicking on the "X" button at the top right of the Jash console, or by clicking on the "Hide" button. When Jash is hidden, it can only be shown again by using the bookmarklet once again or by pressing the Escape key again.

    • Retrieving input history

    • Using the Jash.Profiler object (execution timer)

      1. Simple function profiling
      2. Profiling loops
    • Using the StopWatch object

    • Integrating Jash into your script as a debugger

      1. Basic integration using bookmarklet
      2. Fully integrating Jash into your environment
      3. A note about coding style
  4. Customizing Jash

    • Skinning Jash with your own CSS

      By default, Jash uses a css file (Jash.css) to control its appearance. You can change the location of the css file by copying Jash to your own server (or desktop computer) and changing the "jashRoot" property (in Jash.js or Jash_source.js) to point to the folder containing your version of Jash.css. You must then reference your local copy of Jash.js in your bookmarklet.

  5. Reporting bugs

    At the moment, Jash is a one-man operation. Please send any bugs via email to billy dot reisinger at gmail dot com.

  6. Feature requests

    At the moment, Jash is a one-man operation. Please send any feature requests via email to billy dot reisinger at gmail dot com.