Chapter 1: Introduction to the Pencil Code Environment

In this manual we will show how to use Pencil Code to explore programming. Pencil Code is a free
programming tool available at pencilcode.net. Pencil Code was developed by Google engineer David Bau
together with his son Anthony Bau, with open-source contributions from many others.

Two Ways of Looking at a Program

There are two ways of viewing a program. A computer user sees a program by looking at its output. A
programmer works with a program’s source code. In Pencil Code, the screen is split into two halves, with
the source code on the left and the output on the right. You run programs by by pressing the “play” button
in the middle.

The Pencil Code interface splits the screen,

showing source code on the left and output on the right.
The play button in the center runs the code and produces output.

Languages and Libraries in Pencil Code

Pencil Code supports code in both blocks and text using mainstream web programming languages and
useful libraries including:

• HTML, the standard HyperText Markup Language for the web.

• JavaScript, the standard programming language of web browsers.

• CSS, the standard Cascading Style Sheet language for visual styles on the web.

• jQuery, a popular library that simplifies programming interactive websites.

• CoffeeScript, a language that lets you do more with less typing than JavaScript.

• jQuery-turtle, which extends jQuery to simplify graphics and animation for novices.
With Pencil Code, students can use these technologies to create web applications with global visibility
and impact while exploring fundamental concepts in computational thinking.

We will discuss all these topics in later chapters of this Pencil Code teachers’ manual.
A Web Page is a Program
Every web page is a program, and has both source code and output.

The source code is sent to your computer when you request a web page. It may contain a combination of
different languages, like HTML and JavaScript. The output is what you see when your browser interprets
the source code.

Source code may include languages such as Output is the result of your browser interpreting
HTML, JavaScript, and CSS. See this example in the source code.
your browser at view-source:http://www.loc.gov/.

Encourage your students to explore the source code of different websites by looking for hidden messages
contained in the webpage sources. Go to www.ebay.com, www.flickr.com, or www.mozilla.org. To view
source, press Ctrl-U. (On a Mac, the keyboard command is Command-Option-U, and on Safari, “view
source” needs to be enabled first using Advanced Preferences.)

Every Pencil Code Program is a Web Page

In Pencil Code, every program is a web page. At the top the editor are a few details to help control how a
page is published. In the upper right are buttons for saving and sharing the program, as well as buttons
for managing your website and getting help. The upper left shows the name. Rename a program by
clicking on the name in brown and editing it.

The name sets the URL web address for the program, as shown in the examples in the table below.

Account name Project name Output URL

coolsite first https://coolsite.pencilcode.net/home/first

david example/posterize https://david.pencilcode.net/home/example/posterize

Hovering over the “output” icon in the blue bar on the upper right will provide an “open window” link that
opens a new tab showing just the output of the program as it would appear to users visiting the webpage.
It does not show code. (This link is available only after logging and saving a program.) It is valuable to try
running your programs full-screen, and from there use Ctrl-U to “view source” on your own webpage.

Clicking the open window button will run the program

in full-screen mode, without showing source code.

In Pencil Code, the full-screen output URLs have the word “/home/” in them. These addresses can be
linked, emailed, or embedded anywhere. Changing the “/home/” to “/edit/” will make a URL to show the
Pencil Code editing UI, revealing the source code for any program on Pencil Code.

What is a Programming Language?

Pencil Code allows the programmer to use “block-mode” to drag and drop blocks to design a program.
The blocks in Pencil Code are a direct representation of an underlying text language: CoffeeScript,
JavaScript, or HTML. Although the blocks look different from text code, they are just a visual way to view
and edit instructions in a programming language.

Viewing Source Code in Block Mode

Viewing Source Code as Text

A programming language is any language that is precise enough for a machine to interpret, while also
being understandable by people. The words “run this over and over” in English mean the same thing as
the Intel Pentium opcode “1110101111111110”. But the English words are too ambiguous for a computer
to follow, and the machine opcodes are too obscure for a person to read. A programming language is
written in readable words, but in a way that follows precise patterns, called a syntax, that a computer can
follow precisely.
When viewing JavaScript or CoffeeScript in block-mode in Pencil Code, the syntax of the programming
language is shown through the block structure. For example, when words are part of different commands,
they are shown as different blocks. When one command is under the control of another, the blocks show
the commands nested within one another.

Switching Between Blocks and Text

