Architect Sencha Docs

Save, Preview, and Build

Sencha Architect provides easy access so that you can save, preview, simulate, and build your application using buttons on the Architect toolbar.

Previewing displays your project in a browser.

Simulating lets you test your Sencha Touch iOS or Android applications within your local development environment without having to deploy your apps to an actual mobile device. For a list of which device features are enabled or disabled, refer to the iOS or Android documentation.

Note Simulating requires that the simulator or emulator is already running. Architect displays your project on a running simulator or emulator. Refer to the Android or iOS documentation for information on how to start the Android SDK emulator or the iOS Xcode simulator.

Building an application means packaging it for distribution, so that others can use it. This is necessary to distribute your apps within your company or via the Internet. For Sencha Touch applications, it is often desirable to publish your apps to the Google Play store or Apple Store.

Note: Save your project before previewing, building, or simulating your project.Until a project is saved, the preview and build buttons are grayed out.

Important

  • For information on how to build and simulate Touch projects for BlackBerry and Windows Phone, see Cordova and PhoneGap Apps in the Sencha Touch documentation set.

  • The Architect 3 build and simulate target features overwrite the packager.json file. Do not change this file when using Architect 3. If you are upgrading from a previous version of Architect or Touch where you used that file for build parameters, back up the file. If the packager.json file from a previous project gets overwritten, you can recover the file from the XDA file that's created when you first upgrade Architect to a new version. The XDA file is a compressed file that you can unzip and locate the files.

Introduction

The Sencha Architect toolbar provides buttons that let you save, preview, build, publish and simulate your app:

Ext JS Projects:



Touch Projects:

Architect for Touch apps may also include a Test (Appurify) button on the Toolbar if enabled:

The Appurify button enables access to the Appurify test environment. For more information, see Using Appurify.

Save Your Project

The Save drop-down menu in the toolbar provides different options for how you can save and license your project.

You can also save a project using the Cmd+S keystroke in Mac or the CTRL+S keystroke in Windows and Linux.

  • Save - Saves the project. Specify the Save Path, Application Name, and Project Name.

  • Save Project As - Renames a project before saving.

  • Save Entire Project - (Grayed out until after first save) Forces all files in the project to be re-saved and overwritten, regardless of whether they have been opened or not. A normal Save only writes files for items that have been opened or modified in Architect during the current session.

Note: Saving a project assumes you are creating a commercial application, which can be free or sold. To change the license for GPL (open source) or when you have purchased Sencha Complete or Sencha Touch Bundle, see the "Application License" section in the Installation and Setup Guide.

On the first save of a project, Architect displays the Save Project menu.

To save your project:

  1. Save Path - Click the Browse button to select the path where you want to save project files.

  2. App Name - Specifies the name of your application. This name appears in the code for your application in the first statement that defines the initial View.

  3. Project Name - Specifies the folder name and filename of your project.

Software Requirements

You need the following software to preview and build a project:

  • Ruby - Sencha Cmd (installed automatically by Architect) uses Ruby to compile CSS files into SCSS files.

  • Java - Sencha Cmd uses Java.

  • Apache Ant - Sencha Touch Android projects use Ant to create an Android Package file (APK), which is used to distribute an application.

To install this software:

  1. Windows and Linux: Click Edit > Architect Settings > Dependencies.

    Mac: Click Sencha Architect > Preferences > Dependencies.

    The window appears as:

  2. Click the links to install and verify each software package.
    When complete, the window appears as:

  3. Click Save.

Update the Path for Additional JavaScript Files

If you have additional JavaScript files that accompany your project, update the Architect app.classpath variable to specify the relative path to your code directory.

To update app.classpath:

  1. Navigate to the directory where your Architect project is. If you're not sure where this is, click Save > Save Project As for the Save Path.

  2. Change directory to the <Save_Path_Dir>.sencha > app directory.

  3. Make a new directory for your code, for example the app/thirdparty directory. Copy your JavaScript files to the new directory.

  4. Edit the sencha.cfg file and add a relative path to your new directory name to the app.classpath variable, for example:

    app.classpath=${app.dir}/app,${app.dir}/app.js,${app.dir}/thirdparty

Obtain a Web Server

A local web server is not required to develop with Sencha Architect, but is required if you want to preview your project on your local machine. If you don't already have a local web server, you can use a server such as XAMPP, or the Sencha Cmd web server, which is included in Sencha Cmd version 3.1.1 and later.

