Documentation (JS)

makc edited this page Sep 21, 2013 · 4 revisions

COLT documentation

Tutorials

Check out this tutorial to get you started.

Livecoding

Livecoding is a method of writing and monitoring applications when logic is updated in a working app just as you write the code, without restarting. Data and state of the app are also preserved.

COLT

Code Orchestra Livecoding Tool (COLT) is a tool for livecoding in JavaScript created by the Code Orchestra company. It is an special utility that monitors alterations of resources of web application — source code (JS, HTML), images and the rest. When the tool registers an alteration in the code, the latter is delivered into the working app. It needs to be preprocessed and started in COLT in order to receive code updates.

COLT installation

Download a COLT version for your OS at Code Orchestra's website

  • Win: Start the installer and follow instructions.
  • Mac: Start the .dmg file and move the COLT folder into the Applications folder.

Install Java if necessary.

If you're using Firewall, add the 6126 and 8091 ports to the list of open ones.

Possible issues during launch and how to solve them

  • Java is not installed.
  • Port “6126” and/or “8091” is inaccessible. Firewall needs to be set up.
  • Paths to sources contain symbols not supported by the runtime environment of COLT (like “#”)

##Starting an app in livecoding mode

Start any example of a COLT project. You can find these in the “Projects” folder in the COLT application directory. Click the “Run” button in the top bar of COLT. The app will be compiled and a player window will pop up. If a green icon of the session started lights up down there in the status bar, and an additional tab with the application logs appears — everything is going right. Your app is working in livecoding mode.

Read the “readme.txt” attached to each project. There's a suggestion of opening files with code in a text editor and changing lines of code there. As the code is altered and changes are saved, the app should change too.

##The process of editing an application in livecoding mode

As you click the “Run” button, a specific compilation starts. It alters the source code of the app in a way that each method that will later deliver changes (live-method) is moved to a separate class.

##Glossary

Livecoding session - starts as you click “Run” in COLT. The app is assembled in a specific way, and a socket connection opens between COLT and the app.

Livecoding client - an application started in livecoding mode for a livesession. A livecoding session can have several active clients at the same time. When a new one is added, all changes made during the current session are delivered.

Connection - a new connection is opened when a client is added. As it happens, a new tab with logs appears.

Live Code Update Listener - a specific function that tracks code changes.

Method registry - a registry of live methods. An JavaScript object that stores a registry of methods.

Livecoding annotations - specific metadata that makes it possible to manage regulations of what method or class will have the livecoding behavior.

##Managing regulations of covering the livecoding code

In order to turn livecoding off for a separate function, add the //@disable-livecoding annotation.

Subscribing to the event of changes delivery

When the code has it's implementation changed, the app won't do magic and alter its status and appearance on the screen. You should describe the logic of this update. The most common thing is to perform a specific code in all items of this class to update the object's status. Like, for example, re-drawing it on the screen. The easiest way to do this is adding a method with the //@code-update annotation:

//@code-update
public function codeUpdate() {
  console.log("code update!");
}

Delivery of changes of EMBED resources

Along with code alterations, COLT supports delivery of images and other files that you have in your project folder tree.

In order to handle an event of delivery of any resource in the project folder tree, add the //@asset-update annotation.

//@asset-update
function assetUpdate(e) {
	console.log("asset update! In " + e.sources);
}

Annotations and their parameters

//@disable-livecoding - forbid livecoding of a function.

//@code-update - a handler method for the event of delivering a code update to the app.

source - a relativee path of the file where changes took place.

methods - specifically tracked methods that have been changed.

//@asset-update - a handler method for the event of delivering changes of various resources.

sources - array of paths to changed resources.

Behavior of automatic error trapping and working with “dangerous code”

While writing a new code with the live method, you can make a logical mistake that may cause your app to stop. Like an endless loop, infinite recursion etc. COLT can help you avoid this.

What kind of code transformations take place to avoid these cases? COLT automatically turns the code in live methods into a 'try/catch' block. When “Exception” is trapped, the COLT log shows a message in the log. COLT limits the number of loop iterations (10000 iterations by default).