In Pencil Code, block-mode and text-mode are perfectly equivalent in power and expressiveness. Blocks
are a just a visual view of the syntax of JavaScript, CoffeeScript, or HTML, and students can switch
between blocks and text freely.

This yellow tab with a gray arrow is a toggle

button that switches between text and blocks.

The toggle button on the yellow tab on the lower-left edge of the editing area lets the programmer switch
from block to text and from text to block-mode. Hover on the tab to see the tab expand to a button that
says either “click for blocks” or “click for text”.

When to Use Blocks

When should a student use blocks or text?

The best time to use blocks is when a student is learning a new function or command. Blocks are
organized on the palette with the right syntax to use and shapes that snap together correctly. They make
it easy to try a new idea because you only need to recognize a block to use it.

The best time to use text is after a student knows functions and commands well enough that to type them
from memory. Once students become familiar with the parts of the language they need for a project, they
will find that typing can be faster and more fluid than dragging blocks.

In Pencil Code, the blocks contain code that exactly matches the syntax for the language being used. For
example, when using CoffeeScript, the block to move the turtle forward by 100 pixels will read “fd 100”,
which is exactly the same code to type in text mode. If students modify or add code using text mode, they
can switch back to block mode to see how their code looks as blocks.

Students should feel free to work in either blocks or text, clicking the button to switch at any time. In early
sections we assume students will be working with mostly blocks. As students become more familiar with
the syntax of a language by remembering the syntax within the blocks, they will often want to type code
directly as text, switching to blocks when trying something new, or when trying to understand work that
they typed. Most students will naturally move from blocks to text as they become familiar with the
functions and commands in the language they are using.
Beginning with CoffeeScript
Pencil Code supports both JavaScript and CoffeeScript natively, but the default language in Pencil Code
is CoffeeScript, and we recommend students start with CoffeeScript.

CoffeeScript is a professional language that is used by many tech companies including Github and
Dropbox. Its power and speed are equivalent to JavaScript. CoffeeScript, however, has a simpler syntax
(similar to Python) that uses meaningful indents and less boilerplate punctuation. The simpler syntax
requires less typing when students make the first tricky leap to a text language. It also clarifies the code
for concepts such as functions, nesting, loops, input, and arrays.

pen(red); pen red

for (var i = 0; i < 20; i++) { for i in [0...20]
fd(i); fd i
if (i < 10) { if i < 10
rt(90); rt 90
} dot blue
dot(blue);
}

JavaScript is the standard programming language CoffeeScript is a popular language used by

of the web, but the punctuation in the language professionals to abbreviate JavaScript. It requires
can be overwhelming to a novice. less punctuation than JavaScript.
In this manual we will use CoffeeScript up to Chapter 7, after which we will introduce JavaScript.

Comments
A note on comments: to create a comment in the code in block, first create an empty block by pressing
the “Enter” key and then type in the block starting with the # sign. The comment block now looks
something like this:

The # symbol is the CoffeeScript comment symbol. To create a comment in JavaScript, use “//”.

Switching Languages - CoffeeScript, JavaScript, HTML, and CSS
To switch from CoffeeScript to JavaScript, click on the” gear icon” in the blue bar. From this box, choose
between the two scripting languages and optionally add panes for either or both of the layout languages
HTML and CSS. You can also enable or disable the main turtle here, which is helpful if you are making a
program that does not use the turtle.

The gear button opens a settings panel

that allows switching languages and libraries.

Settings in this panel will be remembered next time you create a new program. To switch settings again,
just use the gear button again.

The Test Panel

One way to explore commands is by typing them in first to try them. The test panel in the lower-right side
of the screen lets you type individual commands in CoffeeScript or JavaScript. For example, if you type
“dot red, 100” and press enter, the command will be run right away so you can see what it does.

The test panel. If the test panel is not visible,

it may be necessary to open it by dragging the gray divider.
Type a command by itself in the test panel, without any arguments, to get a bit of help about it. (See
below for an example of getting help about “label”.) If the test panel is too small to see the help, the dark
gray bar at the top of the panel can be dragged to increase it or decrease it.

You can also click the examples highlighted in yellow in the help text to try them out right away.

Debugging Using the Test Panel

You can use the test panel can to debug the variables in a program. For example, try running a
program in the left-hand panel that reads “x = 42” as follows (if using blocks, find the variable assignment
operator under the “Operators” panel).