Notes:

  1. PHP does not work with the Sencha Cmd web server. Because Architect uses PHP in some examples, and because the Sencha Cmd web server is not capable of serving outside your computer, we recommend that you use a web server like XAMPP or the Apache web server.

  2. If you install Sencha Cmd for its web server, change directory to the directory where you to serve your application, and start the Sencha Cmd web server from the command line with the sencha web start command. The Sencha Cmd web server serves from the http://localhost:1841/ URL. You can also specify an alternate port with the -p port_number option. The web server runs exclusively in the command line window and continues until you press CTRL+C. You can also open a new command window and type the sencha web stop command.

Create a Certificate (Touch Projects Only)

Sencha Touch projects using iOS or Android require a certificate:

  1. iOS - Log into Apple's iOS Provisioning Portal and get development and distribution certificates, register your app and get an App ID, and create a provisioning profile. Access requires purchasing a developer's license. You can also download developer tools and the Xcode emulator.
    Before requesting a certificate at the Provisioning Portal, generate a Certificate Signing Request (CSR) using the openssl tool provided in Mac OS X, for example:

    > openssl req -new -key myprivatekey.key -out mycert.csr 
    Loading 'screen' into random state - done
    You are about to be asked to enter information that will be incorporated into your certificate request.
    What you are about to enter is called a Distinguished Name or a DN.
    There are quite a few fields, but you can leave some blank.
    For some fields there will be a default value,
    If you enter '.', the field will be left blank.
    ----- Country Name <2 letter code> [AU]: US State or Province Name <full name> [Some-State]: My State Locality Name <eg, city> []: My City Organizational Name <eg, company [Internet Widgits Pty Ltd]: MyCompany, Inc Organizational Unit Name <eg, section> []: Common Name <eg server FQDN or Your name> []: com.mydomain Email Address [] adeveloper@mydomain.com
    Please enter the following 'extra' attributes to be sent with your certificate request A challenge password []: An optional company name []: >

    After you create your CSR file, navigate to the Apple Development Portal, Certificates section. To create a Certificate, click the Add button and select the certificate type of iOS App Development. You are requested to upload your CSR file. After the upload completes, you can generate and then download your iOS Certificate.

    The openssl tool is also available for Windows. For more information and for additional steps required to complete an iOS app, see Packaging Native iOS Applications.

  2. Android - Use the keytool command from the Android SDK to create a certificate for your app:

    $ keytool -genkey -v -keystore C:\keys\mykeystore -alias myappkey -keyalg RSA -keysize 2048 -validity 10000
    Enter keystore password: <password>
    What is your first and last name?
      [Unknown]:  Polly Hedra
    What is the name of your organizational unit?
      [Unknown]:  App Development
    What is the name of your organization?
      [Unknown]:  MyCompany
    What is the name of your City or Locality?
      [Unknown]:  Silicon City
    What is the name of your State or Province?
      [Unknown]:  California
    What is the two-letter country code for this unit?
      [Unknown]:  US
    Is CN=MyPassword, OU=App Development, O=MyCompany, L=Silicon City, ST=California, C=US correct?
      [no]:  yes

    Generating 2,048 bit RSA key pair and self-signed certificate (SHA1withRSA) with a validity of 10,000 days for: CN=MyPassword, OU=App Development, O=MyCompany, L=Silicon City, ST=California, C=US Enter key password for <myappkey> (RETURN if same as keystore password): [Storing C:\keys\mykeystore] $

Create A Provisioning File (iOS Projects Only)

Links an Application ID with the iOS certificates and devices authorized to run the application. For more information, see Provisioning Profile Creation and Download.

Preview Your Project

Previewing means viewing your project in a web browser such as Chrome or Safari. Previewing requires that you have a web server operating at the time you click the Preview button.

To preview:

  1. Create a project directory where your web server can access your project. If you are using the Sencha Cmd web server, the directory can be anywhere on your computer. If you are using another web server, locate the project directory where your web server can access it.

  2. Save your project.

  3. Start your web server.

  4. Click the Preview button in the Architect Toolbar:

    When you click the Preview button for an application, the following window appears - after you click Preview, the browser window opens and displays your app. If you have a browser open, Preview adds a tab to the browser.

    1. URL Prefix - Type the URL for where your web server serves files on your computer. If you are using the Sencha Cmd web server and started the web server using the default port and in the directory where you serve files, specify the URL as:

      http://localhost:1841/<ArchitectProjectName>

      If you are using another web server, refer to its documentation for the URL to provide - in most cases, it's http://localhost/ and the directory where you serve your web applications.

    2. Cache bust on preview - Indicates whether or not to use cached information from the web server. By default, when this option is checked, information is not cached and new information is sent on each page request.

Example Ext JS output that shows the use of the default port number 1841, which the Sencha Cmd web server uses to serve web content:

For Touch, the example output appears as:

Build a Web App

Building a web app lets you create files for testing or distributing your project to display on a browser. You can change options after building from the Build web app > Build Settings menu.

