Choosing an Extensible Documentation Solution

For a while I have been using Microsoft Word to author user guides and to be fair this has been a good solution up until now. Since beginning work on Rotorz Tile System there have been a number of product updates which have required multiple updates of the user documentation. Despite using style presets the process of maintaining consistent formatting and updating illustrations is extremely time consuming. I also feel that there is a need for a web based version of the documentation to make it easier for some people to find their way around.

So… ultimately I required a solution that takes a number of document fragments that can be composed in a variety of ways to provide at least two deliverables (PDF plus web based documentation). After some careful thought I also decided that I would like to avoid directly formatting the documentation that I write to save valuable time; this should be handled automatically by the documentation solution.

Continue reading

Advertisements

Unit testing with JavaScript and NodeJS

In my latest project I needed a way to execute JavaScript from the command line. I knew a little about the Rhino project which achieves this and of course the Google V8 Project.

I experimented a little with V8 and the default shell sample application that it ships with. I found it easy to introduce native functionality using C++ and this seemed to perform well. I then discovered the nodejs project. nodejs is built on top of V8 and includes lots of general purpose functionality which is great for running JavaScript from the command line and fantastic for developing server applications.

Instead of reinventing the wheel with my custom V8 shell I decided to use nodejs. nodejs has an excellent module system which makes it easy to add new functionality.

Continue reading

Building server and client applications using JavaScript

JavaScript has become an essential tool that allows web developers to produce sophisticated web applications that often use AJAX to communicate with the server. JavaScript source code is becoming increasingly more complex and so it has become necessary for web browser developers to increase the performance of their JavaScript virtual machines.

Google Chrome features the v8 JavaScript environment which provides outstanding performance by compiling JavaScript into machine code (as opposed to being processed by a virtual machine). The performance boost is massive. V8 is released under an open-source license (http://code.google.com/p/v8/) which can be compiled and used as a standalone JavaScript processor, or more interestingly integrated into custom applications!

Continue reading

Documenting JavaScript with jsdoc3

JavaScript is an extremely dynamic language which allows it to be applied in a variety of interesting ways. Some prefer to take the structured approach whilst others prefer an object-oriented approach using the prototype object or a library that offers a more classical approach. This diversity makes docblock type documentation seem impossible…but it isn’t!!

Thanks to jsdoc3 this task is made significantly simpler. It’s rich selection of tags makes it possible to document even the most abstract concepts that JavaScript permits. It is also extremely easy to create plugins and custom templates. Jsdoc is a command-line tool that works on any platform that supports Java. See project pages for information about usage.

Useful Links:

Continue reading

Using namespaces with jQuery Widgets

Creating plugins for jQuery is a relatively straightforward task, however poorly named plugins can conflict with one another (or even with core jQuery functionality). I have seen numerous attempts at solving this problem which each have their advantages and disadvantages.

My take on this problem is to define widgets in a completely separate namespace and then refer to them using a single jQuery plugin `widget`. This plugin depends upon the following jQuery variant of my `$namespace` function from here.

Continue reading

Improve consistency of button element across browsers

The button element can be styled easily for the desired look, however as soon as padding is specified the button appearance is drastically different across web browsers. So I did some searching and found several different fixes and found that a combination of all of them does the trick (mostly).

I have added the following to the end of Eric Meyers fantastic reset stylesheet.

/* Fix for IE7 */
button {
    overflow: visible;
    width: 0px;
    /* Default padding that can be overridden as desired. */
    padding: 2pt 4pt;
}
/* Fix for IE7+ */
button {
    width: auto;
}
/* Fix for FF */
button::-moz-focus-inner {
    padding: 0px;
    border: none;
}

I threw a crude test together and viewed it with Chrome, FireFox, IE9/IE8/IE7 and Opera and it seems to be a solved case. There are minor differences but it is certainly an improvement. IE7 still adds padding above and beneath button text. Please post a comment if you know how to fix that problem!

References:

Business Process and Data with MVC (Model-View-Controller)

I have been thinking about the general issues with the MVC and the Vespa concept “Vespa: A better MVC”. The idea of splitting the Model component has really helped me a lot with a project that I am working on.

Let me emphasise that this doesn’t define how the model-view-controller (MVC) design pattern is supposed to be used. It merely suggests a slight alternative which allows the Model component to be split into business process and business data.

I decided to split Model into Service and Model (yes I stuck to the same name, but it has a lesser more specific goal). In my project a Service represents a business process whereas a Model only represents business data. I allow the Model to access data via an encapsulated PDO connection.

Continue reading