Then type “x” in the test panel and press enter to see the value of x. If the test panel says “x is not
defined,” it means that the program has not run yet - just press the “play” button, and then interact with
the program after it has run to see the value of x is 42.

There is a special “debug” command that can be used to produce output directly to the test panel without
interfering with the main part of the web page (find the debug block under the “Text” panel). Try creating a
program that reads “debug ‘hello’” as follows. The word “hello” needs to be in quotes.

When you run it, the test panel will say hello! (Debug is an abbreviation for the “console.debug” command
often used by web programmers, which will also work the same way.)

The Pencil Code Library

An experienced programmer may ask “what functions are available to a Pencil Code program?”
About 100 of the functions that can be used in Pencil Code are listed on the block palette but Pencil Code
provides a large open-ended library of functions that goes far beyond what is listed in the palette.
Basically, anything that a web page you can do in Pencil Code.

Only a small fraction of these functions will be discussed in this teacher’s manual, but armed with
the names of the libraries below, you can find many examples and tutorials on the Internet with code that
can be used in Pencil Code. The libraries available to every Pencil Code program include:
 1. The Web Document Object Model (DOM). Standardized by international committee, these
functions are available to every page on the Internet.
2. jQuery. The most widespread web page library on the Internet, used by most popular websites.
We will introduce the workings of the jQuery library in Chapter 11.
3. jQuery-turtle. The turtle library for Pencil Code is an extension to jQuery. It provides all the
simple-to-use functions that we will take advantage of in the first part of this manual. Most of the
functions on the block palette are from this turtle library.
4. socket.io. This is a real-time communications library that enables immediate communication
between browsers..

Exploring the Vast Library Beyond Turtle Functions

Although the web programming world has too many features to cover in a single manual, all the
objects available to a Pencil Code program can all be explored using the test panel. For example, type
“location” to view the DOM “location” object, and they expand it by clicking on the triangle. The test panel
shows that “location” contains many functions and pieces of data including “href”: a program could use
this with the variable location.href.

Web programming functions are widespread enough that there are pages on the Internet about almost
every one of them. A Google search for “location.href” will bring up excellent pages that explain it.

How to Use This Book

Goals and Standards:

This teacher’s manual is designed to help students learn the basics of programming. It is intended to
assist a teacher in teaching an Introduction to Programming one semester course.

This manual shows how to take students step-by-step through the Pencil Code environment and start
writing simple programs. The chapters are organized around the fundamental programming constructs,
starting with basic concepts and then moving on to more advanced concepts. The manual also shows
how to transition students from block coding to text coding: programming for beginning students can be
intimidating, and starting with block-mode can reduce the level of intimidation. While the focus is on
learning programming, many of the programs are aimed at problem solving.

The content for this teacher’s manual is based around the CSTA K-12 Standards. Every chapter consists
of a section that does a crosswalk of the lesson plans to specific standards of the framework. The lessons
are based on programs designed by David and Deepa, many of which are available on
guide.pencilcode.net.
How should this book be read?

This manual is intended primarily for teachers who would like to teach programming using Pencil Code.
There are several sections in each chapter to help the teacher in each topic. The key concepts section
give the teacher a quick technical overview of the topic. The key terms identify important words / terms
that are used in the chapter. Finally the lesson plans guide the teacher through each program. A teacher
new to teaching programming can follow the lessons and teach the students as suggested in the manual.
The more experienced teacher can use the programs and use the lesson plans as suggestions on how to
teach the various concepts. Every program represents an idea on how to solve problem and how the
programming construct that is be taught can be used solve it. Teachers are encouraged to use the lesson
plans they find useful in the classroom and modify them to fit the needs of their students.

There is a suggested pacing for each lesson in the Suggested timeline section. Note that each chapter
has several lesson plans spanning over a couple of class periods. There is a separate pacing guide
(Appendix C) that gives the sequence and pacing on how the material provided by the manual should be
used.

While this is intended to be a teacher’s manual, an advanced student can peruse through the various
programs and use them as resources to funnel their creativity as they create their projects on Pencil
Code.

What grade level students is the material in the book appropriate for?
th th
This manual is intended for a high school, an introduction to programming course. Students 9 , 10 and
th th
possibly 11 graders would benefit from taking this course. An advanced 8 grade student could take this
course. A typical math pre-requisite of pre-algebra would be sufficient to take this course.