Building a web app:

  • Optimizes your code to eliminate the parts of the Sencha class library your application doesn't use.

  • Uses Compass and Sass to compile your CSS and theme styles into an .scss file. The file name uses the App Name you specified when you saved your project.

Build web app options:

  • Environment - Choose Testing to make your the built file readable, which helps you debug your project, or Production, which optimizes and compresses your built project to remove JavaScript classes not used by your application. (Neither option affects your project's source code.)

  • Clean - Generates an optimized build in which intermediate and output files are deleted.

  • Publish Path - Specify the path where you want your published project to reside. Click Browse to choose a path.

  • Action menu:

    • Enable Debug - Generates a debug build and inserts [DBG] statements in the Architect Output log that list additional information about each build step.

Building a web app generates these files:

  • app.json
  • bootstrap.css
  • bootstrap.js
  • bootstrap.json
  • build.settings
  • sass/example/
  • sass/example/bootstrap.js
  • sass/example/example.css
  • theme/ext-theme-classic-<IDvalue>.css

The Output and Log windows provide information about the build.

Build an iOS App (Touch Projects Only)

To build an iOS app for a Sencha Touch project:

  1. Click Build iOS app, and click the App Summary tab:

    Access the Apple developers portal and obtain an Application Name, Application ID, and Bundle Seed ID. (The Bundle Seed ID is the prefix value found when viewing the Application ID in the developer portal-it's a 10-character string that's the same for all your applications in your account).

  2. If you are submitting your app to an online store for distribution, change Configuration to Release, otherwise, leave the Debug setting.

  3. Click the Provision Profile > Browse the path to your provisioning file.

  4. Click the Interface tab:

    Click the Device Type you're targeting or use the default setting for Universal. If your app only runs in portrait or landscape orientation, click the orientation you don't want. Click the Application Icons sizes for which you are supplying images. The icon button displays the Open File menu for you to navigate to where your image files are stored. Image files can be of the .png, .jpg or .gif types, and Architect copies the files to the resources/images directory of your project.

  5. Click the Certificates tab:

    Mac OS: Enter the Certificate Alias available from your access to the Apple developers portal.

    In Windows, this screen appears as:

    Windows: Enter the Certificate Password and Password Path. You assign the password when you create the certificate and the path is where the certificate is stored on your computer.

Build an Android App (Touch Projects Only)

To build an Android app for a Sencha Touch project:

  1. Click Build Android app, and click the App Summary tab:

    Specify the Application Name and Application ID.

  2. If you are submitting your app to an online store for distribution, change Configuration to Release, otherwise, leave the Debug setting.

  3. Set the Android API Level to the minimum level your app works with. You must ensure that the correct API is installed using the Android SDK Manager. For example, you must have previously installed Android 4.4 to use API level 19.

  4. Set the Version String and Version Code for your app.

  5. Click Browse to locate where you installed your Android SDK. The Android SDK resides where you unzipped the Android SDK download. The sdk folder inside of the unzipped zip file contains sub-folders such as tools, build-tools, sources, etc.

  6. Set the permissions relative to the device features your app needs access to. You can find a list of Android permissions in the Android Manifest.permission document.

  7. Click the Interface tab:

    If your app only runs in portrait or landscape orientation, click the orientation you don't want. Click the Application Icons sizes for which you are supplying images. The icon button displays the Open File menu for you to navigate to where your image files are stored. Image files can be of the .png, .jpg or .gif types, and Architect copies the files to the resources/images directory of your project.

  8. Click the Certificates tab:

    Specify your certificate password and path to your certificate. For more information on creating a certificate, see the previous section on the Android SDK keytool command.

Installing an App on an Android Device

  1. Start the Android SDK Manager. In Windows, navigate to the Android, SDK directory, right-click SDK Manager.exe, and click Run as Administrator. In Mac or Linux, change directory to where you unzipped the Android SDK download and in the tools directory, enter the ./android command.

  2. Check Android SDK Platform-tools and uncheck other options. Click the Install Package button. In the next screen, click Android SDK Platform-tools, revision n.n.n and click Accept.

  3. For Windows, install the Google USB Driver from the Android SDK Manager to help install your app on your mobile device. Locate the usb_driver_r04-windows.zip file on the web for the device on which you are installing your app. This file contains Android drivers and contains a device ID for the mobile device. In Windows 8, disable driver signature enforcement to install Android drivers for Windows. Search the web for information on this step.

  4. You can make use of Android much easier if you add the paths to the tools and platform-tools directories to your PATH environment variable.

  5. To get the Android ADB command to communicate with your device, connect the device to your computer and type these commands at the command line:

    android update adb
    adb kill-server
    adb start-server
    adb devices  
    

Notes

  • The android command is in the tools directory and the adb command is in the platform-tools directory (which you need to install separately using the Android SDK Platform-tools package in the Android SDK Manager).

  • Mac and Linux users should use ./android update adb. First change directory to where you unzipped the Android software distribution, and change directory to the tools directory.

  • When the adb devices command succeeds, it lists the serial number of the mobile device. For example:

    $ adb devices
    List of devices attached 
    42424242    device
    

Simulate an iOS App

Before simulating an app, launch the Xcode Simulator without running an app. When you click Run in Architect, Architect opens your app in the Xcode Simulator.

To simulate an iOS app:

  1. Click Simulate on iOS, and click the App Summary tab:

    Specify the Application Name and Application ID that you registered in the Apple developers portal. If needed, change the Version String.

  2. Click the Interface tab:

    If needed, change the Device Type, or unclick an unsupported orientation, or unclick an icon size.

  3. Click Run to display your app on the Xcode Simulator.

Simulate an Android App

Before emulating an Android app, create an Android virtual device (AVD) and start the Android SDK Emulator. When you click Run in Architect, Architect opens your app in the Android SDK Emulator.

To simulate an Android app:

  1. Click Simulate on Android, and click the App Summary tab:

    Specify the application name and ID. Change the Android API Level to the maximum Android level that your app supports. To use the emulator, you need to have previously installed all Android levels using the Android SDK Manager that your app supports. For more information, see API Levels.

    If needed, set the version string and code. Click Browse to set the path to where you installed the Android SDK. Remove any Permissions your app doesn't need.

  2. Click the Interface tab:

    If needed, unclick an unsupported orientation or icon size.

  3. Click Run to display your app on the Android Emulator.

App Refresh

The App Refresh option in the Build menu regenerates project files.

This feature runs in your project directory and updates these files with changes in your project:

  • app.js
  • cmd-packages.js
  • bootstrap.js
  • bootstrap.json

Publish Your Project

Publishing optimizes your project files for distributing your project. After you publish your project, you can compress the directory and distribute the content as needed.

Note: Publishing does not make a project viewable from a browser. Click the Preview button to make your project visible from a browser:

To publish your project:

  1. Create a publish directory where you want your project to be stored.

  2. Save your project.

  3. Click the Publish button:

  4. Click Browse to navigate to your publish directory, and click Continue:

Using Appurify (Sencha Touch Only)

Architect 3.0 and later provides integrated testing for Sencha Touch 2.n applications using the Appurify service, which enables you to test your Sencha Touch application on a real device located in the cloud.

To enable Appurify access:

  1. Windows & Linux: Click Edit > Architect Settings
    Mac OS: Click Sencha Architect > Preferences

  2. Click the Interface tab and click Enable for the Testing with Appurify

  3. Click Save

After you save your project, the Appurify button appears in the toolbar as:

Note: You must set up your own Appurify account from within Architect to use Appurify. When you first click the "Appurify" button, use the Register link to sign up with Appurify:

If you try to register directly on the Appurify web site, you will be put on a wait list. Details of the Appurify pricing and licensing are available on the Appurify website.

To test your app using Appurify:

  1. Create and save your Sencha Touch application.

  2. Click the Appurify button on the Toolbar; this button does not appear until you have enabled Appurify in the Settings, and saved your project.

  3. A pop-up window appears for you to specify how to test your application:

    1. Choose Via uploading project files to Appurify to zip the local project files and upload them to Appurify.

    2. If you have a staging site that contains the project to be tested and is public, choose Via URL and supply the complete URL to your project.

    3. Choose Automated Testing to go to a special Appurify page that runs a script to test your application. Appurify provides this page to support Architect 3.0 and later.

    4. Choose the Tunneling option if your application needs to access an internal service such as a data service. This is discussed below.

    5. Click the Launch button to launch an external browser window running the Appurify test facilities for your Architect project. All interactions on that site are supported by Appurify rather than Sencha.

What is Tunneling?

The Tunneling option allows you to test your application against an internal service such as a data server. A service that is inside your corporate firewall may not be accessible to the Appurify testing site. When you select the Tunneling option, Appurify installs a script on your local machine that opens an SSL tunnel that allows the Appurify device to access your internal service. This tunnel is heavily encrypted and secure.

When you first select the Tunneling option, you get a screen to install this script and any software required to run the script on your operating system. After all the software is installed, the Yes and No buttons are enabled; click "Yes" and the tunneling script starts in the background.

Note that, whenever the tunneling script is running, you have a button to stop the tunneling script. You should always close this script when you are done with your testing to avoid possible security leaks.