Get Started

This guide is aimed at Android developers who wish to create their own applications that incorporate Blockly as a code editor. It is assumed that one is generally familiar with Blockly's usage, and one has a basic understanding of Java and app development using Android Studio.

The major steps are:

  1. Download and build the library
  2. Create the project and configure the activity
  3. Configure the project's dependencies
  4. Extend AbstractBlocklyActivity and implement the necessary methods.

The result will be your own app that looks like the Blockly Simple demo, with a toolbox full of blocks and a large workspace.

Get the Code

First, download the source code from GitHub. If you know how to use Git or Subversion, we highly recommend syncing from our repository so that your code stays up to date.

Download ZIP File Download TAR Ball View On GitHub

Once you have the code, open it in Android Studio by importing the project's root directory. You should should see four modules, the first of which is blocklydemo. Build and run blocklydemo to verify your installation.

Once built, you will find the following library files:

  • blockly-android/blocklylib-core/build/outputs/aar/blocklylib-core-release.aar
  • blockly-android/blocklylib-core/build/outputs/aar/blocklylib-core-debug.aar
  • blockly-android/blocklylib-vertical/build/outputs/aar/blocklylib-vertical-release.aar
  • blockly-android/blocklylib-vertical/build/outputs/aar/blocklylib-vertical-debug.aar

The core files include the model and controller classes, and base classes for the views. The vertical files include the vertically stacking blocks view, defined by the VerticalBlockViewFactory and associated view classes. You will include at least one of each in your project.

Create the project and activity

If you don't already have an application project, go ahead and create one using the "Empty Activity" template. Blockly requires a minSdkVersion of 16 or higher.

If you are working with an existing application, add an "Empty Activity" to the project.

Screenshots of creating a new project in Android Studio.

In either case, you do not need to generate a layout file with the activity. Your blockly activity will initially use layouts provided with the Blockly library.

In the new <activity> of your AndroidManifest.xml file, set the windowSoftInputMode as follows:

<application ...
    android:windowSoftInputMode="stateHidden|adjustPan"
    />

The windowSoftInputMode ensures the keyboard starts in the closed position, even if there are keyboard input fields. It will also make sure the workspace pans to show such fields when the keyboard (or other IME) opens.

In the applications AppTheme, found in res/values/styles.xml, set the parent theme to BlocklyVerticalTheme.

<style name="AppTheme" parent="BlocklyVerticalTheme">
    <!-- Customize your theme here. -->
    ...
</style>

This parent style configures several defaults for the blocks and fields. You can find more details in the style's definition.

Configure project dependencies

In your application project, open File | Project Structure.... Make sure the app module includes library dependencies for...

  • com.android.support:support-v4
  • com.android.support:appcompat-v7
  • com.android.support:recyclerview-v7

Add a module to the project using the '+' button in the Project Structure dialog. Choose the "Import .JAR/.AAR Package" module template, and select blocklylib-debug.aar or blocklylib-release.aar from the blockly-android project directory. Then, in the app module dependencies, add the new module as a module dependency.

Screenshots of adding a module in Android Studio.

Importing these .aar files will copy them into the project directory at the following location(s):

  • MyBlocklyApp/blocklylib-core-debug/blocklylib-core-debug.aar
  • MyBlocklyApp/blocklylib-core-release/blocklylib-core-release.aar
  • MyBlocklyApp/blocklylib-vertical-debug/blocklylib-vertical-debug.aar
  • MyBlocklyApp/blocklylib-vertical-release/blocklylib-vertical-release.aar

To update the Blockly library in your project, just replace the copies at these locations with newer versions.

You can add both the debug and release version .aar files, if you want full debug info in only your app's debug build. If you do, make sure the scopes in the app module dependencies are "Debug compile" and "Release compile", respectively.

Screenshots of the Project Structure dialog in Android Studio, with all module dependencies configured.

Implement the activity base class

The easiest way to develop an Android Blockly activity is to extend AbstractBlocklyActivity, and we highly recommend using it for your first Blockly application. The class has several abstract methods you will need to override, detailed below. The method implementations below mirror those in SimpleActivity, which you can use as a reference.

getToolboxContentsXmlPath()

getToolboxContentsXmlPath() returns the assets/ path to XML that defines the toolbox contents.

@Override
protected String getToolboxContentsXmlPath() {
    return "default/toolbox.xml";
}

getBlockDefinitionsJsonPaths()

getBlockDefinitionsJsonPaths() returns the paths in the assets/ directory to the block defintion .json files. The below implementation imports the default blocks provided by the Blockly library.

@Override
protected List<String> getBlockDefinitionsJsonPaths() {
    return Arrays.asList(
        "default/list_blocks.json",
        "default/logic_blocks.json",
        "default/loop_blocks.json",
        "default/math_blocks.json",
        "default/text_blocks.json",
        "default/variable_blocks.json",
        "default/colour_blocks.json"
    );
}

getGeneratorsJsPaths()

getGeneratorsJsPaths() returns the paths in the assets/ directory to the generator .js files that define the block implementations. Current implementations include all the JavaScript implementations for Blockly's default blocks.

private static final List<String> JAVASCRIPT_GENERATORS = Arrays.asList(
    // Custom block generators go here. Default blocks are already included.
);

@Override
protected List<String> getGeneratorsJsPaths() {
    return JAVASCRIPT_GENERATORS;
}

getCodeGenerationCallback()

getCodeGenerationCallback() returns the callback used to return the generated code back to the app. This is called after the user hits the run/play button in the action bar.

CodeGenerationRequest.CodeGeneratorCallback mCodeGeneratorCallback =
        new LoggingCodeGeneratorCallback(this, "LoggingTag");

@Override
protected CodeGenerationRequest.CodeGeneratorCallback getCodeGenerationCallback() {
    // Uses the same callback for every generation call.
    return mCodeGeneratorCallback;
}

onInitBlankWorkspace()

While not an abstract method, onInitBlankWorkspace() is currently required to define the available variables if your app includes default/variable_blocks.json. Variable support is currently in development.

@Override
protected void onInitBlankWorkspace() {
    // Initialize available variable names.
    getController().addVariable("item");
}

Next steps

At this point, the app should compile and run similar to SimpleActivity. From here, development can progress in several different directions. You can...