Documentation

Welcome to the Glimpse Documentation! Here we hope to introduce you to the various tutorials, concepts and APIs you might need when discovering and using Glimpse.

NOTE: Glimpse docs are currently being improved. If you'd like to help out, just edit this page or contribute to our GitHub Wiki

Platform Basic Port

When trying to create a server port, these are some basic concets that you can use to get up to speed.

Injecting the Client

To add Glimpse to a page, you need to include glimpse.js within the page's HTML. This loads the Glimpse client, which can then be activated by clicking the Glimpse icon in the bottom-right corner.

If you just include glimpse.js, Glimpse won't have any data to show. As a simple example, the following JavaScript will create a Request tab in Glimpse, populated with data from window.location:

glimpse.data.initData({
    data: {
        "Request": {
            name: 'Request',
            data: {
                url: location.href,
                protocol: location.protocol,
                host: location.host,
                pathname: location.pathname,
                search: location.search,
                hash: location.hash
            }
        }
    }
});

You can see other examples of how to pass data into the Glimpse client here.

Building the Backend

One way of passing data from the server to the client is to assign each request a unique ID, which we'll refer to as <request-id>. During the handling of that request, the server should store any data you want to display in the Glimpse client. There should be an HTTP endpoint so that the data associated with the request can be fetched using JSONP. For instance, you might make the request data for a specific request available at /glimpse/request/<request-id>?callback=someFunction. A simple response might look something like:

someFunction({
    "data": {
        "Request": {
            "name": "Request",
            "data": {
                "url": "http://example.com/search?q=4#result-2",
                "protocol": "http",
                "host": "example.com",
                "pathname": "/search",
                "search": "q=4",
                "hash": "result-2"
            }
        }
    }
});

Whenever an HTML page is rendered, intercept the response and add a <script> tag for glimpse.js just before the closing </body> tag, as well as a <script> tag for fetching the associated request. For instance:

    <script src="/glimpse/glimpse.js"></script>
    <script src="/glimpse/request/<request-id>?callback=glimpse.data.initData"></script>
  </body>
</html>

As a minimal example, that's it!

If you want to include some metadata for the Glimpse client, it's generally best to add this as a separate JSONP request since it can be cached (unlike the request-specific data). For instance, assuming the meta-data endpoint already exists:

    <script src="/glimpse/glimpse.js"></script>
    <script src="/glimpse/metadata?callback=glimpse.data.initMetadata"></script>
    <script src="/glimpse/request/<request-id>?callback=glimpse.data.initData"></script>
  </body>
</html>

Using this approach, the data for each request needs to kept available for some time after the request has already been handled. Since keeping data for all requests in memory is likely to be impractical, a simple solution is to keep the request data in a circular buffer. In other words, keep the request data for the last n requests in memory.