Developer Guide

Project structure

/src Source folder

intern

The sourcefolder has an intern part, where the code for internal stuff like the renderpage and the playground (exact copy from google) is. This code won't be executed when exposed as library. So it is never used in productional environment.

library

In the library folder we have the code which is used in productional environment. The class CatBlocks from library/js/lib.js gets exposed as window.CatBlocks when the webpacked library is loaded.

common

The common folder contains the parser which converts the XML content from the android XStream library to an JavaScript usable JSON format.

what does the parser, what the library

where is the project included (link to share)

what to do before PR

how to debug on vscode

Add new bricks

When bricks are added to Catroid, they have to be added to Catblocks as well. There is a GitHub Action that automatically checks for new bricks and posts updates to our Slack channel.

In Catroid bricks can be found in the following path: Catroid/catroid/src/main/java/org/catrobat/catroid/content/bricks/ The important information for Catblocks is defined in the layout-xml file of the brick. The name of the layout can be found in the getViewResource() method. (Example: R.layout.brick_wait for the WaitBrick) Layouts can be found in the following path: Catroid/catroid/src/main/res/layout/ .

In the layout-xml file we can find multiple elements. Relevant elements are those inside the BrickLayout, for example text views or spinners.

Snippet of the WaitUntilBrick layout:

<TextView
    android:id="@+id/wait_until_label"
    style="@style/BrickText.Multiple"
    android:text="@string/brick_wait_until" />

<TextView
    android:id="@+id/brick_wait_until_edit_text"
    style="@style/BrickEditText"
    app:layout_inputType="number"
    app:layout_textField="true" />

<TextView
    android:id="@+id/wait_until_label_second_part"
    style="@style/BrickText.Multiple"
    android:paddingStart="5dip"
    android:text="@string/brick_wait_until_second_part" />

We need to distinguish the these text views:

• The first and third contains static text, that is defined in the strings.xml file. The name of the referenced string can be found in the android:text argument.
• The second is a input field. The name of the input field can be found in the android:id argument.

To define the text shown in Catblocks, we need to add the mapping in the strings_to_json_mapping.json file.

"CONTROL_WAITUNTILTRUE": "${brick_wait_until} %1%2 ${brick_wait_until_second_part}"

CONTROL_WAITUNTILTRUE defines the name of the string to reference in in Catblocks. ${brick_wait_until} %1%2 ${brick_wait_until_second_part} defines the content of the string, where the same strings are referenced as in Catroid. We can see that the input field has two placeholders: %1%2. There need to be two placeholders, because after each input there is a small info icon that is shown when the input text is too long.

Now the string used by the new brick is defined and we need to define the brick. The bricks in Catblocks are defined in the following path: Catblocks/src/library/js/blocks/categories/ Since the WaitUntilBrick is a control brick, it needs to be defined in the control.js file.

WaitUntilBrick: {
  message0: '%{BKY_CONTROL_WAITUNTILTRUE}',
  args0: [
    {
      type: 'field_input',
      name: 'brick_wait_until_edit_text',
      text: 'unset'
    },
    {
      type: 'field_image',
      src: `${document.location.pathname}media/info_icon.svg`,
      height: 24,
      width: 24,
      alt: '(i)',
      flip_rtl: true,
      name: 'brick_wait_until_edit_text_INFO'
    }
  ]
}

There are a few things where we need to pay attention:

• The name of the brick must be equal to the class name in Catroid (case sensive)
• The message name defined in the strings_to_json_mapping.json file needs the prefix BKY_. This prefix tells Blockly that the string needs to be replaced.
• The number of arguments must be equal to the placeholders in the defined string.
• The name of the field should be equal to the ID of the field in Catroid (android:id).
• At the moment, all input fields are of type field_input.
• The name of the info field must be equal to the referenced field name with the postfix _INFO.

To view the brick, we can use the playground (yarn playground:dev). To test it with real parameters we should use a Catroid program that uses the new brick.

Update Languages

Catblocks uses the same language files as Catroid. The same GitHub action that checks for bricks updates, also checks for language updates.

The language files used by Catroid can be found in the following path: Catroid/catroid/src/main/res/. In most of the many value-folders is a strings.xml file. These strings.xml files need to be copied to Catblocks to the following path: Catblocks/i18n/catroid_strings/.

There is one language that needs special care: The strings for values-en in Catblocks are defined in the values folder in Catroid.