Step-By-Step with the EachScape SDK

Creating your first block

 

Update

The latest version of this document always lives here.

 

Introduction

Welcome to the EachScape SDK!  In EachScape, a “Block” is the basic component from which all app functionality is built.  Creating custom blocks via this SDK allows developers to extend block functionality, and thus EachScape app functionality, in any way.

Note: This is a How-To guide.  For more information on the architecture of EachScape, blocks, and how blocks fit into the EachScape environment, please view the developer’s guide.

To create your first custom block, follow each step in the sections below:

1 Download the SDK

2 Create a new app in EachScape

3 Create a new custom block definition

4 Implement your new block in your App

5 Build your app

6 Download your EachScape app

7 iOS Development using Xcode

Xcode: Import your EachScape app into your development environment

Xcode: Load your new custom block

8 Android Development using Eclipse

Open up the Android SDK Manager and in the download/install screen

Import the EachScape SDK Library project into Eclipse

Import the EachScape Block Sample App into Eclipse

Import the EachScape Input File into your sample project

Perform your own development using the EachScape SDK

9 Package your code for EachScape

iOS

Android

10 Upload your code to EachScape

FAQ

 

1 Download the SDK

  1. In the Cloud Studio, click on “Augment”

  2. In the Context Menu, click on “SDK Docs” to download relevant SDK Documentation

  3. In the Context Menu, click on the SDK relevant to you (Android SDK or iOS SDK) to download

2 Create a new app in EachScape

  1. In the EachScape Builder, click on “Develop” Tab

  2. Click on the “New App” icon in the Context Menu (upper left-hand corner)

  3. In the New App panel, use these values

    1. Name: SDKTest

    2. → “Visual Editor v5.0”

    3. → “Canvas”

    4. → “Create”

  4. You’ll get a confirmation panel that your app has been created.  Click “Edit”

3 Create a new custom block definition

