Plugins ======= How to get plugins ------------------ You can find plugins in the [official app repository](https://github.com/walterbender/turtleblocksjs/plugins). 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)](https://github.com/walterbender/turtleblocksjs/blob/master/plugins/translate.json) > 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/walterbender/turtleblocksjs/blob/master/plugins/gmap.json > , > but do download > > https://raw.githubusercontent.com/walterbender/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](https://github.com/walterbender/turtleblocksjs/raw/master/screenshots/foodplugin.png "The 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/walterbender/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](http://en.wikipedia.org/wiki/JSON) * You may also want to familarize yourself with the Python plugin library [plugins in Turtle Art](http://wiki.sugarlabs.org/go/Activities/Turtle_Art/Plugins) The Plugin Dictionary --------------------- You should explore [some example plugins](https://github.com/walterbender/turtleblocksjs/blob/master/README.md#Plugins) and learn [how to install them.](https://github.com/walterbender/turtleblocksjs/blob/master/README.md#how-to-load-plugins) 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":""}``` 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](https://github.com/walterbender/turtleblocksjs/blob/master/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](https://github.com/walterbender/turtleblocksjs/blob/master/plugins/finance.rtp) 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](https://github.com/walterbender/turtleblocksjs/blob/master/pluginify.py#L33) 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](https://github.com/walterbender/turtleblocksjs/blob/master/plugins/translate.json#L38) ```"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](https://github.com/walterbender/turtleblocksjs/blob/master/plugins/translate.json), [weather.json](https://github.com/walterbender/turtleblocksjs/blob/master/plugins/weather.json), [maths.rtp](https://github.com/walterbender/turtleblocksjs/blob/master/plugins/maths.rtp)