UIZE JavaScript Framework

GUIDES Javascript Bookmarklets

1. Introduction

This document assumes that you are already familiar with bookmarklets, how to set them up in your Web browser(s), and how to use them.

This document provides additional tips, along with some useful bookmarklets that should come in handy when doing development using the UIZE JavaScript Framework.

2. Useful Troubleshooting Bookmarklets

The bookmarklets described in this section serve as useful troubleshooting aids when developing Web applications using UIZE.

2.1. DELVE Bookmarklet

The DELVE Bookmarklet launches the DELVE tool in a separate window, set to inspect the Web page that is loaded in the active tab of the window where the bookmarklet was used.

BOOKMARKLET


DELVE  ← drag the link to your bookmarks toolbar (or click it to try it now)

The DELVE tool can be used to delve into the inner workings of pages that use the UIZE JavaScript Framework. For more information on the DELVE tool, see the guide Using the DELVE Tool.

To use the bookmarklet, follow these simple steps...

1.  Navigate in your Web browser to a page that you would like to inspect.
2.  Launch the bookmarklet. Move the DELVE window out of the way so that it doesn't obscure the Web page you are inspecting. If you're lucky enough to be developing using two monitors, move the DELVE window to your secondary monitor and put it into full screen mode for maximum viewing pleasure.
3.  Use DELVE to delve into what's going on in the page you're inspecting. If you're a first time user of DELVE and are not familiar with its features, read the guide Using the DELVE Tool to learn more about it.

BOOKMARKLET SOURCE CODE

(function () {
  var
    _screen = window.screen,
    _width = _screen.width - 50,
    _height = _screen.height - 100,
    _html =
      [
        '<html>',
          '<head><title>DELVE</title></head>',
          '<body>',
            '<script src="http://www.uize.com/js/Uize.js"></script>',
            '<script type="text/javascript">',
              'Uize.require (',
                '\'UizeSite.DelvePageWriter\',',
                'function (_DelvePageWriter) {',
                  '_DelvePageWriter.initialize ();',
                '}',
              ');',
            '</script>',
          '</body>',
        '</html>'
      ].join ('\n'),
    _window = window.open (
      'javascript:\'' + _html.replace (/'/g,'\\\'') + '\'',
      'reportPopup',
      [
        'width=' + _width,
        'height=' + _height,
        'left=' + Math.max ((_screen.width - _width - 10) >> 1,0),
        'top=' + Math.max ((_screen.height - _height - 40) >> 1,0),
        'toolbar=no',
        'location=no',
        'directories=no',
        'status=no',
        'menubar=no',
        'resizable=yes',
        'scrollbars=no'
      ].join (',')
    )
  ;
  _window.focus ();
}) ();

2.2. Module Reference Bookmarklet

BOOKMARKLET


MODULE REFERENCE  ← drag the link to your bookmarks toolbar (or click it to try it now)

BOOKMARKLET SOURCE CODE

(function () {
  var _moduleName = prompt ('Enter a module name (e.g. Uize.Array.Sort)...','');
  if (_moduleName) {
    var
      _width = 1000,
      _height = 750,
      _screen = window.screen,
      _window = window.open (
        'http://www.uize.com/reference/' + _moduleName + '.html',
        'uizeReference',
        [
          'width=' + _width,
          'height=' + _height,
          'left=' + Math.max ((_screen.width - _width - 10) >> 1,0),
          'top=' + Math.max ((_screen.height - _height - 40) >> 1,0),
          'toolbar=no',
          'location=no',
          'directories=no',
          'status=no',
          'menubar=no',
          'scrollbars=yes'
        ].join (',')
      )
    ;
    _window.focus ();
  }
}) ();

2.3. Built Modules Bookmarklet

The Built Modules Bookmarklet provides an easy way to see a list of all the JavaScript modules that have been built for the Web page in which the bookmarklet is used.

BOOKMARKLET


BUILT MODULES  ← drag the link to your bookmarks toolbar (or click it to try it now)

When you're on a Web page that is using the UIZE JavaScript Framework, using the Built Modules Bookmarklet will open a popup browser window containing a list of all the JavaScript modules built for the page, listed in the correct order of dependency. This might come in handy from time to time when you're unsure of what modules are loaded on a page, suspicious of what modules might be loaded that don't need to be loaded, or just curious about what's used on what kinds of pages.

