August 20, 2013

Using the TurtleBits Editor

RichB commented yesterday about his 7-year-old's experience with the TurtleBits editor: "He expected the editor just to create new blank space at the end for him. So every few minutes I had to come back to the computer and hold the return key to generate some blank lines."

I have had the same experience with my 6-year-old! So now I have fixed up the editor to always insert a blank line at the end. Let's see if that helps with this issue.

TurtleBits should be as beginner-friendly as possible. Here are a few notes on the use and design of the TurtleBits editor....

Editor Design Goals

It is designed with a few goals in mind:

  • Newcomer-friendly. No commitment to try and play with programming.
  • Kid-friendly. Clear design that kids can drive on their own.
  • Kid-proof. Difficult to make catastrophic mistakes like deleting your code.
  • Open. Should have an API that lets kids load and save data themselves.
  • Bootstrappable. Should be possible to write an editor within the editor.

In other words, the editor should have No Thresholds and No Limits.

Guests Can Play

Visiting opens up an example program that you can run and play without an account.

However, if you want to save your program, you will need to pick an account name so that you can come back to it later. Create an account by just clicking the "Save" button in the play area. You can optionally choose a password.

Users Get a Domain

Once you set up an account, you get a domain "" where you can save as many programs as you like.

There are a few advantages to getting your own domain.

  1. First of all, it's neat to have a domain name to use. Kids learn that they can easily put their own presence on the internet.
  2. Second, a domain gives you a natural namespace for creating your own website. Having a domain with real URLs means that you can easily create hyperlinks and relationships between multiple files.
  3. Third, by working in your own domain, you reduce the possibility that you will accidentally interfere with other users' work - browser cross-origin security rules protect you from stepping on other programmers' toes (or their programs' cookies).
  4. Fourth, by giving each user their own domain, you can have two students share a computer by opening an editor for each student in a separate tab or browser window. (This is a common problem in real classrooms, where you typically have fewer computers than kids.) You don't need to face the dilemma of "which one logs in" - both can be logged in at once.

Easy URLs for Editing

Every file you post on your domain is available in your /home directory. For example, if your username is "david" and you post the program named "first", your program can be run by visiting

Anybody can view and play and tweak your source code by changing the "home" in the URL to "edit", for example, by visiting

However, if you have set a password, visitors will not actually be able to save over your URL without logging in with your password first. (But do be aware that people can easily type in and run code as if it were running in your domain - they just can't save it.)

You can create new files by typing the "edit" URL of the filename that you would like directly into the browser address bar. You can create any directory structure you want, for example "".

Deleting Files and Directories

To reduce the chance that you can quickly destroy your own work by pressing the wrong button, there is no "Delete" or "Delete Directory" button in the editor. But of course, you can delete files and directories.

Delete a file by using the editor to erase its contents and saving it. Saving an empty file will delete it. Delete a directory by deleting all the files in it.

Save Protection and Local Backups

A common problem is for kids to lose their work by forgetting to save, or by crashing their browser (e.g., hanging it and then having to close it).

So each time a program is run, the code is first saved in localStorage. If you close the browser and return to the same file, the unsaved backed-up version will be shown (if it is different and newer than the saved version). If the backup is not what you want, you can click "Load last saved version" to go back to the saved version.

In addition, the normal forward- and back- and navgiate- and refresh- button actions are in the browser are protected by a "Did you want to save?" prompt.

Another common problem is to have two tabs open to the same file and then overwrite a newer version with an older one. If the editor sees that you are about to to this, it confirms that you want to overwrite a newer version before you do it.

Renaming Files and Creating Other File Types

Rename a file by just clicking on and editing its name (colored brown) in the editor. Normal filenames (without an extension) are assumed to be coffeescript files that should be run with turtle bits.

You can also save HTML, CSS, Javascript, plaintext, or other types of files on your domain. Just rename them with an extension in the filename such as "mypage.html". Recognized extensions include "html", "htm", "js", "css", "coffee", "txt", "xml", and "json".

Weakened Passwords

Passwords are optional. TurtleBits is not a high-security area, so if you use a password, you should use an unimportant password that it is OK to leak. For example, pick a three-digit number that you would be happy sending in cleartext.

As I describe below, TurtleBits exposes a storage API that is easy to for beginners to understand. So TurtleBits does not protect passwords with challenge-response. Instead, passwords are always hashed down to a three-digit key that is sent in the clear as the "key=" cgi argument for authenticated server requests. (Very easy to crack by brute force - the purpose is to just avoid accidental interference, not malicious attacks.) Your actual password is never stored, so remains unknowable. But you should use a low-security password anyway.

JSON API for storage

As you get more advanced, kids often ask "how do I save a message" - e.g., for example, so that a guest can sign their webpage and leave a message that is still there after you close the browser.

For that, we have a JSON API. It is simple to use. Instead of using "/home/" or "/edit/", substitute the word "/load/" or "/save/" in the URL. Using "/load/" will load the contents of the URL (along with some file metadata such as the last modification time) and return it as JSON. Using "/save/" will save the URL. To supply the data to save, use the "&data=" CGI argument.

Of course, access to the API can be simplified using jQuery:

$.getJSON '/load/first', (m) -> see m
$.getJSON '/save/first', {data: 'fd 100'}, (m) -> see m

Fully Bootstrapped

The turtlebits editor itself uses this API to load and save everything on To see the details of what it is doing, just take a peek at the network debugger in the console.

There are some details such as how directory listings work that are not described here.

One key detail is that if you have set a password, saving will not work without a key. To see the key that is used for your account, you can look for the "key" CGI argument in the network debugger. If your key is "098", then you can save as follows:

$.getJSON '/save/first', {data: 'rt 90', key: '098'}, (m) -> see m
Posted by David at August 20, 2013 04:10 AM

It also looks like Chrome DevTools are implementing a virtual space at the bottom of their editor:

Doesn't seem to be available in Canary yet.

Posted by: RichB at August 20, 2013 07:09 AM

More observations:

1. When copy/paste code from the help pane, sometimes you get a space prepended. The problem comes because this code doesn't show an error cross
2. The following code locks up Chrome:
while true
turnto lastmousemove
fd 10
wait 1

I have no idea whether this is valid coffeescript, it was a guess.
3. The auto-generated newline at the end of the file is a big help

Posted by: RichB at August 20, 2013 02:52 PM

1. Yeah, maybe the HTML in the help pane should be rearranged to avoid special chars when you copy. At some point I should rewrite the help pane, but it's very finicky getting the layout to work well in the browser.

2. Try using "await done defer()" instead of wait. I've added Iced coffeescript and have written a couple blog posts about it.

3. Good! I haven't had a chance to try it with Cody yet.

Posted by: David at August 23, 2013 07:52 AM

I have now (I think) fixed the help pane so that when you copy/paste from it, it works more nicely.

The key is that the little caret > before the lines shouldn't be selectable. Let me know if you try it and this fixes the problem.

Posted by: David at September 2, 2013 07:35 AM
Post a comment

Remember personal info?