jCquard

Unlike many of the more popular JavaScript libraries out there, such as YUI and Prototype and Scriptaculous and Dojo and MooTools and jQuery (just to name one or two), jCquard seeks to serve an extremely small niche market. Namely, jCquard’s target audience is people who would like to (or, God help them, need to) write JavaScript applications using IBM-style 80-column punch cards.

Compatibility

Obviously, to make use of a technology as ancient as punch cards, you must start with the newest and freshest technology and then work your way backwards. To this end, jCquard requires a DOM-compatible browser that supports the <canvas> element, such as Firefox 3. In short, if you can’t see the image of the punch card at the top of this page, then it’s time to upgrade.¹

The latest version of the jCquard library is available as a compressed tar file (241.9 KB).

The jCquard Object

jCquard.ready(func)

A function passed to the jCquard object’s ready method will be called if and when the jCquard object is ready to be used. You should use the method to enclose any code that uses the jCquard object, like so:

jCquard.ready(function() {
    /* Your code goes here */
});
		    

jCquard.setDefaultCard(cardDef)

This method is used to specify a new default punch card image. cardDef is a JavaScript object with the following members:

imgSrc	The URL of the card image file
chadWidth	The width of one of the chads (punches)
chadHeight	The height of one of the chads (punches)
columnCount	The number of columns on the card
rowCount	The number of rows on the card
columnPos	An array of pixel positions, measured from the left-hand edge of the image, of each column on the card
rowPos	An array of pixel positions, measured from the top edge of the image, of each row on the card

jCquard.Card(options)

The Card method creates an instance of a jQuard Card object. There are in fact two ways to create a Card object. Method #1:

var myCard = jCquard.Card(/* options */);
		    

Method #2:

var myCard = new jCquard.Card(/* options */);
		    

You can also create a new card based on an image of an existing card, like so:

var srcImage = new Image();



srcImage.addEventListener('load', function() {

 var myCard = new jCquard.Card({image: this, title: "Copy of Hello World"});



 // add the card to the page

 document.body.appendChild(myCard.render());

}, false);



srcImage.src = 'helloWorld.png';
		    

Run this code

Please wait...

The options JavaScript object has the following members, both of which are optional:

title	The title printed at the top of the card (default: "Untitled")
image	An Image object containing an image of an existing card, whose values will be copied to the current card

The Card object

The Card object is the centerpiece of the jCquard library.

card.title

The title attribute is used to get and set the title that is printed at the top of the card. Typically, this should reflect whatever is encoded on the card itself.

card.getId()

Returns a unique ID for the card, which is also the ID of the <canvas> object returned by the render() method.

card.getColumnCount()

Returns the total number of columns (punched or unpunched) on the card.

card.getRowCount()

Returns the total number of rows on the card.

card.render()

Renders an image of the card and returns a <canvas> object that can be inserted into the DOM. The value of the <canvas> object’s id attribute can be retrieved with the getId() method.

If <canvas> is unsupported, the method throws an exception.

card.punchHole(column, row, noRender)

The punchHole() method is to jCquard what the increment() function is to Arithmetic. column and row specify where the hole should be punched. The render() method is called after the hole has been punched. Returns the calling object.

card.isPunched(column, row)

Returns true if the hole in the column^th column and the row^th row has been punched, or false if it has not.

card.punchValueAt(value, column)

Converts value to binary and punches its least significant bits at the column^th column of the card. If value is a string, then the numeric value (ASCII — but don’t fret, EBCDIC is on its way) of the first character is used. The render() method is called after the value has been punched. Returns the calling object.

card.getValueAt(column)

Retrieves the value punched at the column^th column of the card.

card.punchStringAt(string, column)

Converts the characters in string to binary values and then punches the values at sequential columns starting at the column^th column. If the string overruns the width of the card, then the remaining portion of the string is returned. Otherwise, the calling object is returned.

Example:

var cards = [];

var address = "Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in liberty, and dedicated to the proposition that all men are created equal.";



do {

 var card = jCquard.Card({title: "Gettysburg Part " + (cards.length + 1)});

 address = card.punchStringAt(address, 0);

 cards.push(card);

} while (!(address instanceof jCquard.Card));



for (var i=0; i<cards.length; i++) {

 document.body.appendChild(cards[i].render());

}
		    

Run this code

card.getStringAt(column)

Returns the string encoded starting at the column^th column of the card up to the next column with a 0 value or the end of the card, whichever comes first.