The set of modules built for a page approximately reflects what modules the page uses, although there might be modules that are incorrectly required, or not in use because of the page's current state. Perusing the list of built modules might provide some clues to potential issues lurking in the code. When you want to know this information, the bookmarklet should be a more convenient approach than digging in the page's HTML or Firebug's DOM inspector, especially if modules are being scrunched together into single external JS library files, or even inlined in the page by a server-side dependency resolution mechanism.

BOOKMARKLET SOURCE CODE

(function () {
  function _showReport (_report) {
    var
      _width = 500,
      _height = 600,
      _screen = window.screen,
      _window = window.open (
        '',
        'reportPopup',
        [
          'width=' + _width,
          'height=' + _height,
          'left=' + Math.max ((_screen.width - _width - 10) >> 1,0),
          'top=' + Math.max ((_screen.height - _height - 40) >> 1,0),
          'toolbar=no',
          'location=no',
          'directories=no',
          'status=no',
          'menubar=no',
          'scrollbars=yes'
        ].join (',')
      ),
      _document = _window.document
    ;
    _document.open ('text/html');
    _document.writeln (
      '<html><body><pre>' + _report.replace (/</g,'&lt;') + '</pre></body></html>'
    );
    _document.close ();
    _window.focus ();
  }
  var _modulesBuilt = Uize.getModulesBuilt && Uize.getModulesBuilt ();
    /* NOTE: Uize.getModulesBuilt is deprecated */
  if (!_modulesBuilt) {
    _modulesBuilt = [];
    var _modulesByName = Uize.getModuleByName ('*');
    for (var _moduleName in _modulesByName) _modulesBuilt.push (_moduleName);
  }
  _showReport (_modulesBuilt.join ('\n'));
}) ();

2.4. Lookup Widget From Node ID Bookmarklet

The Lookup Widget From Node ID Bookmarklet makes it easy to look up a widget on a Web page from the id of a DOM node, and see a detailed report containing the widget's full dereferencing path, the widget's class, its parentage information, and a summary of its state.

BOOKMARKLET


GET WIDGET FROM NODE ID  ← drag the link to your bookmarks toolbar (or click it to try it now)

You might be troubleshooting some issue on a page and you're digging through the HTML and find some node of interest. You can also use Firebug's Inspect Element feature to click on and select some node of interest. If the node has an id that makes it look like it's a DOM node of some widget in the widget tree for the page, then you can use this bookmarklet to find the widget that owns the node.

To use the bookmarklet, follow these simple steps...

1.  Locate the node of interest that you believe belongs to a widget, either by viewing the source of the page or by using a tool such as Firebug.
2.  Grab the id for the DOM node of interest and provide it to the bookmarklet. Copy the node's id, then launch the bookmarklet (which can be on your browser toolbar somewhere). Enter the node id in the prompt that pops up.
3.  Upon entering the node's id and hitting enter, the bookmarklet will scan through the page's widget tree to find the widget to which the node belongs. If it finds the widget, it will display a report in a popup window. The report will contain such information as the full dereferencing path for the widget (which you can copy-and-paste into Firebug's console, or otherwise use for further debugging goodness), the widget's class, parentage information for the widget, and a summary of the state of the widget's state properties.

2.4.1. Page Widget Expected

This bookmarklet assumes that the page has a single page widget instance that contains the page's widget tree, and that the page widget instance is accessible by a global identifier named either page (as is the general convention) or zPage (as is the convention for Zazzle's Web site).

If you wish to use this bookmarklet for a site that uses a different global identifier for the page widget instance on its pages, then you should create your own edited version of the bookmarklet and scrunch it using the JavaScript Scruncher tool.

BOOKMARKLET SOURCE CODE

