Step-By-Step with the EachScape SDK
Creating your first block
The latest version of this document always lives here.
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
In the Cloud Studio, click on “Augment”
In the Context Menu, click on “SDK Docs” to download relevant SDK Documentation
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
In the EachScape Builder, click on “Develop” Tab
Click on the “New App” icon in the Context Menu (upper left-hand corner)
In the New App panel, use these values
→ “Visual Editor v5.0”
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.
Builder → Augment → “New Block”
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.
For Android development, use whatever class name you like because you will specify the package name below.
Description: “This block is used for Searching”
Block Type: <do not change this value>
Package Name: <Only for Android> (eg: com.example.search)
Version Number: 1.01 <Must start with 1.01>
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
Raw app level event descriptor: <blank>
Raw view level event descriptor: <blank>
Raw Descriptor <without the numbers on the left-hand side>
Text Font: font_spec
[Sections Label: text](Sections)
Raw event descriptor: <This is where you describe events. For now, you can just input ‘tap’
Default settings: <blank>
Item level alias: <blank>
Item level help: <copy/paste the below without formatting>
Display Text: This is text to display
Text Font: This is the font selection for the text
Sections: Number of sections
Sections Label: Use to show info in sections
Allowed usage: <Eligible for middle, not scrollable>
Default height: 100
Click on the “Visibility/Access” tab
Platforms: <Select relevant platforms, for this example, try Android 4.4 or iOS 7 and 8 Pixel Perfect>
- 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
Float over the Components section of the Navigation Frame (toward the bottom). It will pop up. Click on “MyBlocks” tab
Click on “new custom block”
Block Name: “MyblocknameInstance”
Block Type: Click on your new new block definition that you defined
In the upper part of the Navigation Frame, click on the “First” View
Go back to the “MyBlocks” tab
Click and drag your block’s icon directly onto the mobile phone preview
Your new block should appear in the Navigation Frame Hierarchy
Right-click on your new block and pull up the “Edit” frame.
Fill out your block’s properties as desired
--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
Click “Generate” in the Context Menu at the top
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” )
Click on “Generate my app”
- 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
Click on “Build History”. Once your app is built, the new version will show in the Navigation Frame on the left.
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.
Click on the build you want (iOS developers should click on an iOS build, Android developers should click on an Android build)
- 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.
Use Finder to extract the EachScape input file “SDKTest <version number> input.zip”
Rename the resulting folder (eg: “SDKTest 1.01 input”) to “app”
Replace the app folder found at SDK/ESApp/Resources/app with the resulting folder from the prior step
Open SDK.xcodeproj, located in the SDK folder, with Xcode
Clean the project (⇧⌘K)
If present, delete the existing ‘EachScape’ app in the simulator.
To open the iOS Simulator, in the menu bar for Xcode, click Xcode → Open Developer Tool → iOS Simulator
Select an iPhone Simulator destination from the scheme selection jump bar in the top left of Xcode
Compile and run(⌘R)
- 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
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
Go to Xcode → Project Navigator. So, if your company prefix is ‘XY”, you should now see these code files:
Follow the reference documentation and ‘Developer Guide to Building EachScape Blocks’ to write the code for your block
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
Android SDK Buildtools (The latest version should work)
Choose Android 4.0 (API 14)
Add the Android Support Libraries if you wish
→ Install Packages
Import the EachScape SDK Library project into Eclipse
Copy the androidsupportv4.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
androidsupportv7.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
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
- 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
You’ll need an input file. Included in the SDK is the input file helloWorldInput.zip.
Unzip the helloWorldInput.zip and the content should have 4 folders:
Copy res and src into the EachScape SDK Library
Copy assets into the EachScape Block Sample app (replacing what’s currently there)
Compile the project
Install on your phone
Run the app
- 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
For reference, use ‘Developer Guide to Building EachScape Blocks’ to write the code for your block
- 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:
The Four source files for your new block
Your four modified source files
Any additional Libraries you have used
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
NOTE: If you are creating an Android 2.3 block, use ‘android:targetSdkVerion=”15”’ Otherwise, use 18
NOTE: Any external jars go here
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
10 Upload your code to EachScape
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
Now upload the ZIP file to EachScape: EachScape → Augment → Select your zip file → Context Menu/“Edit Code”
Select the appropriate “Choose File” for your implementation
- 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
- 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)