Functions of blackbird.js

In today's blog, I will go through each function of the blackbird.js as an exercise. Basically, I thought going through some JS code would be nice as a way to brush up and learn more about the beautiful and fluid language of JavaScript.

I find the naming of these functions are pretty evident in what it does. Looking at the code closer does helps one to grasp the branches and leaves of the code with greater confidence.

Below are the functions in more details:

generateMarkup: Generates the tool's content markup, including the header (filters and controls), main log body, and the footer (checkbox).

addMessage: Addes the log message to the output list.

clear: Clears the output list.

clickControl: Event handler for clicking to clear, resize, or hide log.

clickFilter: Event handler for filtering out logs based on type (debug, error, warning, etc)

clickVis: Event handler for setting to start tool on load.

scrollToBottom: Scrolls to the bottom of the log output list.

isVisible: This determines whether the display is visible or not by checking the css display style.

hide: This hides the display by setting the css style display attribute to none.

show: This gets the body element, then remove and add the tool content code into the body element. Also, it sets to display the tool.

reposition: Sets the position according the the position argument. If no argument is provided, use the default topRight or move to the next position as stored in the state. This calls setState after the classes have been set accordingly.

resize: Resizes the tool display to either small or large based on the argument, default or state value.

setState: Goes thru the state object and sets the property (props) array to be written to the cookie. Then it sets the class attribute for CSS styling.

getState: Retrieves the state object from cookie.

readKey: This is the event handler for keyup. Based on the F2 key combination with alt and shift, as well as the current visible state, the function clears the log, reposition or hide/show the tool display.

Examining blackbird.js

The code to blackbird.js can be found here. Today, I will examine the inner working of blackbird.js, line by line.

To start off with, let's understand the self-executing anonymous function.

(function () {
    ... some code
})();

The use of it, helps to provide function level scoping while making the code executing on its own. For more detailed explanation, refer to this nicely written blog.

Next, at the top level within the main function, we can see that there are some variables defined, including cache array, and objects like classes, profiler and messageTypes. At the same time, some inner functions are there: generateMarkup, clickControl, isVisible, getState, addEvent, and removeEvent. The window object is set with a namespace, i.e. the log object with methods such as toggle, clear, debug, warn and profile. These methods provide the API of the library. The initialization code is performed on window's load. This is achieved by calling addEvent with window, 'load' event and the callback function as the arguments. The addEvent & removeEvent code look a bit long but have good reasons. The main idea is to be cross-browser compatible.

The initialization code requires some describing.


addEvent(window, 'load',
/* initialize Blackbird when the page loads */
function () {
    var body = document.getElementsByTagName('BODY')[0];
    bbird = body.appendChild(generateMarkup());
    outputList = bbird.getElementsByTagName('OL')[0];

   backgroundImage();

   //add events
   addEvent(IDs.checkbox, 'click', clickVis);
   addEvent(IDs.filters, 'click', clickFilter);
   addEvent(IDs.controls, 'click', clickControl);
   addEvent(document, 'keyup', readKey);

   resize(state.size);
   reposition(state.pos);
   if (state.load) {
       show();
       document.getElementById(IDs.checkbox).checked = true;
   }

   scrollToBottom();

   window[NAMESPACE].init = function () {
       show();
       window[NAMESPACE].error(['', NAMESPACE, ' can only be initialized once']);
   }

   addEvent(window, 'unload', function () {
       removeEvent(IDs.checkbox, 'click', clickVis);
       removeEvent(IDs.filters, 'click', clickFilter);
       removeEvent(IDs.controls, 'click', clickControl);
       removeEvent(document, 'keyup', readKey);
   });
});

Line by line, first it grabs the body element, then append to it the generated markup. The outputList element is set. Next, events are registered for clicking the checkbox, filters, additional controls, and key ups. Base on the current state, the log display is resized and repositioned. If indicated to load, the display will be shown and the checkbox checked. Then the log content is scrolled to the bottom. The init method on window namespace object is defined. Finally, window on unload will remove the before-mentioned event registration.

In the next blog, we'll go and visit the individual functions and the relevant variable data.

JS logger: Blackbird

The Blackbird project is a neat little JS project that helps one to not write alert for debugging. Although you may argue much of the functionality has been superseded by developer tool in various browsers, this Blackbird logger tool is still nice in terms of its ease of use, cool UI and simplicity.

In the next post, we'll dissect its JS source code to understand how it works behind the scene as an exercise!