(Inline Scratchblocks)
(wooo rewrite)
Line 4: Line 4:
 
Feel free to fix any articles that don't conform to this guide.
 
Feel free to fix any articles that don't conform to this guide.
  
This guide is intended for wiki editors, and includes guidelines on ''style'' as well as a little extra syntax. It thus serves a different purpose to [[Block Plugin/Syntax]], which is a guide to the syntax intended for both wiki editors and forum users.
+
This guide is intended for wiki editors, and includes guidelines on ''style'' as well as a little extra syntax. It thus serves a different purpose to [[Block Plugin/Syntax]], which is intended for forum users and wiki editors alike.
 +
 
 +
= Style Guide =
  
 
== Whitespace ==
 
== Whitespace ==
Line 52: Line 54:
  
 
* Always put whitespace around inserts and embedded blocks. This is easier to read.
 
* Always put whitespace around inserts and embedded blocks. This is easier to read.
 +
  
 
{| border=1
 
{| border=1
Line 79: Line 82:
 
</dl>
 
</dl>
  
== Laziness ==
+
== Be Explicit ==
The block plugin will insert certain things for you automatically, in case you forget. Don't rely on this; always include properly formatted scripts in wiki articles. If Javascript is disabled then the source code will be displayed directly to the user, so we want the article source to be readable.
+
The block plugin will close brackets and c-blocks for you, in case you forget. Don't rely on this; always include properly formatted scripts in wiki articles. If Javascript is disabled then the source code will be displayed directly to the user, so the scratchblocks code in articles needs to be readable.
  
 
* Always include "<code>end</code>" after a C block.
 
* Always include "<code>end</code>" after a C block.
Line 109: Line 112:
 
if <<(x position) < [3]> and <(var) = [4]>>
 
if <<(x position) < [3]> and <(var) = [4]>>
 
</pre>
 
</pre>
 +
</dl>
 +
 +
== Misc ==
 +
: '''Warning:''' The wiki doesn't support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014
 +
 +
* Replace "<code>(user id)</code>" with "<code>(user id :: sensing)</code>". The user id block is deprecated, and may be removed from scratchblocks in the future.
 +
<dl>
 +
<dd>'''No:'''
 +
<dd><pre>set [foo v] to (user id)</pre>
 +
<dd>'''Yes:'''
 +
<dd><pre>set [foo v] to (user id :: sensing)</pre>
 
</dl>
 
</dl>
  
Line 115: Line 129:
  
 
{| border=1
 
{| border=1
! Scratch 1.4 Block
+
! Scratch 1.4
! Replacement
+
! Scratch 2.0 replacement
 
|-
 
|-
 
| <scratchblocks>switch to costume [costume1 v] </scratchblocks>
 
| <scratchblocks>switch to costume [costume1 v] </scratchblocks>
Line 151: Line 165:
 
|}
 
|}
  
=== The <sb>(user id)</sb> Block ===
+
= Wiki-only features =
<!-- (Using blocks in headings is evil, not recommended, should be added to the style guide as a "no", and should almost certainly be outlawed. (Does look cool, though.)) -->
+
There are some extra "hidden" features intended for use on the wiki only.
  
<blockquote>"Now we have the category hack, I'm going to remove the <code>(user id)</code> block from the scratchblocks plugin's database, <s>just for fun</s> in light of my nefarious master plan to switch to generating the blocks list directly from the <s>decompiled SWF sources</s> Scratch 2.0 source code.
+
=== Ellipsis ===
 
+
* The grey <sb>. . .</sb> ellipsis block represents a gap in a script. Use it!
{{-}}blob8108
 
</blockquote>
 
  
Summary: Replace "<code>(user id)</code>" with "<code>(user id :: sensing)</code>" where appropriate.
+
: Don't write the word "script", "scripts", any other obsolete block, or a comment saying "script goes here".
  
{{note| I think the wiki plugin still hasn't been updated yet, so double-colon hacks may not work yet: <sb>(user id :: sensing)</sb>}}
 
 
== New features ==
 
<!-- At some point, you should probably rename this "Secret Wiki-only" features. Or some such. (Not that the ellipsis block is technically wiki-only. Nor the category hack. But I digress.) -->
 
 
=== Ellipsis ===
 
You can now use the grey <sb>. . .</sb> ellipsis block to represent gaps in scripts.
 
 
* If you're putting a deliberate gap in a script--use it! Don't write the word "script", "scripts", any other obsolete block, or a comment saying "script goes here".
 
 
<dl>
 
<dl>
 
<dd>'''No:'''
 
<dd>'''No:'''
Line 197: Line 200:
 
</dl>
 
</dl>
  
* Always write <code>. . .</code>, with spaces between the dots. This makes the block easier to read. <!-- I wanted to enforce this in the plugin, but it was too difficult and I was feeling impatient. :P --->
+
* Always put spaces between the dots: <code>. . .</code>. This makes the block easier to read.
 +
<!-- I wanted to enforce this in the plugin, but it was too difficult. --->
  
 
=== Inline Scratchblocks ===
 
=== Inline Scratchblocks ===
Line 204: Line 208:
 
Producing:
 
Producing:
 
:I'm rather fond of the <sb>stamp</sb> block in Scratch 2.0.
 
:I'm rather fond of the <sb>stamp</sb> block in Scratch 2.0.
 +
Notes:
 +
* You can only use a single block in the inline tag, not a whole script.
 +
 +
* Use inline scratchblocks to represent variable names, eg <sb>(score)</sb>:
 +
<dl>
 +
<dd>'''No:'''
 +
<dd><pre>Use the "score" variable to keep track of...</pre>
 +
<dd>'''Yes:'''
 +
<dd><pre>Use the <sb>(score)</sb> variable to keep track of...</pre>
 +
</dl>
 +
 +
* For block links, use inline scratchblocks instead of images:
 +
<dl>
 +
<dd>'''Yes:'''
 +
<dd><pre>[[Stamp (block)|<sb>stamp</sb>]]</pre>
 +
<dd>[[Stamp (block)|<sb>stamp</sb>]]
 +
</dl>
 +
 +
* Don't use inline scratchblocks in headings.
 +
<dl>
 +
<dd>'''No:'''
 +
<dd><pre>== The (username) block ==</pre>
 +
<dd>'''Yes:'''
 +
<dd><pre>== The username block ==</pre>
 +
</dl>
  
Some notes:
+
=== Colouring blocks ===
* You can only use a single block in the inline tag, not a whole script. This is by design.
+
: '''Warning:''' The wiki doesn't support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014
* Use the inline tag where appropriate.
+
 
* Use it to represent variable names: <sb>(score)</sb>
+
You can set the colour of blocks using secret hacks. This allows you to colour blocks that would normally appear obsolete, for example the "create clone" block from the Scratch 2.0 prototype.
* To make a link containing a block image, instead of using an image, use the following markup:
+
 
:<pre>[[Stamp (block)|<sb>stamp</sb>]]</pre>
+
:<scratchblocks>create clone</scratchblocks>
Producing:
+
 
:[[Stamp (block)|<sb>stamp</sb>]]
+
By using a special hack, you can get the correct colour:
  
=== Set Block Colour ===
+
:<scratchblocks>create clone // category=control</scratchblocks>
You can now set the colour of a block using a secret comment hack: <code>// category=[...]</code>. For example, the "create clone" block from the prototype was renamed "create clone of", so it normally appears obsolete:
 
  
<pre>create clone</pre>
+
Notes:
<scratchblocks>create clone</scratchblocks>
 
  
But by putting a special comment, you can get the correct colour:
+
* For colouring blocks, do '''not''' use the deprecated ''comment syntax'', which may be removed in the future. Use the more flexible ''double-colon syntax'' instead, which also supports reporters:
 +
<dl>
 +
<dd>'''No:'''
 +
<dd><pre>create clone // category=control</pre>
 +
<dd>'''Yes:'''
 +
<dd><pre>create clone :: control</pre>
 +
<dd><pre>say (ultrasonic sensor :: extension)</pre>
 +
</dl>
  
<pre>create clone // category=control</pre>
 
<scratchblocks>create clone // category=control</scratchblocks>
 
  
'''Warning:''' The syntax for this will change in the future, so use it sparingly.
 
  
== External Links ==
+
= External Links =
* [http://github.com/blob8108/scratchblocks2/blob/master/src/blocks.txt Complete List of Blocks]
+
* [http://github.com/blob8108/scratchblocks2/blob/master/tests/all-blocks.txt Complete List of Blocks]
 
* [http://blob8108.github.io/scratchblocks2/ Test page]
 
* [http://blob8108.github.io/scratchblocks2/ Test page]

Revision as of 13:02, 20 September 2014

Shortcut:
S:SB2STYLE

In order to keep the Scratch Wiki looking neat, please follow the following style guide when writing <scratchblocks> on the wiki.

Feel free to fix any articles that don't conform to this guide.

This guide is intended for wiki editors, and includes guidelines on style as well as a little extra syntax. It thus serves a different purpose to Block Plugin/Syntax, which is intended for forum users and wiki editors alike.

Style Guide

Whitespace

  • Always put a line break before and after the opening and closing <scratchblocks> tags.
No:
I like this script: <scratchblocks>when flag clicked
say [Hello!]</scratchblocks> Pretty, isn't it?

Yes:

I like this script:

<scratchblocks>
when gf clicked
say [Hello!]
</scratchblocks>

  • However, if you're writing a script with a single block, only use one line:
Yes:
<scratchblocks>when gf clicked</scratchblocks>
  • Use indentation. Always indent by 4 spaces. (This is for consistency as much as for any other reason.)
No:
repeat (10)
if <touching [mouse-pointer v]?>
move (10) steps
end
stamp
end

Yes:

repeat (10)
    if <touching [mouse-pointer v]?>
        move (10) steps
    end
    stamp
end
  • Always put whitespace around inserts and embedded blocks. This is easier to read.


No Yes
if<mouse down?> then
if <mouse down?> then
<(variable)=[3]>
<(variable) = [3]>
(join (((3)*(3))+((3)/((3)-(3))))[j])
(join (((3) * (3)) + ((3) / ((3) - (3)))) [j])
set size to (100)%
set size to (100) %
Note Note: This last example is currently broken due to a mysterious wiki-only bug.
  • Always put spaces around the comment symbol "//".
No:
stamp//Draws a picture!

Yes:

stamp // Draws a picture!

Be Explicit

The block plugin will close brackets and c-blocks for you, in case you forget. Don't rely on this; always include properly formatted scripts in wiki articles. If Javascript is disabled then the source code will be displayed directly to the user, so the scratchblocks code in articles needs to be readable.

  • Always include "end" after a C block.
No:
repeat (10)
    move (10) steps
    stamp

Yes:

repeat (10)
    move (10) steps
    stamp
end
  • Always close brackets.
No:
if <<(x position) < [3]> and <(var) = [4

Yes:

if <<(x position) < [3]> and <(var) = [4]>>

Misc

Warning: The wiki doesn't support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014
  • Replace "(user id)" with "(user id :: sensing)". The user id block is deprecated, and may be removed from scratchblocks in the future.
No:
set [foo v] to (user id)

Yes:

set [foo v] to (user id :: sensing)

Scratch 2.0 Blocks

Make sure you use the 2.0 versions of blocks (unless it's an article specifically about Scratch 1.4). This includes:

Scratch 1.4 Scratch 2.0 replacement
switch to costume [costume1 v] 
switch costume to [costume1 v]
switch to background [background1 v] 
switch backdrop to [background1 v]
next background
next backdrop
(background #)
(backdrop #)
if <>
if <> then
forever if <>
forever
    if <>
stop script
stop [this script v]
stop all
stop [all v]
when Sprite1 clicked
when this sprite clicked
<loud?>
<(loudness) > [30]>

Wiki-only features

There are some extra "hidden" features intended for use on the wiki only.

Ellipsis

  • The grey . . . ellipsis block represents a gap in a script. Use it!
Don't write the word "script", "scripts", any other obsolete block, or a comment saying "script goes here".
No:
forever
    if <>
        script
    end
end

No:

forever
    if <>
        // script goes here
    end
end

Yes:

forever
    if <>
        . . .
    end
end
  • Always put spaces between the dots: . . .. This makes the block easier to read.

Inline Scratchblocks

You can place scratchblocks inside a sentence using the <sb> tag, like this:

I'm rather fond of the <sb>stamp</sb> block in Scratch 2.0.

Producing:

I'm rather fond of the stamp block in Scratch 2.0.

Notes:

  • You can only use a single block in the inline tag, not a whole script.
  • Use inline scratchblocks to represent variable names, eg (score):
No:
Use the "score" variable to keep track of...

Yes:

Use the <sb>(score)</sb> variable to keep track of...
  • For block links, use inline scratchblocks instead of images:
Yes:
[[Stamp (block)|<sb>stamp</sb>]]

stamp

  • Don't use inline scratchblocks in headings.
No:
== The (username) block ==

Yes:

== The username block ==

Colouring blocks

Warning: The wiki doesn't support double-colon syntax yet. Go bug scmb1 to update the plugin! :) --blob8108 12:04 20 September 2014

You can set the colour of blocks using secret hacks. This allows you to colour blocks that would normally appear obsolete, for example the "create clone" block from the Scratch 2.0 prototype.

create clone

By using a special hack, you can get the correct colour:

create clone // category=control

Notes:

  • For colouring blocks, do not use the deprecated comment syntax, which may be removed in the future. Use the more flexible double-colon syntax instead, which also supports reporters:
No:
create clone // category=control

Yes:

create clone :: control
say (ultrasonic sensor :: extension)


External Links