This process will define a custom block, but not actually create that block.  It’s like creating a blueprint for a building, and then creating a block that uses this blueprint will follow in the next steps.

 

  1. Builder → Augment → “New Block”

  2. Basic Tab

    1. Name field: 

      1. On iOS, use this convention: “<CompanyInitials><Name>Block” (eg: for Search block created by Google, this could be “GSearchBlock”).  This is to conform with the typical naming convention since Objective-C doesn’t have namespaces like Java does.

      2. For Android development, use whatever class name you like because you will specify the package name below.

    2. Description: “This block is used for Searching”

    3. Block Type: <do not change this value>

    4. Package Name: <Only for Android> (eg: com.example.search)

    5. Version Number: 1.01 <Must start with 1.01>

  3. Definition (Use the documentation in the ‘Descriptor How-To” tab to determine how to define your block.  If you are implementing our example, you can simply copy/paste the below

    1. Raw app level event descriptor: <blank>

    2. Raw view level event descriptor: <blank>

    3. Raw Descriptor <without the numbers on the left-hand side>

      1. Display Text:text

      2. Text Font: font_spec

      3. Sections: 0-4

      4. [Sections Label: text](Sections)

    4. Raw event descriptor: <This is where you describe events.  For now, you can just input ‘tap’

      1. tap

    5. Default settings: <blank>

    6. Item level alias: <blank>

    7. Item level help: <copy/paste the below without formatting>

      1. Display Text: This is text to display

      2. Text Font: This is the font selection for the text

      3. Sections: Number of sections

      4. Sections Label: Use to show info in sections

    8. Allowed usage: <Eligible for middle, not scrollable>

    9. Default height: 100

  4. Click on the “Visibility/Access” tab

    1. Deprecated: No

    2. Platforms: <Select relevant platforms, for this example, try Android 4.4 or iOS 7 and 8 Pixel Perfect>

  5. Click “Create”

  6. Your new custom block will be shown in the Builder Navigation frame and also in the center view.

4 Implement your new block in your App

  1. Float over the Components section of the Navigation Frame (toward the bottom).  It will pop up.  Click on “MyBlocks” tab

  2. Click on “new custom block”

    1. Block Name: “MyblocknameInstance”

    2. Block Type: Click on your new new block definition that you defined 

    3. Click “Create”

  3. In the upper part of the Navigation Frame, click on the “First” View

  4. Go back to the “MyBlocks” tab

  5. Click and drag your block’s icon directly onto the mobile phone preview

  6. Your new block should appear in the Navigation Frame Hierarchy

  7. Right-click on your new block and pull up the “Edit” frame.

    1. Fill out your block’s properties as desired

  8. --Add as many other views and blocks to your app as needed --

    NOTE: you’ll want to include an empty block with a distinct background color to easily verify your app is loading correctly.

5 Build your app

  1. Click “Generate” in the Context Menu at the top

  2. Select all the versions you wish to build (always select HTML5)
    NOTE: If you want to generate an iOS build, you must FIRST take care of your provisioning.  For help on Provisioning, click HERE. (http://support.eachscape.com / “Creating a certificate for iOS apps” )

  3. Click on “Generate my app”

  4. You’ll be kicked back to the Cloud Studio screen.  Click the “Build History” to watch the build in progress.

6 Download your EachScape app

  1. Click on “Build History”.  Once your app is built, the new version will show in the Navigation Frame on the left.

  2. The Navigation Frame now contains a history of all your builds.  iOS, Android, and HTML5 builds are indicated in the list via a small icon to the right of the build number.

  3. Click on the build you want (iOS developers should click on an iOS build, Android developers should click on an Android build)

  4. Click on the “download input” button (In the build description area near the top of the Build Details).  This will download the EachScape input file to your machine, which will be imported into your Dev environment in the next step

7 iOS Development using Xcode

Xcode: Import your EachScape app into your development environment

 

Note: this document is aimed at developers and so we expect you to already be setup as an iOS developer and that your XCode is already set up the way you need.  If you need more information on setting up XCode, please consult the Apple Developer Network documentation.

 

  1. Use Finder to extract the EachScape input file  “SDKTest <version number> input.zip”

  2. Rename the resulting folder (eg: “SDKTest 1.01 input”) to “app”

  3. Replace the app folder found at SDK/ESApp/Resources/app with the resulting folder from the prior step

  4. Open SDK.xcodeproj, located in the SDK folder, with Xcode

  5. Clean the project (⇧⌘K)

  6. If present, delete the existing ‘EachScape’ app in the simulator.

    1. To open the iOS Simulator, in the menu bar for Xcode, click Xcode → Open Developer Tool → iOS Simulator

  7. Select an iPhone Simulator destination from the scheme selection jump bar in the top left of Xcode

  8. Compile and run(⌘R)

  9. This last step verifies that the code you downloaded from EachScape is running properly in your environment.  Now, we will proceed to implement your custom block in the next step

Xcode: Load your new custom block

  1. Run `./prepare-sdk`. This renames the example files to match the block names you’ve specified.  eg:  Xcode://MyApp/Classes/Block/ExampleBlock.h is renamed to <YourPrefix><YourBlockName>.h
     

  2. Go to Xcode → Project Navigator.  So, if your company prefix is ‘XY”, you should now see these code files:

    1. Xcode://MyApp/Classes/Block/XYTestBlock.h

    2. Xcode://MyApp/Classes/Block/XYTestBlock.m

    3. Xcode://MyApp/Classes/Block/XYTestBlockController.h

    4. Xcode://MyApp/Classes/Block/XYTestBlockController.m
       

  3. Follow the reference documentation and ‘Developer Guide to Building EachScape Blocks’ to write the code for your block

  4. Debug until you are satisfied with the behavior in your test app
     

NOTE: If you use external libraries in your implementation, create the directory Xcode://MyApp/Classes/Block/Library and store any binaries and headers in that directory

 

8 Android Development using Eclipse

Open up the Android SDK Manager and in the download/install screen

  1. Android SDK Build­tools (The latest version should work)

  2. Choose Android 4.0 (API 14)

  3. Add the Android Support Libraries if you wish

  4. → Install Packages

 

Import the EachScape SDK Library project into Eclipse

  1. Copy the android­support­v4.jar into the EachScape Block SDK Library project’s libs folder inside Eclipse. It should have already been downloaded to sdk/extras/android/support/v4 during the prior step

  2. android­support­v7.jar will be supported in the near future. If you need to include this version, you can add it to the libs folder of the EachScape Block Sample App imported in the next step

 

Import the EachScape Block Sample App into Eclipse

  1. Make sure the Android SDK version is API Level 14. If you don’t have it, click on the Android SDK icon in Eclipse and Check the box that says Android 4.0 API 14. The EachScape API currently supports a max of 14

  2. In the Eclipse → Problems tab, you will find an error.  Replace the existing red ‘X’ library with the EachScape SDK Library project

Import the EachScape Input File into your sample project

  1. You’ll need an input file.  Included in the SDK is the input file helloWorldInput.zip. 

  2. Unzip the helloWorldInput.zip and the content should have 4 folders: 

    1. assets

    2. build­-resources

    3. res

    4. src

  3. Copy res and src into the EachScape SDK Library

  4. Copy assets into the EachScape Block Sample app (replacing what’s currently there)

  5. Compile the project

  6. Install on your phone

  7. Run the app

    1. You should see four sample output strings on the display, one of them “Hello World”, and three labels

Perform your own development using the EachScape SDK

  1. For reference, use ‘Developer Guide to Building EachScape Blocks’ to write the code for your block

  2. Debug until you are satisfied with the behavior in your test app

9 Package your code for EachScape

After you have completed your block development, you will be ready to upload your code back to EachScape.  


Here’s the inventory of what you need to provide to EachScape:

 

iOS

The Four source files for your new block

  1. Your four modified source files

    1. Xcode://MyApp/Classes/Block/XYTestBlock.h

    2. Xcode://MyApp/Classes/Block/XYTestBlock.m

    3. Xcode://MyApp/Classes/Block/XYTestBlockController.h

    4. Xcode://MyApp/Classes/Block/XYTestBlockController.m

  2. Any additional Libraries you have used

    1. MyApp/Classes/Block/Library/LibName_1.h

    2. MyApp/Classes/Block/Library/LibName_1.a

    3. MyApp/Classes/Block/Library/LibName_2.h

    4. MyApp/Classes/Block/Library/LibName_2.a

Android                    

  1. The zip file should include all directories of your code that you need for the custom block. The items at the root level can only be one or more of the following folders src, libs, res, assets, or LibraryProjects only. If you have external jars you need for your block, include them in the libs folder.  It will look like the following example
     

  2. AndroidSDKBlockUpload.zip

    1. AndroidManifest.xml

      1. NOTE: If you are creating an Android 2.3 block, use ‘android:targetSdkVerion=”15”’ Otherwise, use 18

    2. LibraryProjects

    3. assets

    4. libs

      1. NOTE: Any external jars go here

      2. NOTE: If you are using a 3rd party Android Library project, you can place the whole project here but you *MUST* remove the ‘gen/bin’ folder from each library

    5. res

    6. src

10 Upload your code to EachScape

  1. Create a zipfile with the contents of the “Block” directory named ‘BlockTypeName.zip’.  

    NOTE: The correct filename for your ZIP file is the value you gave the MasterBlock’s name back in step 3.2.a.  This is the “Type” of the block.  You can also verify this value by going to → Augment → and verifying the name your block shows
     

  2. Now upload the ZIP file to EachScape: EachScape → Augment → Select your zip file → Context Menu/“Edit Code”


    1. Select the appropriate “Choose File” for your implementation
       

  4. Once your upload is complete, re-build your test app (EachScape → Your App → Generate → <appropriate build options> → OK → Build History → Select Latest Build, to test your new functionality

FAQ

  1. If you find that the Controller isn’t being run, make sure that @”template” has been replaced in your code with the block reference (defined in the Edit Block properties in the Augment tab)