Blockly Editor

The default Blockly editor comes packaged as WorkbenchViewController. It contains a workspace, a toolbox that holds blocks, and a trash folder.

The following guide explains the steps for creating and populating a Workbench View Controller.

Create the Workbench View Controller

This is how you would add an empty WorkbenchViewController to an existing UIViewController.

Swift

override func viewDidLoad() {
  super.viewDidLoad()

  // Create editor
  let workbenchViewController = WorkbenchViewController(style: .defaultStyle)

  // Add editor to this view controller
  addChildViewController(workbenchViewController)
  view.addSubview(workbenchViewController.view)
  workbenchViewController.view.frame = view.bounds
  workbenchViewController.view.autoresizingMask = [.flexibleWidth, .flexibleHeight]
  workbenchViewController.didMove(toParentViewController: self)
}

override var prefersStatusBarHidden : Bool {
  return true
}

Objective-C

- (void)viewDidLoad {
  [super viewDidLoad];

  // Create editor
  BKYWorkbenchViewController *workbenchViewController =
    [[BKYWorkbenchViewController alloc] initWithStyle:BKYWorkbenchViewControllerStyleDefaultStyle];

  // Add editor to this view controller
  [self addChildViewController:workbenchViewController];
  [self.view addSubview:workbenchViewController.view];
  workbenchViewController.view.frame = self.view.bounds;
  workbenchViewController.view.autoresizingMask =
    UIViewAutoresizingFlexibleWidth | UIViewAutoresizingFlexibleHeight;
  [workbenchViewController didMoveToParentViewController:self];
}

- (BOOL)prefersStatusBarHidden {
  return YES;
}

If you run this, you'll see the workbench containing an empty workspace, an empty toolbox along the leading edge of the screen, and a button to open the trash folder.

An empty Workbench

As you can see, this isn't very useful until there are blocks in the toolbox. Let's populate that next.

Add Blocks to the Toolbox

Adding blocks to the toolbox is a three-step process:

  1. Load JSON block definitions into the BlockFactory associated with the WorkbenchViewController.
  2. Construct a Toolbox using that block factory.
  3. Load the toolbox into the WorkbenchViewController.

1. Load JSON Block Definitions into the Block Factory

Blockly for iOS lets you create blocks with JSON data.

Let's create a simple sound block in JSON for your project:

  1. In Xcode, add a new file to your project by selecting File > New > File ...
  2. From the iOS tab, select Other > Empty, and hit Next.
  3. Save the file as blocks.json.
  4. Paste the following code in the file:

    [
      {
        "type": "play_sound",
        "message0": "play sound %1",
        "args0":
          [
            {
              "type": "field_dropdown",
              "name": "VALUE",
              "options":
                [
                  ["meow", "meow"],
                  ["woof", "woof"],
                  ["oink", "oink"],
                ]
            }
          ],
        "previousStatement": null,
        "nextStatement": null,
        "colour": "#5c6bc0",
      },
    ]
    
  5. Return to your viewDidLoad() method, and paste the following to load this JSON file into the workbench's block factory:

Swift

// Load the workbench's block factory with the "blocks.json" file
let blockFactory = workbenchViewController.blockFactory
do {
  try blockFactory.load(fromJSONPaths: ["blocks.json"])
} catch let error {
  print("Error loading 'blocks.json' into block factory: \(error)")
  return
}

Objective-C

// Load the workbench's block factory with the "blocks.json" file
NSError *blockFactoryError = nil;
BKYBlockFactory *blockFactory = workbenchViewController.blockFactory;
[blockFactory loadFromJSONPaths:@[@"blocks.json"] bundle:nil error:&blockFactoryError];

if (blockFactoryError) {
  NSLog(@"Error loading 'blocks.json' into block factory: %@", blockFactoryError);
  return;
}

Blockly is also bundled with JSON files defining many default blocks. For details on how to load these default blocks into a block factory, click here.

2. Construct a Toolbox

Next, create a toolbox with the block defined in the block factory:

Swift

// Create a new toolbox with a "Sound" category
let toolbox = Toolbox()
let soundCategory =
  toolbox.addCategory(name: "Sound", color: ColorPalette.indigo.tint400)

do {
  // Create a sound block and add it to the "Sound" category
  let soundBlock = try blockFactory.makeBlock(name: "play_sound")
  try soundCategory.addBlockTree(soundBlock)
} catch let error {
  print("Error adding 'play_sound' block to category: \(error)")
  return
}

Objective-C

// Create a new toolbox with a "Sound" category
BKYToolbox *toolbox = [[BKYToolbox alloc] init];
BKYToolboxCategory *soundCategory =
  [toolbox addCategoryWithName:@"Sound" color:BKYColorPalette.indigo.tint400];

// Create a sound block and add it to the "Sound" category
NSError* makeBlockError = nil;
BKYBlock *soundBlock =
  [blockFactory makeBlockWithName:@"play_sound" error:&makeBlockError];
if (makeBlockError) {
  NSLog(@"Error creating 'play_sound' block: %@", makeBlockError);
  return;
}

NSError* addBlockError = nil;
[soundCategory addBlockTree:soundBlock error:&addBlockError];
if (addBlockError) {
  NSLog(@"Error adding soundBlock to category: %@", addBlockError);
  return;
}

3. Load Toolbox into the Workbench

Finally, you can load your toolbox into the workbench:

Swift

do {
  try workbenchViewController.loadToolbox(toolbox)
} catch let error {
  print("Error loading toolbox into workbench: \(error)")
  return
}

Objective-C

NSError* loadToolboxError = nil;
[workbenchViewController loadToolbox:toolbox error:&loadToolboxError];

if (loadToolboxError) {
  NSLog(@"Error loading toolbox into workbench: %@", loadToolboxError);
  return;
}

Try Your App

If you've followed the steps correctly, your app should have a workbench with a single block in its toolbox:

Workbench with a one-block toolbox

Next Steps

From here, you can continue to customize different parts of your Blockly app: