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. Create the project and configure the activity
  2. Configure the project's dependencies
  3. 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.

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 18 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

Open your project's build.gradle file and make sure it includes the JCenter repository. Also make sure you include the Google maven repository for Android's support and compatibility classes. Project files created by recent versions of Android Studio should already have this, as shown here:

allprojects {
    repositories {
        jcenter()
        maven {
            url 'https://maven.google.com'
        }
    }
}

Next, open the build.gradle file for your application, usually found in the app/ directory. Inside the dependencies block, include the following lines:

compile 'com.android.support:appcompat-v7:26.0.1'
compile 'com.android.support:recyclerview-v7:26.0.1'
compile 'com.android.support:support-v4:26.0.1'
compile 'com.google.blockly.android:blocklylib-vertical:0.9-beta.20171003'

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 definition .json files. The below implementation imports the default blocks provided by the Blockly library.

@Override
protected List<String> getBlockDefinitionsJsonPaths() {
    List<String> assetPaths = new ArrayList<>(DefaultBlocks.getAllBlockDefinitions());
    // Append your own block definitions here.
    return assetPaths;
}

The DefaultBlocks class contains helper functions for Blockly's predefined blocks. getAllBlockDefinitions() returns an array of all paths to predefined blocks. It is as easy place to start, though one will eventually want to select the specific blocks relevant to the app, and also creation blocks specific to the runtime environment.

See Add Custom Blocks for details on creating new blocks.

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() {
    return mCodeGeneratorCallback;
}

In this implementation, the app uses the same generator callback for every generation call. This is common, but not required.

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...