diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..de68fe2 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +.DS_Store +*.komodoproject diff --git a/Closure.md b/Closure.md index dbcec48..16c8877 100644 --- a/Closure.md +++ b/Closure.md @@ -8,7 +8,7 @@ If so, then you are probably attempting to run the uncompiled version of Blockly ## Getting Closure -Getting Closure is quick and easy. Use Subversion to checkout a copy from [Closure's repository](https://code.google.com/p/closure-library/source/checkout): +Getting Closure is quick and easy. Use either Git or Subversion to checkout a copy from [Closure's repository](https://github.com/google/closure-library): ``` svn checkout https://github.com/google/closure-library/trunk closure-library-read-only @@ -18,4 +18,4 @@ Once you have the Closure files, place them next to Blocky's root directory and ![](closure_directory.png) -That's it. Blockly should now work in uncompiled mode. \ No newline at end of file +That's it. Blockly should now work in uncompiled mode. diff --git a/CreatingMutators.md b/CreatingMutators.md new file mode 100644 index 0000000..6ffb3e4 --- /dev/null +++ b/CreatingMutators.md @@ -0,0 +1,68 @@ +**[Creating Custom Blocks](wiki/CustomBlocks): [Defining a Block](wiki/DefiningBlocks): Creating Mutators** + +# Creating Mutators + +Advanced blocks may use a mutator to be even more dynamic and configurable. Mutators allow blocks to change in custom ways, beyond dropdown and text input fields. The most common example is the pop-up dialog which allows ` if ` statements to acquire extra ` else if ` and ` else ` clauses. But not all mutators are so visible. + +## mutationToDom and domToMutation + +The XML format used to load, save, copy, and paste blocks automatically captures and restores all data stored in editable fields. However, if the block contains additional information, this information will be lost when the block is saved and reloaded. + +A simple example of this is the ` Blockly.Language.text_trim ` block. This block normally reads "` trim spaces from [both] sides `" where ` [both] ` is a dropdown with options ` both `, ` left `, and ` right `. The latter two options result in a grammatical error, requiring the word ` sides ` to become ` side `. This is easy to accomplish, one just adds a validation function on the dropdown which changes the text field. When the dropdown is changed, so is the field. However, since the field is not editable, it is not saved or restored when converted to and from XML. To store this extra information, a mutation is stored. + +Saving mutation data is accomplished by adding a ` mutationToDom ` function in the block's definition. Here is the example from the aforementioned ` text_trim ` block: +``` + mutationToDom: function() { + // Save whether the 'sides' field should be plural or singular. + var container = document.createElement('mutation'); + var plural = (this.getFieldValue('MODE') == 'BOTH'); + container.setAttribute('plural', plural); + return container; + } +``` +This function is called whenever a block is being written to XML. If the function does not exist or returns null, then no mutation is recorded. If the function exists and returns a 'mutation' XML element, then this element (and any properties or child elements) will be stored as part of the block's XML representation. In the above case the XML will include this tag: ` ` + +The inverse function is ` domToMutation ` which is called whenever a block is being restored from XML. Here is the example from the aforementioned ` text_trim ` block: +``` + domToMutation: function(xmlElement) { + // Restore the 'sides' field as plural or singular. + var plural = (xmlElement.getAttribute('plural') == 'true'); + this.setFieldText(plural ? 'sides' : 'side', 'SIDES'); + } +``` +If this function exists, it is passed the block's 'mutation' XML element. The function may parse the element and reconfigure the block based on the element's properties and child elements. In the above case, a field is changed from singular to plural. + +## compose and decompose + +Mutation dialogs allow a user to explode a block into smaller sub-blocks and reconfigure them, thereby changing the shape of the original block. The dialog button is added to a block in its [init function](wiki/DefiningBlocks#Init_Function). + +``` + this.setMutator(new Blockly.Mutator(['controls_if_elseif', 'controls_if_else'])); +``` + +![https://blockly.googlecode.com/svn/wiki/controls_if.png](https://blockly.googlecode.com/svn/wiki/controls_if.png) + +The ` setMutator ` function takes one argument, a new Mutator. The Mutator constructor takes one argument, a list of sub-blocks to show in the mutator's toolbox. Creating a mutator for a sub-block is not advised at this time. + +When a mutator dialog is opened, the block's ` decompose ` function is called to populate the mutator's workspace. +``` + decompose: function(workspace) { + var ifBlock = new Blockly.Block(workspace, 'controls_if_if'); + ifBlock.initSvg(); + ... + return ifBlock; + } +``` + +At a minimum this function must create and initialize a top-level block for the mutator dialog, and return it. This function should also populate this top-level block with any sub-blocks which are appropriate. + +When a mutator dialog saves its content, the block's ` compose ` function is called to modify the original block according to the new settings. +``` + compose: function(ifBlock) { + ... + } +``` + +This function is passed the top-level block from the mutator's workspace (the same block that was created and returned by the ` compose ` function). Typically this function would spider the sub-blocks attached to the top-level block, then update the original block accordingly. + +This function should take care to ensure that any blocks already connected to the original block should remain connected to the correct inputs, even if the inputs are reordered. \ No newline at end of file diff --git a/Credits.md b/Credits.md new file mode 100644 index 0000000..ef31b1b --- /dev/null +++ b/Credits.md @@ -0,0 +1,22 @@ +(TODO: Add table of contents.) +# Engineers + +## Core + * Neil Fraser + * Quynh Neutron + * Chris Pirich + * Ellen Spertus + * Phil Wagner + +## Bug fixes + * Spencer Gordon + +# Documentation + +In addition to documentation by the engineers, we are grateful to: + + * Janet Miller + +# Translators + +Siebrand Mazeland helped immensely by setting us up at http://translatewiki.net, which we have been using. Anatoly Techtonik helped with several Serbian languages. \ No newline at end of file diff --git a/FAQHighLevel.md b/FAQHighLevel.md new file mode 100644 index 0000000..9f51cee --- /dev/null +++ b/FAQHighLevel.md @@ -0,0 +1,65 @@ +

