Codeblock.js

Editable, runnable javascript code blocks

Download .zip Download .tar.gz View on GitHub

Why?

Humans learn better when they can play with what they're working with, when they can poke at it and understand what happens to B when you change A. The browser provides a wonderful place where examples can be interactive, and yet most documentation for javascript APIs doesn't make use of these capabilities.

Codeblock.js turns example code into editable, runnable code blocks that visitors can poke at and play with to better understand your API. For example, try playing with the parameters in the example below:

//Try playing with the parameters var R=0, s=5; x1=.1; y1=.05, x2=.25, y2=.24, x3=1.6, y3=.24, x4=300, y4=200, x5=300, y5=200; //Try various tags here (p, a, code, etc.) //var elems=document.getElementsByTagName("h3"); var elems=document.querySelectorAll("#sandstorm_demo span"); var l=elems.length; var i, c; var A = function (){ for(i=0; i-l; i++){ c=elems[i].style; c.position='absolute'; c.left=(Math.sin(R*x1+i*x2+x3)*x4+x5)+"px"; c.top=(Math.cos(R*y1+i*y2+y3)*y4+y5)+"px"; } R++; }; //Loop setInterval(function(){A()},s); console.log("Sandstorm!");

Using Codeblock.js

Codeblock.js is a jQuery plugin that uses the Ace code editor, and therefore requires including both jQuery and Ace.

<!--Thanks Google!-->
<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<!--Ajax source from github, you probably should host it yourself--<
<script src="//rawgithub.com/ajaxorg/ace-builds/master/src-noconflict/ace.js" type="text/javascript" charset="utf-8"></script>
<!--The codeblock plugin--<
<script src="codeblock.js"></script>

Once the scripts are imported, you can use the $.codeblock call to transform any piece of text into an editable, runnable code sample. Try it out:

$("#basic-codeblock-example").codeblock(); console.log("Success");
//Press "Run" above to turn this sample into a codeblock //Then try running this code to undo console.log("Destroying..."); window.setTimeout(function(){ $("#basic-codeblock-example").codeblock("destroy"); }, 1000);

API

The codeblock.js api is very similar to the api of jQuery UI widgets, so if you are familiar with those the syntax should feel natural.

Instantiation

//To reset: //$("#api-instantiation").codeblock("destroy"); //Below are the default parameters. Try changing one or all of them. $("#api-instantiation").codeblock({ editable: true, //initial console text consoleText: "Output from the example appears here", consoleClass: "codeblock-console-text", runButtonText: "run", runButtonClass: "codeblock-console-run", console: true, resetable: true, runnable: true, //The ace theme to use editorTheme: "ace/theme/dawn", lineNumbers: true });
console.log("A simple codeblock");

Methods

$("#api-methods").codeblock(); console.log("The current text of the codeblock is:"); console.log($("#api-methods").codeblock("text")); //Set the text of the codeblock //$("#api-methods").codeblock("text", "console.log('Dynamically set code!')"); //Reset and run the codeblock programatically //$("#api-methods").codeblock("reset"); //$("#api-methods").codeblock("run"); //Get or change properties of the codeblock //$("#api-methods").codeblock("editable", false); //console.log($("#api-methods").codeblock("editable")); //$("#api-methods").codeblock("runnable", false); //console.log($("#api-methods").codeblock("runnable")); //Get the underlying ACE Editor for more complex actions //$("#api-methods").codeblock("editor").moveCursorTo(0,10);
console.log("Use the methods above"); console.log("to manipulate this codeblock");

Events

$("#api-events").codeblock().on("codeblock.run", function(){ console.log("The event codeblock was run"); }).on("codeblock.reset", function(){ console.log("The event codeblock was reset"); }).on("codeblock.console", function(e, text){ console.log("The text '"+text+"' was written to the console"); });
console.log("Play with this codeblock"); console.log("and see what events are thrown");