Skip to content

Latest commit

 

History

History
197 lines (156 loc) · 8.84 KB

README.md

File metadata and controls

197 lines (156 loc) · 8.84 KB
Raw

Plugins

How to get plugins

You can find plugins in the official app repository. The plugins are identified by the extension .json You need to download the plugins to load it. (In this guide I will use this plugin)

NOTE: You need to download the "raw" plugin by clicking on the "Raw" link on the .JSON file page. In other words, don't download https://github.com/sugarlabs/turtleblocksjs/blob/master/plugins/gmap.json , but do download https://raw.githubusercontent.com/sugarlabs/turtleblocksjs/master/plugins/gmap.json .

If you see the error message "Syntax Error: unexpected <" it means you probably did not download the "raw" plugin.

Nutrition Plugin

How to load plugins

On the Settings Palette found on the Option Toolbar (click it if it is not expanded) you will see this option:

Click it and a file chooser will appear.

In the file chooser select a plugin file (they have .json file suffixes) and click 'Open'.

The file will open and load new blocks into the palettes. Many plugins define their own palettes, so you will likely see a new palette button at the bottom of the column of buttons on the left side of the screen. (In the case of the translate plugin, new blocks will be added to a new palette, external)

The plugin is saved in the browser local storage so you don't need to reload it every time you run TurtleJS.

How to make a plugin

Plugins allow developers add new palettes and blocks to support additional functionality without having to make any changes to the core code of Turtle Blocks. Anyone is free to create and distribute extensions. If a plugin is present, it is loaded when the activity is launched and any palettes or blocks defined by the plugin are made available to the user.

Prerequisites

  • It facilitates debugging if you must have turtleblocksjs up and running. Use the following command to run it from your cloned repository: 

    python -m SimpleHTTPServer

  • To define the Turtle blocks in your plugin, you will need to know how to program in Javascript. The blocks are defined in a dictionary element. To understand better, check the [code of basicblocks.js] (https://github.com/sugarlabs/turtleblocksjs/blob/master/js/basicblocks.js)

  • We provide a tool to help you compile psuedo-code into JSON (see the section on Pluginify below). But you may also want to at least familiarize yourself with JSON

  • You may also want to familarize yourself with the Python plugin library plugins in Turtle Art

The Plugin Dictionary

You should explore some example plugins and learn how to install them.

Plugins are a dictionary of JSON-encoded components that incorporates: a flow-block dictionary, an arg-block dictionary, a block dictionary, a globals dictionary, a palette dictionary, and color dictionaries.

  • flow-block: commands that are evaluated when a flow block is run;
  • arg-block: commands that are evaluated when an arg block is run;
  • block: new blocks defined in the plugin;
  • globals: globals that you can reference throughout your code (Please use a unique name for your globals -- by convention, we have been prepending the plugin name to global variables, e.g., weatherSecretKey for the secretKey used in the weather plugin.);
  • palette: icons (in SVG format) associated with the palette;
  • fill-colors: hex color of the blocks;
  • stroke-colors: hex color for stroke of the blocks;
  • highlight-colors: hex color of the blocks when they are highlighted.

Resources

Resources available to your plugin vary by section. globals have access to the blocks class, where as flow-block and arg-block have access to both the blocks class and the logo class. Note that you can access the logo class from the blocks class by referencing blocks.logo.

Layout and Format

  
  {
    "GLOBALS":{},
    "FLOWPLUGINS":{},
    "ARGSPLUGINS":{},
    "BLOCKPLUGINS":{},
    "PALETTEFILLCOLORS":{},
    "PALETTESTROKECOLORS":{},
    "PALETTEHIGHLIGHTCOLORS":{},
    "PALETTEPLUGINS":{}
  }

Format for PALETTEFILLCOLORS, PALETTEHIGHLIGHTCOLORS and PALETTESTROKECOLORS:

{"[palette name]":"[color hex code]"}

Example: "PALETTESTROKECOLORS":{"external":"#3771c8"}

Format for PALETTEPLUGINS:

{"[palette name]":"[svg file code]"}

Example: "PALETTEPLUGINS":{"external":"<?xml version........</svg>"}

Format for blocks:

"{[name of the block]":"code of the block"}

Example: "BLOCKPLUGINS":{"translate":"var ....", "detectlang":"var ....", "setlang":"var ...."},

Pluginify

You can use pluginify.py to convert a .rtp (Readable Turtleblocks Plugin) to a .json plugin.

Writing plugins directly in JSON is tedious. To make the job easier for you, we have created the readable Turtle Blocks plugin (RTP) format. The syntax is available in python pluginify.py syntax

.rtp example

Once you have made an RTP file it is time to convert it to JSON so that it can be used in TurtleBlocksjs. To convert it to JSON, run python pluginify.py filename.rtp

.rtp syntax

References

Valid blocks styles in turtleblocksjs:

  • zeroArgBlock: E.g., penup, pendown
  • basicBlockNoFlow: E.g., break
  • oneArgBlock: E.g., forward, right
  • twoArgBlock: E.g., setxy. These are expandable.
  • oneArgMathBlock: E.g., sqrt
  • oneArgMathWithLabelBlock: E.g., box
  • twoArgMathBlock: E.g., plus, minus, multiply, divide. These are also expandable.
  • valueBlock: E.g., number, string. Value blocks get DOM textareas associated with them so their values can be edited by the user.
  • mediaBlock: E.g., media. Media blocks invoke a chooser and a thumbnail image is overlayed to represent the data associated with the block.
  • flowClampZeroArgBlock: E.g., start. A "child" flow is docked in an expandable clamp. There are no additional arguments and no flow above or below.
  • flowClampOneArgBlock: E.g., repeat. Unlike action, there is a flow above and below.
  • flowClampBooleanArgBlock: E.g., if. A "child" flow is docked in an expandable clamp. The additional argument is a boolean. There is flow above and below.
  • doubleFlowClampBooleanArgBlock: E.g., if then else. Two "child" flows are docked in expandable clamps. The additional argument is a boolean. There is flow above and below.
  • blockClampZeroArgBlock: E.g., forever. Unlike start, there is flow above and below.
  • blockClampOneArgBlock: E.g., action. A "child" flow is docked in an expandable clamp. The additional argument is a name. Again, no flow above or below.
  • booleanZeroArgBlock: E.g., mouse button.
  • booleanOneBooleanArgBlock: E.g., not
  • booleanTwoBooleanArgBlock: E.g., and
  • booleanOneArgBlock: E.g.,
  • booleanTwoArgBlock: E.g., greater, less, equal.
  • parameterBlock: E.g., color, shade, pensize

To use the block styles to create your blocks, let us go through an example

"translate":"var TranslateBlock = new ProtoBlock(\"translate\"); TranslateBlock.palette = palettes.dict[\"external\"]; blocks.protoBlockDict[\"translate\"] = TranslateBlock; TranslateBlock.oneArgMathBlock(); TranslateBlock.docks[0][2] = \"textout\"; TranslateBlock.docks[1][2] = \"textin\"; TranslateBlock.defaults.push(\"Hello\"); TranslateBlock.staticLabels.push(\"translate\");",

See the line TranslateBlock.oneArgMathBlock(); That is how you define the block style oneArgMathBlock to TranslateBlock. To define your own block, use any of the style methods listed above.

Example plugins

translate.json, weather.json, maths.rtp