FAQ - High Level

+ +These are the most frequently asked questions relating to the purpose of Blockly and what it is (and isn't) good for. + +(TODO: Add table of contents.) + +## How does Blockly relate to Scratch, App Inventor, etc.? + +### Similarities + +All are [visual programming languages](https://en.wikipedia.org/wiki/Visual_programming_languages). [Historically](http://web.mit.edu/newsoffice/2010/android-abelson-0819.html), Blockly was influenced by [App Inventor](https://en.wikipedia.org/wiki/App_inventor), and App Inventor was influenced by Scratch, which was influenced by StarLogo and Etoys. + +The progenitor of all of these was [Logo](https://en.wikipedia.org/wiki/Logo_(programming_language)) (not itself a visual programming language), which was co-created by [Seymour Papert](https://en.wikipedia.org/wiki/Seymour_Papert) after working with [Jean Piaget](https://en.wikipedia.org/wiki/Jean_Piaget), one of the proponents of [constructivist learning theory](https://en.wikipedia.org/wiki/Constructivism_(learning_theory)). + +### Differences + +Rather than being a stand-alone program, Blockly is a code editor that can be embedded into a larger project. For more information, see the page of [Alternatives](wiki/Alternatives) to Blockly. + +## Why are graphics better than text? + +Novice programmers are fighting two battles at once: the fight to translate their ideas into logical statements, and the fight to keep the syntax legal. Blockly makes it completely impossible to make a syntax error. There are no unbalanced parentheses, no unescaped strings, no missing semicolons. Blockly allows novice programmers to concentrate on the logic. + +Additionally, many non-programmers find a blank screen with a blinking cursor to be daunting. How does one start? Blockly allows these users to browse through the menu of blocks and start plugging things together. + +Even seasoned programmers can benefit by starting a script with Blockly. If one is writing a quick script using an unfamiliar API (such as office suite automation) it can take a long time to learn that API. With Blockly one can plug the blocks together for a first draft, then switch to the generated code to keep going. + +## How does Blockly scale to large programs? + +It doesn't, at least not yet. Blockly is currently designed for creating relatively small scripts. We have ideas for semantic zooming and other techniques that would allow Blockly to scale. But that is not our current focus. Please do not attempt to maintain the Linux kernel using Blockly. + +## Why not use a data-flow metaphor? + +Data-flow is often a simpler way to represent certain common tasks. However we chose not to use it for two reasons. The first is that data-flow languages usually fail badly when attempting to solve tasks outside their domain. The second is that the generated code looks nothing like the visual data-flow representation, which serves as a barrier for the user graduating from the visual programming language to a text-based code editor. We feel strongly that users should not be locked in. + +## Isn't Blockly too low level? + +If the user wants to do anything truly original, they must have access to basic math and logic operations. However, once the basics are taken care of, Blockly offers a rich (and constantly growing) set of higher-level blocks. Such as computing the standard deviation of a list, using a single block. + +Additionally, most of the high-level features would reside in the domain-specific API blocks provided to Blockly by host applications. For example a game engine using Blockly could have a block that moves a sprite until it hits a wall. + +## Can Blockly import from code? + +Blockly can export from blocks to JavaScript, Python, and Dart. However we have no plans to import from one of these languages to Blockly. The main issue is that modern programming languages are fearsomely complex, with closures, list comprehension, operator overloading, etc. Importing arbitrary code would have a high development cost compared with a limited real-world utility. + +## Can I run Blockly without an Internet connection? + +Yes, although you won't be able to save programs for later use. See [download instructions](http://google.github.io/blockly/hoc.html). + +## Why isn't there an installer? + +Blockly is a technical preview aimed at application developers. At this point it is not an end-user application. Users who are not comfortable with syncing Subversion would most likely be disappointed in the current codebase. They are encouraged, however, to use our [public server](https://blockly-demo.appspot.com) or to [download a version to run off-line](http://google.github.io/blockly/hoc.html). + +## How can I get a young person started with programming? + +We recommend trying out the [Hour of Code tutorials](http://code.org/learn). (The Code.org Angry Birds tutorial uses Blockly.) If one doesn't appeal to the student, try another. Many of the tutorial providers have additional material beyond the first hour. + +## Why isn't Blockly available in my native language? + +Because nobody has [volunteered to translate it yet](wiki/Translation). Please do so. + + + +--- + +See also: [Language Design Philosophy](wiki/Language) \ No newline at end of file diff --git a/InjectingResizable.md b/InjectingResizable.md new file mode 100644 index 0000000..604c5e6 --- /dev/null +++ b/InjectingResizable.md @@ -0,0 +1,76 @@ +**[Installation](wiki/Installation): Injecting Resizable Blockly** + +# Introduction + +The most flexible way to put Blockly into a web page is to inject it into an 'iframe'. +This is slightly more complicated than [injecting Blockly into a div](wiki/InjectingFixedSize), but using an iframe allows +Blockly to resize to fill the page, and it allows more than one instance of Blockly to exist on the page. +The only limitation of using an iframe is that for security reasons Blockly will not execute in Chrome when served directly off the local file system with the ` file:// ` protocol. + +## Injection + +Include the following snippet in your web page: + +``` + + +``` + +The iframe is where Blockly will appear. It will be sized as needed using tables, CSS, or JavaScript. The next step is to create the frame for the editor. Here's a good starting snippet for ` frame.html `. + +``` + + + + + + + + + + + + + + +``` + +The script tags in the above snippet load the core Blockly script (` blockly_compressed.js `), the core blocks set (` blocks_compressed.js `), and selects the user's language to be English (` msg/js/en.js `). + +Adjust the paths as needed to enable inclusion of these script files. Likewise, the ` Blockly.inject ` line has a path that needs to point to Blockly's root directory so that media such as the trash can and the sounds may be loaded. + +Test the page in a browser. You should see Blockly's editor filling the iframe, with four block categories in the toolbox. + +Here is [a live demo](https://blockly-demo.appspot.com/static/demos/iframe/index.html) of an iframe nested in a table that fills the screen. \ No newline at end of file diff --git a/Klingon.md b/Klingon.md index be98f3c..de9fd69 100644 --- a/Klingon.md +++ b/Klingon.md @@ -3,6 +3,8 @@ On 1 April 2014 we released a Klingon is an unusual choice for a translation, and on this page we wanted to give some context on the hows and whys, as well as how you can help. +![](klingon.png) + ## Why? Blockly has been translated into over 40 languages, including RTL languages such @@ -54,4 +56,4 @@ offer useful context for those new to Klingon. All phrases _must_ be manually translated. Bing Translate produces such translations as ` "Library" -> "be'nI''a'wI', Datu'" ` which actually means ` "discover my big sister" `. -Clearly this would be an inadvisable phrase to use in a Klingon environment. \ No newline at end of file +Clearly this would be an inadvisable phrase to use in a Klingon environment. diff --git a/Language.md b/Language.md new file mode 100644 index 0000000..4a5c006 --- /dev/null +++ b/Language.md @@ -0,0 +1,11 @@ +# Language Design Philosophy + +The primary users of Blockly are novice programmers. However, in addition to wanting to enable these users to do useful work, we also want to actively support a smooth migration to JavaScript once they outgrow Blockly. This drives several design decisions. + +## One-based Lists + +Novice programmers freak out when they encounter zero-based lists for the first time. As a result, Blockly follows the lead of Lua and Lambda Moo by making list and string indexing one-based. + +## Variable Names + +Novice programmers do not expect that ` location_X ` and ` location_x ` are different variables. As a result, Blockly follows the lead of BASIC and HTML by making variables case-insensitive. Also, Blockly does not require that variables conform to the typical ` [_A-Za-z][_A-Za-z0-9]* ` scheme. If one wants to name a variable ` List of zip codes ` or \ No newline at end of file diff --git a/LanguageGenerators.md b/LanguageGenerators.md new file mode 100644 index 0000000..64a0575 --- /dev/null +++ b/LanguageGenerators.md @@ -0,0 +1,74 @@ +**[Installation](wiki/Installation): Language Generators** + +# Introduction + +Most applications of Blockly require the user's program to be translated into JavaScript, +Python, Dart, or some other language. This action is performed on the client-side by Blockly. + +## Generating Code + +The first step is to include the generator for the language in question. +Right after ` blockly_compressed.js ` is loaded, load the generator(s) needed. +Here is the JavaScript generator: + +``` + +``` + +The user's blocks may be exported to code at any time from your application with this call: + +``` + var code = Blockly.JavaScript.workspaceToCode(); +``` + +Replace ` JavaScript ` with ` Python ` or ` Dart ` in all preceding lines to switch the language generated. + +## Realtime Generation + +Generating code is an extremely fast operation, so there's no harm in calling this function frequently. A common strategy is to generate and display code in realtime by adding a listener to Blockly's change event: + +``` + function myUpdateFunction() { + var code = Blockly.JavaScript.workspaceToCode(); + document.getElementById('textarea').value = code; + } + Blockly.addChangeListener(myUpdateFunction); +``` + +## Running JavaScript Code + +If JavaScript code is generated, it may be executed right in the browser: + +``` + Blockly.JavaScript.addReservedWords('code'); + var code = Blockly.JavaScript.workspaceToCode(); + try { + eval(code); + } catch (e) { + alert(e); + } +``` + +Basically, the above snippet just generates the code and evals it. However, there are a couple of refinements. +One refinement is that the eval is wrapped in a ` try `/` catch ` so that any runtime errors are visible, instead of failing quietly. +Another refinement is that ` code ` is added to the list of reserved words so that if the user's code contains a variable of that name it will be automatically renamed instead of colliding. Any local variables should be reserved in this way. + +## Infinite Loops + +Although the resulting code is guaranteed to be syntactically correct at all times, it may contain infinite loops. +Since solving the [Halting problem](https://en.wikipedia.org/wiki/Halting_problem) is beyond Blockly's scope (!) the best approach for dealing with these cases is to maintain a counter and decrement it every time an iteration is performed. +To accomplish this, just set ` Blockly.JavaScript.INFINITE_LOOP_TRAP ` to a code snippet which will be inserted into every loop and every function. Here is an example: + +``` + window.LoopTrap = 1000; + Blockly.JavaScript.INFINITE_LOOP_TRAP = 'if(--window.LoopTrap == 0) throw "Infinite loop.";\n'; + var code = Blockly.JavaScript.workspaceToCode(); +``` + +## JS Interpreter + +Instead of using ` eval() `, a completely different way to run JavaScript code is to use a [JavaScript Interpreter](wiki/JSInterpreter). This allows for step-by-step execution at any speed. Blocks may be highlighted as they are executed. Infinite loops are no longer an issue. Security is guaranteed. The JS Interpreter is recommended for any non-trivial applications. + +## Example + +Here is [a live demo](https://blockly-demo.appspot.com/static/demos/generator/index.html) of generating and executing JavaScript. \ No newline at end of file diff --git a/TranslationForDevelopers.md b/TranslationForDevelopers.md index d01dab7..bda291e 100644 --- a/TranslationForDevelopers.md +++ b/TranslationForDevelopers.md @@ -1,7 +1,5 @@ This document provides what developers should know about Blockly translations. Translators should read [this document](Translation) instead. -(TODO: Add table of contents.) - # Introduction Internationalization (i18n) is one of Blockly's top priorities. See, for example, [CS in VN](https://neil.fraser.name/news/2013/03/16/). Blockly supports right-to-left and left-to-right scripts, and the [Puzzle application](https://blockly-demo.appspot.com/static/apps/puzzle/index.html) has been translated into over 50 languages. We look forward to getting all of Blockly translated into that many languages. diff --git a/Tutorial_CreateYourFirstBlock.md b/Tutorial_CreateYourFirstBlock.md new file mode 100644 index 0000000..6d6955e --- /dev/null +++ b/Tutorial_CreateYourFirstBlock.md @@ -0,0 +1,260 @@ +# Tutorial - Create and add your first block - Step-by-step guide + +![http://i289.photobucket.com/albums/ll234/syntax_photos/BlockFactory_MoveTo_Preview_zps16065a5d.png](http://i289.photobucket.com/albums/ll234/syntax_photos/BlockFactory_MoveTo_Preview_zps16065a5d.png) +
+

Introduction

+ +This tutorial a complete walk though for adding a block to the turtle app.
+By the end of the tutorial you will have a fully functional new block in the turtle tool box.
+This new block, called move to will move the turtle directly to a specified x/y location.
+
+
+

Before you begin

+ +The basic tools you need for this tutorial are:
+
+ + + + + + + + +
+

Installing Subversion

+
+For Linux its a simple matter of running this in a terminal window:
+
	> sudo apt-get install subversion

+
+ +For Windows see http://tortoisesvn.net/ + + +

Install the Blockly source code

+
+To get the latest verison of Blockly run the following from a terminal window:
+
	> svn checkout http://blockly.googlecode.com/svn/trunk/ blockly

+
+Once everything is downloaded you will have a new Blockly folder containing the code and examples.
+Since this tutorial modifies the turtle app files you might want to copy the folder and contents for backup purposes.
+The folder in question is called "turtle" and exists in the "blockly/apps/" folder.
+
+
+

Pre-checks

+ +Open the Blockly/apps/turtle folder. Test the turtle app by double-clicking the index.html file.
+Make sure it runs in the browser.
+
+The files which are going to be modified are turtle.js, blocks.js, and template.soy within the folder.
+
+
+
+

Step 1 - Designing the block

+ +Let's start by designing the block itself. Open the online block designer. This designer helps to define how the new block will look and function.
+
+Open this link: https://blockly-demo.appspot.com/static/apps/blockfactory/index.html + +Design the block as per this layout:
+
+ + +The preview block should look like this:
+
+ + +Once complete you can see two sets of generated code in the tables to the right.
+
+

Blockly Language Code

+
Blockly.Blocks['move_to'] = {

+  init: function() {

+    this.setHelpUrl('http://www.example.com/');

+    this.setColour(160);

+    this.appendDummyInput()

+	.appendField("move to");

+    this.appendValueInput("XPOS")

+	.setCheck("Number")

+	.appendField("x");

+    this.appendValueInput("YPOS")

+	.setCheck("Number")

+	.appendField("y");

+    this.setInputsInline(true);

+    this.setPreviousStatement(true);

+    this.setNextStatement(true);

+    this.setTooltip('');

+}

+
+ +

Blockly JavaScript stub code

+
Blockly.JavaScript['move_to'] = function(block) {

+  var value_xpos = Blockly.JavaScript.valueToCode(block, 'XPOS', Blockly.JavaScript.ORDER_ATOMIC);

+  var value_ypos = Blockly.JavaScript.valueToCode(block, 'YPOS', Blockly.JavaScript.ORDER_ATOMIC);

+  // TODO: Assemble JavaScript into code variable.

+  var code = '...';

+  return code;

+};

+
+ +For more details on block design see:
+https://code.google.com/p/blockly/wiki/DefiningBlocks + +For more details on the code generation see:
+https://code.google.com/p/blockly/wiki/GeneratingCode + +
+

Step 2 - Editing the blocks.js file

+ + +Open blocks.js via a standard text editor or IDE.
+
+Taking the above two blocks of code, paste both parts in after this section of code.
+
+
Blockly.JavaScript['draw_move'] = function(block) {

+  ...

+};

+
+ +The code will now need some modification. Replace the source code above with:
+
+
Blockly.Blocks['draw_moveto'] = {

+  // move turtle to absolute x,y location

+  // for reference 0,0 is top/let and 200,200 is centre

+  init: function() {

+    this.setHelpUrl('');

+    this.setColour(160);

+    this.appendDummyInput()

+        .appendField(BlocklyApps.getMsg('Turtle_moveTo'));

+    this.appendValueInput("XPOS")

+        .setCheck("Number")

+        .appendField("x");

+    this.appendValueInput("YPOS")

+        .setCheck("Number")

+        .appendField("y");

+    this.setInputsInline(true);

+    this.setPreviousStatement(true);

+    this.setNextStatement(true);

+    this.setTooltip(BlocklyApps.getMsg('Turtle_moveToTooltip'));

+  }

+};

+

+Blockly.JavaScript['draw_moveto'] = function(block) {

+  // Generate JavaScript for moving to absolute position

+  var xpos = Blockly.JavaScript.valueToCode(block, 'XPOS', Blockly.JavaScript.ORDER_NONE) || '0';

+  var ypos = Blockly.JavaScript.valueToCode(block, 'YPOS', Blockly.JavaScript.ORDER_NONE) || '0';

+  return 'Turtle.moveTo(' + xpos + ',' + ypos + ', \'block_id_' + block.id + '\');\n';

+};

+
+ +Now save the file changes.
+
+
+
+

Step 3 - Editing the turtle.js file

+ +Open turtle.js via a standard text editor or IDE.
+
+Look for the Turtle API section. It comes under the // Turtle API comment.
+
+Add the following API block of code after the Turtle.moveBackward{} API block.
+
	Turtle.moveTo = function(xpos, ypos, id) {

+	  BlocklyApps.log.push(['MT', xpos, ypos, id]);

+	};

+
+To cater for this API call another piece of code needs adding into the Turtle.step{} block.
+Drop this piece of code inside the switch (command) {...} block of the Turtle.step function.
+A sensible place is between the 'FD' (Forward) and 'RT' (Right Turn) sections:
+
    case 'MT': // Move To

+		Turtle.x=values[0];

+		Turtle.y=values[1];

+		break;

+
+ +Now save the file changes.
+
+
+
+

Step 4 - Editing the template.soy file

+ +Open the template.soy file for editing.
+
+Within the {template .messages} block open up some space and paste in the following.
+This is helper/documentation for the move_to block.
+A recommended location is after the <span id="Turtle_moveBackward"> ... ></span> part in the document.
+
    <span id="Turtle_moveToTooltip">{msg meaning="Turtle.moveToTooltip" desc="Moves the turtle to an absolute x and y location via 2 numbers. Top left is 0,0 whilst centre is 200,200 (default)."}Moves turtle to the absolute x/y location without drawing a mark{/msg}</span>

+    <span id="Turtle_moveTo">{msg meaning="Turtle.moveTo" desc="block text - Infinitive or imperative of a verb to move the turtle to an absolute x and y location via 2 numbers. Top left is 0,0 whilst centre is 200,200 (default)."}move to{/msg}</span>

+
+In order to make the new block appear in the tool box scroll down to the {template .toolbox} section and insert the following. A logical place for the "move to" block to appear in the tool box is after existing the "draw move" block. Therefore, paste this section after 
 ... 

+

+Unknown end tag for 

+

+
+ +
	<block type="draw_moveto">

+		<value name="XPOS">

+			<block type="math_number">

+				<field name="NUM">200</field>

+			</block>

+		</value>

+		<value name="YPOS">

+			<block type="math_number">

+				<field name="NUM">200</field>

+			</block>

+		</value>

+	</block>

+
+ +Now save the file changes.
+
+
+
+

Step 5 - Compling the code changes

+ +Before continuing ensure all changes to the turtle.js, blocks.js, and template.soy files have been saved.
+
+Now that the code has been entered it's time to compile the changes.
+Open up a terminal window and navigate into the turtle folder. For example:
+
> cd <myfolder>/blockly/apps/turtle

+
+Look at the top of the template.soy document. You should find an entry like this:
+
	java -jar ../_soy/SoyToJsSrcCompiler.jar --outputPathFormat generated/en.js --srcs ../common.soy,template.soy

+
+Copy this line then paste it into the terminal window. After a few seconds the compiling process should complete. If all went well (no reported errors) you can now test the new block.
+
+
+
+

Step 6 - Testing the new block

+ +From the turtles folder double-click index.html. This should launch the turtle blockly program in your browser.
+Open the toolbox and check to see if the new ''move to'' block is present.
+Hovering over the new block should reveal the help text popup balloon.
+
+Constuct a simple test block and run the code. Example:
+
+ + +You can check that the code is being correctly to generated by pressing the code button:
+
+ + +The generated code should look like this:
+
var x_position;

+

+Turtle.turnRight(30);

+for (x_position = 100; x_position <= 300; x_position += 15) {

+  Turtle.moveTo(x_position,220);

+  Turtle.moveForward(50);

+}

+
+ +

+ +

END OF TUTORIAL

+ +That's your first block under way. If you want to modify the blocks functionality/appearance then its just a matter of changing the code and re-compiling (as per Step 5).
+
+Note that you can leave the browser open but you will need to refresh the page in order to see new changes take place.
+
+(TODO: Link to Google+ page.)
+
+Please send any questions you have to the support group, not as a comment to this page. \ No newline at end of file diff --git a/appendField.png b/appendField.png index 5e8d4c5..37f20ae 100644 Binary files a/appendField.png and b/appendField.png differ diff --git a/appendFieldCheckbox.png b/appendFieldCheckbox.png index f96de60..a7331a8 100644 Binary files a/appendFieldCheckbox.png and b/appendFieldCheckbox.png differ diff --git a/appendFieldColour.png b/appendFieldColour.png index 8edea12..2ffd66d 100644 Binary files a/appendFieldColour.png and b/appendFieldColour.png differ diff --git a/appendFieldDropdown.png b/appendFieldDropdown.png index 68d6611..f41fb02 100644 Binary files a/appendFieldDropdown.png and b/appendFieldDropdown.png differ diff --git a/appendFieldImage.png b/appendFieldImage.png index e38f047..cf92dc8 100644 Binary files a/appendFieldImage.png and b/appendFieldImage.png differ diff --git a/appendFieldTextInput.png b/appendFieldTextInput.png index 996656a..8dd001d 100644 Binary files a/appendFieldTextInput.png and b/appendFieldTextInput.png differ diff --git a/appendFieldVariable.png b/appendFieldVariable.png index fd03ea6..1de0fd8 100644 Binary files a/appendFieldVariable.png and b/appendFieldVariable.png differ diff --git a/appendInput.png b/appendInput.png index fc4c1f7..0efb853 100644 Binary files a/appendInput.png and b/appendInput.png differ diff --git a/closure_alert.png b/closure_alert.png index 8590eb9..93e8396 100644 Binary files a/closure_alert.png and b/closure_alert.png differ diff --git a/controls_if.png b/controls_if.png index d15040e..01ba8af 100644 Binary files a/controls_if.png and b/controls_if.png differ diff --git a/count-with.png b/count-with.png index cb73bb7..ce80c9b 100644 Binary files a/count-with.png and b/count-with.png differ diff --git a/help/And_Or.md b/help/And_Or.md deleted file mode 100644 index d500c14..0000000 --- a/help/And_Or.md +++ /dev/null @@ -1,10 +0,0 @@ -# The **And Or** Block - -To access the **And Or** Block, click **Logic**. - -| **Option** | **Description** | -|:-----------|:----------------| -| **and** | Place this between two blocks to make the program do something whenever both conditions exist at the same time. Example: In the Maze program, you might want your player to move forward whenever there are walls on both sides. To do this, use **wall to the right?** and **wall to the left?**.| -| **or** |Place this between two blocks when you want the program to do something whenever at least one of the conditions exist.| - -**Note**: The **And Or** block fits with blocks that it might not be useful with. For example, it fits with the **True** block. \ No newline at end of file diff --git a/help/Colour.md b/help/Colour.md index 0bc3d97..465fb19 100644 --- a/help/Colour.md +++ b/help/Colour.md @@ -1,4 +1,3 @@ -(TODO: Add table of contents.) # Introduction @@ -45,4 +44,4 @@ Blockly colours are represented as text of the form "#rrggbb" where "rr", "gg", which prints "#ff0000". -Note that [blending light is different from blending pigments](http://www.newton.dep.anl.gov/askasci/gen99/gen99557.htm). Blending red, green, and blue light in equal ratios yields white light, while blending red, green, and blue paint yields a muddy colour. \ No newline at end of file +Note that [blending light is different from blending pigments](http://www.newton.dep.anl.gov/askasci/gen99/gen99557.htm). Blending red, green, and blue light in equal ratios yields white light, while blending red, green, and blue paint yields a muddy colour. diff --git a/help/IfElse.md b/help/IfElse.md index 8e91ef4..97e9165 100644 --- a/help/IfElse.md +++ b/help/IfElse.md @@ -1,4 +1,3 @@ -(TODO: Add table of contents.) # Introduction diff --git a/help/Lists.md b/help/Lists.md index ac7e6a4..838906b 100644 --- a/help/Lists.md +++ b/help/Lists.md @@ -1,4 +1,3 @@ -(TODO: Add table of contents.) # Introduction diff --git a/help/Logic.md b/help/Logic.md index 0fe2a97..663db62 100644 --- a/help/Logic.md +++ b/help/Logic.md @@ -1,4 +1,3 @@ -(TODO: Add table of contents.) # Introduction @@ -20,29 +19,42 @@ Boolean values can also be stored in variables and passed to procedures, the sam # Blocks -If a block expects a Boolean value as an input, it interprets an absent input as **false**. An example is provided below. Non-Boolean values cannot be directly plugged in where Boolean values are expected, although it is possible (but inadvisable) to store a non-Boolean value in a variable, then plug that into the input. Neither of these practices are recommended, and their behavior could change in future versions of Blockly. +If a block expects a Boolean value as an input, it usually interprets an absent input as **false**. An example is provided below. Non-Boolean values cannot be directly plugged in where Boolean values are expected, although it is possible (but inadvisable) to store a non-Boolean value in a variable, then plug that into the input. Neither of these practices are recommended, and their behaviour could change in future versions of Blockly. ## Values A single block, with a dropdown specifying either **true** or **false**, can be used to get a boolean value: -![](help/boolean-true-false.png) +![](help/logic-true-false.png) + +## comparisons + +There are six comparison operators. Each takes two inputs (normally numbers) and returns true or false depending on how the inputs compare with each other. + +![](help/logic-compare.png) + +The six operators are: equals, not equals, less than, less than or equal, greater than, greater than or equal. + +## logical operations + +The **and** block will return **true** only if both of its two inputs are also true. + +![](help/logic-and.png) + +The **or** block will return **true** if either of its two inputs are true. + +![](help/logic-or.png) ## not The **not** block converts its Boolean input into its opposite. For example, the result of: -![](help/boolean-not-true.png) +![](help/logic-not-true.png) is false. As mentioned above, if no input is provided, a value of **true** is assumed, so the following block produces the value **false**: -![](help/boolean-not.png) +![](help/logic-not.png) Leaving an input empty is not recommended, however. - -## comparisons - - -## logical operations \ No newline at end of file diff --git a/help/Loops.md b/help/Loops.md index 7dcbd22..93d08b9 100644 --- a/help/Loops.md +++ b/help/Loops.md @@ -1,4 +1,3 @@ -(TODO: Add table of contents.) # Introduction and Terminology @@ -67,4 +66,4 @@ The following program prints "alpha" on the first iteration of the loop. On the The **break out of loop** block provides [an early exit from a loop](https://en.wikipedia.org/wiki/Control_flow#Early_exit_from_loops). The following program prints "alpha" on the first iteration and "breaks out" of the loop on the second iteration when the loop variable is equal to "beta". The third item in the list is never reached. -![](help/control-for-each-break.png) \ No newline at end of file +![](help/control-for-each-break.png) diff --git a/help/Text.md b/help/Text.md index bd1d7e0..58badb5 100644 --- a/help/Text.md +++ b/help/Text.md @@ -1,4 +1,3 @@ -(TODO: Add table of contents.) # Introduction @@ -146,4 +145,4 @@ This is what the current version of the pop-up window looks like: There is also a version of the block for getting a number from the user: -![](help/text-get-number.png) \ No newline at end of file +![](help/text-get-number.png) diff --git a/help/True_False.md b/help/True_False.md deleted file mode 100644 index 4a710fb..0000000 --- a/help/True_False.md +++ /dev/null @@ -1,15 +0,0 @@ -# The **True False** Block - -To access the **True False** Block, click **Logic**. - -| **Option** | **Description** | -|:-----------|:----------------| -| **true** | Useful when combined with another block, like the **Repeat** block, to tell the program to do something whenever a condition is true.| -| **false** |Useful when combined with another block, like the **Repeat** block, to tell the program to do something whenever a condition is true.| - -**Tip**: Combine the **True False** block with the [Repeat](Repeat) block to write statements like: - - * **Repeat while** true. - * **Repeat until** false. - -**Note**: The **True False** block fits with other blocks, like the **And Or** block, that it might not be useful with. \ No newline at end of file diff --git a/help/Variables.md b/help/Variables.md index 3a7f3d5..549d758 100644 --- a/help/Variables.md +++ b/help/Variables.md @@ -1,4 +1,3 @@ -(TODO: Add table of contents.) # Introduction diff --git a/help/boolean-not-true.png b/help/boolean-not-true.png deleted file mode 100644 index 61be030..0000000 Binary files a/help/boolean-not-true.png and /dev/null differ diff --git a/help/boolean-not.png b/help/boolean-not.png deleted file mode 100644 index 2947d02..0000000 Binary files a/help/boolean-not.png and /dev/null differ diff --git a/help/boolean-true-false.png b/help/boolean-true-false.png deleted file mode 100644 index 3de7e0b..0000000 Binary files a/help/boolean-true-false.png and /dev/null differ diff --git a/help/colour-select.png b/help/colour-select.png index d071776..5a33c75 100644 Binary files a/help/colour-select.png and b/help/colour-select.png differ diff --git a/help/if-else.png b/help/if-else.png index 82d1404..2ad8f8f 100644 Binary files a/help/if-else.png and b/help/if-else.png differ diff --git a/help/logic-and.png b/help/logic-and.png new file mode 100644 index 0000000..f0faf0a Binary files /dev/null and b/help/logic-and.png differ diff --git a/help/logic-compare.png b/help/logic-compare.png new file mode 100644 index 0000000..9469899 Binary files /dev/null and b/help/logic-compare.png differ diff --git a/help/logic-not-true.png b/help/logic-not-true.png new file mode 100644 index 0000000..0b45fa6 Binary files /dev/null and b/help/logic-not-true.png differ diff --git a/help/logic-not.png b/help/logic-not.png new file mode 100644 index 0000000..678983c Binary files /dev/null and b/help/logic-not.png differ diff --git a/help/logic-or.png b/help/logic-or.png new file mode 100644 index 0000000..7da2961 Binary files /dev/null and b/help/logic-or.png differ diff --git a/help/logic-true-false.png b/help/logic-true-false.png new file mode 100644 index 0000000..c6676d8 Binary files /dev/null and b/help/logic-true-false.png differ diff --git a/i18n_block_diagram.png b/i18n_block_diagram.png index 9c119c5..27a3717 100644 Binary files a/i18n_block_diagram.png and b/i18n_block_diagram.png differ diff --git a/klingon.png b/klingon.png new file mode 100644 index 0000000..09f30ab Binary files /dev/null and b/klingon.png differ diff --git a/operatorPrecedence.png b/operatorPrecedence.png index 5008ac3..6984da1 100644 Binary files a/operatorPrecedence.png and b/operatorPrecedence.png differ diff --git a/setInputsInline.png b/setInputsInline.png index b32b16d..7b9b4a8 100644 Binary files a/setInputsInline.png and b/setInputsInline.png differ diff --git a/setNextStatement.png b/setNextStatement.png index fed9d68..7fd38ed 100644 Binary files a/setNextStatement.png and b/setNextStatement.png differ diff --git a/setOutput.png b/setOutput.png index 6dd8753..054a73a 100644 Binary files a/setOutput.png and b/setOutput.png differ diff --git a/setPreviousStatement.png b/setPreviousStatement.png index 7cd7755..8ae2f59 100644 Binary files a/setPreviousStatement.png and b/setPreviousStatement.png differ diff --git a/text_length.png b/text_length.png index 19cca57..7ef8a56 100644 Binary files a/text_length.png and b/text_length.png differ