AboutDotmatrix is a lightweight, framework independent javascript library used in creating a fast, easy to change marquee style scrolling dot-matrix board on your site. I made it to see if I could, and I'm not sure anyone has a use for it, but if you do, please let me know. It'd make me
... [More]
super pleased to continue working on this project.
InstallationTo install, simply unzip (or untar) the archive files found on the right side of this page, and drop the dotmatrix/ directory into your website. The index.html file merely holds a small demo to show you how dotmatrix works.
SetupSetting up dotmatrix is a pretty straight forward process. It requires only two things: A javascript include in your header A div with the id 'dotboard' somewhere in your page
The IncludeIf we open up the index.html page, we see the javascript include right in the tag.
Dotboard Demo
Including the controller is the only include you need to make, however, the system will then perform, behind the scene, some other includes, which you control from the div#dotboard element.
The Dotboard RootDemo dotboard text! Neat!Let's go a bit deeper into the parameters we can set through this div (all of which, except id are optional). Note: While using the default show factory, any text you enter inside of the dotboard div will become the text used for the show. If you provide no text, you will have to manually set the text it uses.
cols - This sets the default 'length' of the dotboard. Defaults to: 9 columns rows - This sets the default 'height' of the dotboard. Defaults to: 11 rows lib - This sets the character library that will be used by the dotboard. Uses the default charlib show - This sets which show file will be used to run the dotboard Uses the default show factory Lib(rary) ParameterWithin the dotboard/ directory, there exists a subdirectory named chars/. Within this directory, there is a 'default.js' file. If you fail to specify a resource with the "lib" parameter, it will use this 'default.js' file. If you create a custom library, you would place it inside of the chars/ directory. If the custom library's filename was 'custom.js', your lib parameter would be: lib="custom"
The system automatically adds the .js extension and reference to the chars/ directory.
Show ParameterWithin the dotboard/ directory, there exists a subdirectory named shows/. Within this directory, there is a 'default.js' file. If you fail to specify a resource with the "show" parameter, it will use this 'default.js' file. If you create a custom show factory, you would place it inside of the shows/ directory. If the custom show's filename was 'newshow.js', your show parameter would be: show="newshow"
The system automatically adds the .js extension and reference to the shows/ directory.
Building a ShowIf you navigate to dotboard/shows/default.js, you will find the default show factory. Dotboard is merely a rendering engine that creates a field of points, and then turns on/off points within the field. The show factory builds off this rendering engine to move text across the field of points. Within the chars/ directory is a default.js file which contains instructions for the rendering engine to convert Ascii text (any text you type in, like this text here) into the dot-matrix text, so it can be scrolled along.
Now, inside of the dotboard/shows/default.js, there is a function called buildShow(){}. ALL show factories you build must have this buildShow parameter to work with the rendering engine. This build show acts as both the instantiation point for the show factory, and as an opportunity to edit settings within the rendering engine. Let's take a look at it:
function buildShow(){
db.yoff = 1; // Puts 1px top border on the show
show.offset = db.cols; // Set the left offset to the size of the box, so it starts
// blank and scrolls left
show.actions = { // The commands which run our show
1: '>', // Start playing the show at Mark 1
41: '[', // Pause/blink the text at Mark 41
75: ']', // Stop the pause/blink and resume show at Mark 75
end: '@' // When the show ends, loop back to the start and go fresh
};
show.size = db.load(); // Load whatever text was in div#dotboard
show.init(runShow); // Initialize the show
}From this function, you can access any of the dotboard rendering engine settings (db.) and set values in them. The most common function you should probably need to use is the yoff setting. Depending on the size of your dotboard, you may want to push the dots down to center them on the board. All the characters in the default library are 7x9 dots, and the default dotboard size is 9x11. If you wish to have a horizontal setting in this case, you'd set the top offset (yoff) to 1.
show.offset, on the other hand, is an after-rendering offset used by the show factory to move the characters off to the right to alter their starting position. The show factory, by default, sets this value to the number of columns in the dotboard, allowing the show to start blank, and scroll in the text from the left.
show.action allows you to edit how the show plays out. You must provide a literal javascript object (denoted by {}) containing a key:value set of show-time delineation to the action.
Show Actions'>' - Play - To start playing a show, you must include this 'Play' character, which will start the show. Normally, this action is placed at the start of a show: {1: '>'} '|' - Pause - To pause a show, set the action character to '|'. When the time delineation is reached, the show will pause until it is again restarted by a '>' action. '#' - STOP - To stop a show (without being able to restart it), use the '#' action character. When the time delineation is reached, the show will stop, and will only restart when the page is reloaded. '@' - Looping Restart - When a show ends (or when you deem it necessary to start it over), pass in the '@' action character. When this occurs, the show will stop, rewind to the beginning, and run through both the show text and the action script again. '!' - Soft Restart - When a show ends (or when you deem it necessary), pass in the '!' action character. When this occurs, the show will stop, and rewind to the beginning, and run through only the show text again, continuing with the action script from the current delineation. '[' - Pause/Start Blink - If you want to blink text in your show, pass in the '[' action character. This will pause the show, and blink whatever text is currently visible in the dotboard. If you pause the show to initiate a blink, you should only restart the show using the end blink action character (]), and not the play character (>). ']' - End Blink/Resume - When you want a pause/blink action to end, pass in the ']' action character. This will stop the blinking, and resume scrolling the show. Now, let's build a demo show. Lets say we want to delay the start of a show for 10 show-time delineations. (Each show time delineation is equal to 100 milliseconds, or 1/10th of a second. So 10 show-time delineations is equal to 1 real-time second). Then, we want the scrolling text to go on until 50 delineations, at which time we want to pause the show and blink the currently visible text. Then, we want the text to blink for 50 delineations, at which time, we want to stop the blinking, and resume the show. And when the show ends, we want to loop back to the beginning, and play the exact same show again, complete with the pause/blink action.
In this situation, our action script looks like this:
show.action = {10: '>', 50: '[', 100: ']', end: '@'};Now, lets say we want to make a small edit, and after the show plays through once, we want the text to continue to scroll, but without redoing the blink. We change the end character to a soft restart action character, or:
show.action = {10: '>', 50: '[', 100: ']', end: '!'};if you do not specify show actions, the default show will be:
show.action = {1: '>', end: '@'};Show TextNow, for the show to work correctly, within our buildShow() function, we must include the following line:
show.size = db.load();The above line of code will load as the show text whatever was placed inside the div#dotboard. If you did not place any text inside of the div#dotboard, or want to use different text than what was inserted, you must provide that text here as the only parameter in the db.load() method.
So lets say we had no text in div#dotboard, and wanted our text to be: 'Dotboard is Great!'
We would edit this line in our buildShow() function to:
show.size = db.load('Dotboard is Great!');Starting a ShowFinally, we must pass into the show factory the function which will run the show. The default method is:
show.init(runShow);Which references a show factory helper function (runShow) that manages the actions of the show. [Less]
Copyright
©
2013
Black Duck Software, Inc.
and its contributors, Some Rights Reserved. Unless otherwise marked, this work is licensed under a
Creative Commons Attribution 3.0 Unported License
. Ohloh
®
and the Ohloh logo are trademarks of
Black Duck Software, Inc.
in the United States and/or other jurisdictions. All other trademarks are the property of their respective holders.