Get Started

This guide shows you how to get started with Blockly for iOS. It assumes the reader has a basic understanding of iOS development.

Blockly for iOS was written in Swift, but it can easily be used in both Swift and Objective-C projects.

It supports devices running iOS 8.0 or above.

Before You Begin

Install Blockly

Use CocoaPods
CocoaPods is a dependency manager for Swift and Objective-C projects.

Install CocoaPods

Open a Terminal window and run the following command:
sudo gem install -n /usr/local/bin cocoapods

For details, see the CocoaPods Getting Started guide.

Set up CocoaPods dependencies

To configure Blockly for your project, set up its dependencies:

  1. If you don't have an Xcode project yet, create one now.
  2. Open a Terminal window and navigate to the directory containing your .xcodeproj file.
    cd "path-to-your-project"
  3. If you don't have a Podfile yet, create one by running this in the Terminal:
    pod init
  4. Open the Podfile and add the following:
    source 'https://github.com/CocoaPods/Specs.git'
    
    target 'YourProjectAppTarget' do
      use_frameworks!
    
      pod 'Blockly'
    end
  5. Save the Podfile.
  6. Run these commands in the Terminal:
    pod install
    pod update
    This creates an .xcworkspace file for your app. Use this file for all future development of your app. (Make sure to close Xcode first before opening the .xcworkspace file.)

That's it! Your project is now set up to use Blockly.

Use Carthage
Carthage is a decentralized dependency manager that lets you retain full control over your project structure and setup.

Install Carthage

Download and run the latest release of Carthage.pkg.

Set up Carthage dependencies

To configure Blockly for your project, set up its dependencies:

  1. If you don't have an Xcode project yet, create one now.
  2. Open a Terminal window and navigate to the directory containing your .xcodeproj file.
    cd "path-to-your-project"
  3. Create a Cartfile in this directory, and add the following:
    github "google/blockly-ios"
  4. Save the Cartfile.
  5. Run this command:
    carthage update --platform iOS
    This fetches all Blockly dependencies into a Carthage/Checkouts folder and builds each one into a Carthage/Build folder.
  6. Close all open instances of Xcode and then open your .xcodeproj file.
  7. Add the frameworks built by Carthage to your project:
    1. In your project settings, select your main application target and open its General settings tab.

    2. Scroll down to the Embedded Binaries section and press the + button.
    3. In the window that pops up, press the Add Other... button.
    4. Navigate to path-to-your-project/Carthage/Build/iOS.
    5. Select Blockly.framework and AEXML.framework. Press Open.
    6. Another window will appear. Press Finish.
  8. Open the Build Phases tab for your main application target, press the + button and choose New Run Script Phase. Create a Run Script in which you specify your shell (eg. bin/sh), add the following contents to the script area below the shell:
    /usr/local/bin/carthage copy-frameworks
    and add these framework paths under Input Files:
    $(SRCROOT)/Carthage/Build/iOS/AEXML.framework
    $(SRCROOT)/Carthage/Build/iOS/Blockly.framework
  9. Open the Build Settings tab for your main application target, and set the following value:
    • Always Embed Swift Standard Libraries to Yes

That's it! Your project is now set up to use Blockly.

Install manually

While we strongly recommend that you use CocoaPods or Carthage to keep your project dependencies up-to-date, this guide covers how to manually configure Blockly for your project.

  1. Download and unpack the source code from GitHub: Download ZIP File Download TAR Ball View On GitHub
  2. Close all open instances of Xcode.
  3. Open your Xcode project file, or create one if you haven't already.
  4. Select File > Add Files to [Project Name]... and add two projects from the Blockly source code into your project:
    • Blockly.xcodeproj
    • third_party/Carthage/Checkouts/AEXML/AEXML.xcodeproj
  5. Add those projects as dependencies for your project:
    1. In your project settings, select your main application target and open its General settings tab.

    2. Scroll down to the Embedded Binaries section and press the + button.
    3. In the window that pops up, select the following frameworks:
      • Blockly.xcodeproj > Products > Blockly.framework(iOS)
      • AEXML.xcodeproj > Products > AEXML.framework(iOS)
    4. Press the Add button.
  6. Open the Build Settings tab for your main application target, and set the following value:
    • Always Embed Swift Standard Libraries to Yes

  7. Clean your project by selecting Product > Clean
  8. .

That's it! Your project is now set up to use Blockly.

Use Blockly

Import Blockly

To import Blockly, add the following:

Swift

import Blockly

Objective-C

// For CocoaPods users, use the following:
#import "Blockly/Blockly.h"
#import "Blockly-Swift.h"

// For non-CocoaPods users, use the following:
#import <Blockly/Blockly.h>
#import <Blockly/Blockly-Swift.h>

Note: Before your first compile, you may see an error in Xcode that Blockly-Swift.h could not be found. To fix it, just compile your project once to generate the file.

Add the Blockly Editor

To create the default Blockly editor in a new UIViewController subclass, add the following:

Swift

override func viewDidLoad() {
  super.viewDidLoad()

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

  // Load its block factory with default blocks
  let blockFactory = workbenchViewController.blockFactory
  blockFactory.load(fromDefaultFiles: .allDefault)

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

  // Add some blocks to the "Blocks" category
  let blockNames = ["controls_if", "controls_repeat_ext", "math_number", "math_arithmetic"]
  for blockName in blockNames {
    do {
      let block = try blockFactory.makeBlock(name: blockName)
      try blocksCategory.addBlockTree(block)
    } catch let error {
      print("Error adding '\(blockName)' block to category: \(error)")
    }
  }

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

  // 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];

  // Load its block factory with default blocks
  BKYBlockFactory *blockFactory = workbenchViewController.blockFactory;
  [blockFactory loadFromDefaultFiles:BKYBlockJSONFileAllDefault];

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

  // Add some blocks to the "Blocks" category
  NSArray *blockNames =
    @[@"controls_if", @"controls_repeat_ext", @"math_number", @"math_arithmetic"];

  for (NSString *blockName in blockNames) {
    NSError* error = nil;

    // Create block
    BKYBlock *block = [blockFactory makeBlockWithName:blockName error:&error];
    if (error) {
      NSLog(@"Error creating '%@' block: %@", blockName, error);
      continue;
    }

    // Add block to category
    [blockCategory addBlockTree:block error:&error];
    if (error) {
      NSLog(@"Error adding '%@' block to category: %@", blockName, error);
      continue;
    }
  }

  // Load the toolbox into the workbench
  NSError *error = nil;
  [workbenchViewController loadToolbox:toolbox error:&error];
  if (error) {
    NSLog(@"Error loading toolbox into workbench: %@", error);
    return;
  }

  // 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;
}

Running this code example produces the following:

Example of the default Blockly editor

Run Sample Code

The source code includes several sample projects that showcase some of the things that you can do with Blockly for iOS:

  • Use Blockly in both Swift and Objective-C code
  • Import blocks from JSON
  • Import a toolbox from XML
  • Generate and execute JavaScript code

The samples are located in the Samples directory of the Blockly for iOS GitHub project.

For CocoaPods users, you can explore the samples by running:

$ pod try Blockly

Next Steps

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

  • Toolbox: Explains how to configure the editor's toolbox.
  • Customize Blockly Editor: Explores different ways to customize and use the Blockly Editor.
  • Block Factory: Covers how to add default blocks and custom blocks to your project.
  • Code Generators: Explains how to generate executable code from the blocks in a user's workspace.

For complete API documentation, visit the iOS reference section.

Blockly Developer Tools

We recommend that you use Blockly Developer Tools when creating a Blockly app. It is a set of developer tools that can speed up many parts of the Blockly development process.