(function () {
  function _showReport (_report) {
    var
      _width = 950,
      _height = 700,
      _screen = window.screen,
      _window = window.open (
        '',
        'reportPopup',
        [
          'width=' + _width,
          'height=' + _height,
          'left=' + Math.max ((_screen.width - _width - 10) >> 1,0),
          'top=' + Math.max ((_screen.height - _height - 40) >> 1,0),
          'toolbar=no',
          'location=no',
          'directories=no',
          'status=no',
          'menubar=no',
          'scrollbars=yes'
        ].join (',')
      ),
      _document = _window.document
    ;
    _document.open ('text/html');
    _document.writeln (
      '<html><body><pre>' + _report.replace (/</g,'&lt;') + '</pre></body></html>'
    );
    _document.close ();
    _window.focus ();
  }
  var _pageWidget = window.zPage || window.page;
  if (_pageWidget) {
    var _nodeId = prompt ('Enter a DOM node id...','');
    if (_nodeId) {
      function _findWidgetWithIdPrefix (_parent) {
        if (_parent.get ('idPrefix') == _idPrefix) {
          return _parent;
        } else {
          var _children = _parent.children;
          for (var _childName in _children) {
            var _widget = _findWidgetWithIdPrefix (_children [_childName]);
            if (_widget) return _widget;
          }
        }
      }
      function _getWidgetPath (_widget) {
        var _widgetPath = [];
        while (_widget) {
          _widgetPath.unshift (
            _widget == _pageWidget
              ? (_pageWidget == window.zPage ? 'zPage' : 'page')
              : _widget.get ('name')
          );
          _widget = _widget.parent
        }
        return _widgetPath.join ('.children.');
      }
      var
        _nodePos = _nodeId.indexOf ('-'),
        _idPrefix = _nodePos > -1 ? _nodeId.slice (0,_nodePos) : _nodeId,
        _widget = _findWidgetWithIdPrefix (_pageWidget),
        _parent = _widget.parent,
        _parents = []
      ;
      while (_parent) {
        _parents.push (
          _getWidgetPath (_parent) +
          '  --  WIDGET CLASS: ' + _parent.constructor.moduleName
        );
        _parent = _parent.parent;
      }
      if (_widget) {
        var _divider = '\n---------------------------------------------------------\n\n';
        _showReport (
          'WIDGET PATH: ' + _getWidgetPath (_widget) + '\n' +
          'WIDGET CLASS: ' + _widget.constructor.moduleName + '\n' +
          _divider +
          'WIDGET PARENTAGE:\n\n' +
          (_parents.length ? _parents.join ('\n') + '\n' : 'no parents\n') +
          _divider +
          'WIDGET STATE SUMMARY:\n\n' + _widget.toString ()
        );
      } else {
        alert (
          'The DOM node with the ID "' + _nodeId + '" does not appear belong to a widget.'
        );
      }
    }
  } else {
    alert ('This page doesn\'t have a page widget instance named "page" or "zPage".');
  }
}) ();

2.5. Flattened Widget Tree Bookmarklet

The Flattened Widget Tree Bookmarklet produces a report of all the widgets in the widget tree hierarchy for a Web page, in the form of a flattened list.

BOOKMARKLET


FLAT WIDGET TREE  ← drag the link to your bookmarks toolbar (or click it to try it now)

When you use this bookmarklet on a page that has a page widget instance, the bookmarklet will traverse the entire widget tree for the page and produce a flattened list of all the widgets in a popup window. Each entry in the list is a full dereferencing path, which you can copy-and-paste into Firebug's console (or otherwise use) for further debugging goodness.

BOOKMARKLET SOURCE CODE

(function () {
  function _showReport (_report) {
    var
      _screen = window.screen,
      _width = 500,
      _height = 600,
      _window = window.open (
        '',
        'reportPopup',
        [
          'width=' + _width,
          'height=' + _height,
          'left=' + Math.max ((_screen.width - _width - 10) >> 1,0),
          'top=' + Math.max ((_screen.height - _height - 40) >> 1,0),
          'toolbar=no',
          'location=no',
          'directories=no',
          'status=no',
          'menubar=no',
          'scrollbars=yes'
        ].join (',')
      ),
      _document = _window.document
    ;
    _document.open ('text/html');
    _document.writeln (
      '<html><body><pre>' + _report.replace (/</g,'&lt;') + '</pre></body></html>'
    );
    _document.close ();
    _window.focus ();
  }
  var _pageWidget = window.zPage || window.page;
  if (_pageWidget) {
    var _widgets = [];
    function _processWidget (_widget,_widgetPath) {
      _widgets.push (
        _widgetPath += _widget == _pageWidget
          ? (_pageWidget == window.zPage ? 'zPage' : 'page')
          : _widget.get ('name')
      );
      _widgetPath += '.children.';
      var _children = _widget.children;
      for (var _childName in _children)
        _processWidget (_children [_childName],_widgetPath)
      ;
    }
    _processWidget (_pageWidget,'');
    _showReport (_widgets.join ('\n'));
  } else {
    alert ('This page doesn\'t have a page widget instance named "page" or "zPage".');
  }
}) ();