Discuss Scratch

NickyNouse
Scratcher
1000+ posts

A Guide to Scratch-Blocks Themes

Hey all! Over the last several months I've contributed some code to Scratch-Blocks so that the blocks in the Scratch 3.0 editor will be natively theme-able with CSS. I've developed a handful of themes (at least one of which should still work), but I haven't released any documentation on how the new code works. I'm fixing that now: here it is, your guide to styling Scratch-Blocks!

Blocks
First things first, every block in Scratch-Blocks consists of a <g> element, which is a “group”–a container for other svg elements. This group will contain elements for the following:
  • The block's background (a <path> element)
  • One or more text labels (<text> element[s])
  • Its inputs (which I'll sometimes refer to as arguments). Inputs are usually handled as blocks themselves so they'll have their own <g> elements, I'll talk more about them later.
  • Reporter blocks that have been dropped into the block's inputs, they'll have their own child <g> elements.
There are 2 SVG data-attributes that help you to identify a block, and both are on its <g> element:

data-category: This data-attribute contains the name of the category that the block falls into. Some of these are subject to change (for example, they're still figuring out how to categorize list blocks), and I'm not sure whether internationalization will affect these. But for now, these are the available categories:
  • motion
  • looks
  • sounds
  • pen
  • data
  • events
  • control
  • sensing
  • operators
  • more

data-shapes: This data-attribute is a space-separated list of shape keywords that apply to the block. Those could be any from the following:
  • reporter
  • boolean
  • round
  • c-block
  • c-1 (the number is the number of c-inputs, so if/else would be c-2)
  • hat
  • stack (only if it's not a c-block or hat)
  • end
For a more in-depth look at what might cause a block to have what keyword, see the code here.

There are a few more things you'll want to know. It's possible that a block will contain multiple <path> elements, so the one that represents the background will have the class “blocklyBlockBackground”.

Arguments
Arguments are any inputs in any blocks. Scratch-Blocks handles them very similarly to blocks, and they too usually have a <g> element around them, with one major exception: boolean inputs. A boolean input is simply a <path> element that is added directly into its parent block's <g> element, and its data-attributes will be applied to that <path> instead.

There are a couple data-attributes that apply to arguments:

data-argument type: This is the type of data that the input will accept. It's a space-separated list, and it's designed in a hierarchy–since the number input type is based on the text input type, it lists both “text” and “number” in this attribute.
  • angle
  • checkbox
  • colour
  • date
  • dropdown
  • iconmenu
  • number
  • text
  • variable
  • boolean
data-shapes: Once again, this data-attribute is a space-separated list of shape keywords that apply to the block. Those could be any from the following:
  • argument
  • boolean
  • round

Dropdowns
Dropdown menus are rendered outside the SVG in the HTML part of the page. They have a data-category attribute on their div, which has the class “blocklyDropDownDiv”. This doesn't apply to the tooltip that appears when you click a reporter.
Dropdowns have arrows that should automatically inherit the background color of their parent dropdown.

Other
  • The workspace's background has the class “blocklyMainBackground”.
  • Blocks that are being dragged are in a separate SVG with the class “blocklyDragSurface”.
  • When you're dragging around a stack block, a “ghost” block appears that indicates where the dragged block would go. This “ghost” block is called an insertion-marker, and its <g> will have the class “blocklyInsertionMarker”.
  • Similarly, when dragging around a reporter, blocks and arguments will have a glow around them. This is called a replacement glow, and those blocks and arguments will have the class “blocklyReplaceable” on their <g> elements (or for boolean inputs, their <path> elements).

Selecting these elements in CSS
When selecting an element that should be inside a block's <g>, be careful to use the direct-child selector “>”. Often, other blocks will be nested inside a bigger block, so you'll want to make sure that you're only affecting the elements that are directly inside the block in question. For example, if I want to safely color my motion blocks red, I could do the following:
g[data-category="motion"] > path.blocklyBlockBackground {
fill: red;
}

A little-known selector you may end up using is the attribute selector that searches a space-separated list, which uses the syntax [attribute~=“value”]. For example, to color the backgrounds of all text arguments, you could do this:
g[data-argument-type~="text"] > .blocklyBlockBackground {
fill: green;
}

For examples of how to use these selectors, see my example theme here.

Last edited by NickyNouse (Jan. 26, 2017 06:35:35)

pollypuffin
Scratcher
38 posts

A Guide to Scratch-Blocks Themes

NickyNouse wrote:

Hey all! Over the last several months I've contributed some code to Scratch-Blocks so that the blocks in the Scratch 3.0 editor will be natively theme-able with CSS. I've developed a handful of themes (at least one of which should still work), but I haven't released any documentation on how the new code works. I'm fixing that now: here it is, your guide to styling Scratch-Blocks!

Blocks
First things first, every block in Scratch-Blocks consists of a <g> element, which is a “group”–a container for other svg elements. This group will contain elements for the following:
  • The block's background (a <path> element)
  • One or more text labels (<text> element[s])
  • Its inputs (which I'll sometimes refer to as arguments). Inputs are usually handled as blocks themselves so they'll have their own <g> elements, I'll talk more about them later.
  • Reporter blocks that have been dropped into the block's inputs, they'll have their own child <g> elements.
There are 2 SVG data-attributes that help you to identify a block, and both are on its <g> element:

data-category: This data-attribute contains the name of the category that the block falls into. Some of these are subject to change (for example, they're still figuring out how to categorize list blocks), and I'm not sure whether internationalization will affect these. But for now, these are the available categories:
  • motion
  • looks
  • sounds
  • pen
  • data
  • events
  • control
  • sensing
  • operators
  • more

data-shapes: This data-attribute is a space-separated list of shape keywords that apply to the block. Those could be any from the following:
  • reporter
  • boolean
  • round
  • c-block
  • c-1 (the number is the number of c-inputs, so if/else would be c-2)
  • hat
  • stack (only if it's not a c-block or hat)
  • end
For a more in-depth look at what might cause a block to have what keyword, see the code here.

There are a few more things you'll want to know. It's possible that a block will contain multiple <path> elements, so the one that represents the background will have the class “blocklyBlockBackground”.

Arguments
Arguments are any inputs in any blocks. Scratch-Blocks handles them very similarly to blocks, and they too usually have a <g> element around them, with one major exception: boolean inputs. A boolean input is simply a <path> element that is added directly into its parent block's <g> element, and its data-attributes will be applied to that <path> instead.

There are a couple data-attributes that apply to arguments:

data-argument type: This is the type of data that the input will accept. It's a space-separated list, and it's designed in a hierarchy–since the number input type is based on the text input type, it lists both “text” and “number” in this attribute.
  • angle
  • checkbox
  • colour
  • date
  • dropdown
  • iconmenu
  • number
  • text
  • variable
  • boolean
data-shapes: Once again, this data-attribute is a space-separated list of shape keywords that apply to the block. Those could be any from the following:
  • argument
  • boolean
  • round

Dropdowns
Dropdown menus are rendered outside the SVG in the HTML part of the page. They have a data-category attribute on their div, which has the class “blocklyDropDownDiv”. This doesn't apply to the tooltip that appears when you click a reporter.
Dropdowns have arrows that should automatically inherit the background color of their parent dropdown.

Other
  • The workspace's background has the class “blocklyMainBackground”.
  • Blocks that are being dragged are in a separate SVG with the class “blocklyDragSurface”.
  • When you're dragging around a stack block, a “ghost” block appears that indicates where the dragged block would go. This “ghost” block is called an insertion-marker, and its <g> will have the class “blocklyInsertionMarker”.
  • Similarly, when dragging around a reporter, blocks and arguments will have a glow around them. This is called a replacement glow, and those blocks and arguments will have the class “blocklyReplaceable” on their <g> elements (or for boolean inputs, their <path> elements).

Selecting these elements in CSS
When selecting an element that should be inside a block's <g>, be careful to use the direct-child selector “>”. Often, other blocks will be nested inside a bigger block, so you'll want to make sure that you're only affecting the elements that are directly inside the block in question. For example, if I want to safely color my motion blocks red, I could do the following:
g[data-category="motion"] > path.blocklyBlockBackground {
fill: red;
}

A little-known selector you may end up using is the attribute selector that searches a space-separated list, which uses the syntax [attribute~=“value”]. For example, to color the backgrounds of all text arguments, you could do this:
g[data-argument-type~="text"] > .blocklyBlockBackground {
fill: green;
}

For examples of how to use these selectors, see my example theme here.

Thanks, that helped!

Powered by DjangoBB

Standard | Mobile