Docs Help

Terms, Icons, and Labels

Many classes have shortcut names used when creating (instantiating) a class with a configuration object. The shortcut name is referred to as an alias (or xtype if the class extends Ext.Component). The alias/xtype is listed next to the class name of applicable classes for quick reference.

Access Levels

Framework classes or their members may be specified as private or protected. Else, the class / member is public. Public, protected, and private are access descriptors used to convey how and when the class or class member should be used.

Member Types

Member Syntax

Below is an example class member that we can disect to show the syntax of a class member (the lookupComponent method as viewed from the Ext.button.Button class in this case).

lookupComponent ( item ) : Ext.Component
protected

Called when a raw config object is added to this container either during initialization of the items config, or when new items are added), or {@link #insert inserted.

This method converts the passed object into an instanced child component.

This may be overridden in subclasses when special processing needs to be applied to child creation.

Parameters

item :  Object

The config object being added.

Returns
Ext.Component

The component to be added.

Let's look at each part of the member row:

Member Flags

The API documentation uses a number of flags to further commnicate the class member's function and intent. The label may be represented by a text label, an abbreviation, or an icon.

Class Icons

- Indicates a framework class

- A singleton framework class. *See the singleton flag for more information

- A component-type framework class (any class within the Ext JS framework that extends Ext.Component)

- Indicates that the class, member, or guide is new in the currently viewed version

Member Icons

- Indicates a class member of type config

- Indicates a class member of type property

- Indicates a class member of type method

- Indicates a class member of type event

- Indicates a class member of type theme variable

- Indicates a class member of type theme mixin

- Indicates that the class, member, or guide is new in the currently viewed version

Class Member Quick-Nav Menu

Just below the class name on an API doc page is a row of buttons corresponding to the types of members owned by the current class. Each button shows a count of members by type (this count is updated as filters are applied). Clicking the button will navigate you to that member section. Hovering over the member-type button will reveal a popup menu of all members of that type for quick navigation.

Getter and Setter Methods

Getting and setter methods that correlate to a class config option will show up in the methods section as well as in the configs section of both the API doc and the member-type menus just beneath the config they work with. The getter and setter method documentation will be found in the config row for easy reference.

History Bar

Your page history is kept in localstorage and displayed (using the available real estate) just below the top title bar. By default, the only search results shown are the pages matching the product / version you're currently viewing. You can expand what is displayed by clicking on the button on the right-hand side of the history bar and choosing the "All" radio option. This will show all recent pages in the history bar for all products / versions.

Within the history config menu you will also see a listing of your recent page visits. The results are filtered by the "Current Product / Version" and "All" radio options. Clicking on the button will clear the history bar as well as the history kept in local storage.

If "All" is selected in the history config menu the checkbox option for "Show product details in the history bar" will be enabled. When checked, the product/version for each historic page will show alongside the page name in the history bar. Hovering the cursor over the page names in the history bar will also show the product/version as a tooltip.

Search and Filters

Both API docs and guides can be searched for using the search field at the top of the page.

On API doc pages there is also a filter input field that filters the member rows using the filter string. In addition to filtering by string you can filter the class members by access level, inheritance, and read only. This is done using the checkboxes at the top of the page.

The checkbox at the bottom of the API class navigation tree filters the class list to include or exclude private classes.

Clicking on an empty search field will show your last 10 searches for quick navigation.

API Doc Class Metadata

Each API doc page (with the exception of Javascript primitives pages) has a menu view of metadata relating to that class. This metadata view will have one or more of the following:

Expanding and Collapsing Examples and Class Members

Runnable examples (Fiddles) are expanded on a page by default. You can collapse and expand example code blocks individually using the arrow on the top-left of the code block. You can also toggle the collapse state of all examples using the toggle button on the top-right of the page. The toggle-all state will be remembered between page loads.

Class members are collapsed on a page by default. You can expand and collapse members using the arrow icon on the left of the member row or globally using the expand / collapse all toggle button top-right.

Desktop -vs- Mobile View

Viewing the docs on narrower screens or browsers will result in a view optimized for a smaller form factor. The primary differences between the desktop and "mobile" view are:

Viewing the Class Source

The class source can be viewed by clicking on the class name at the top of an API doc page. The source for class members can be viewed by clicking on the "view source" link on the right-hand side of the member row.

Sencha Touch 2.4


top

Packaging Native iOS Applications

This guide walks through the steps required to create and install a native application on a device running iOS for development and testing. This guide does not discuss how to submit your finished app to the iTunes store. For more information, see the Apple Development Portal.

These steps are required within the Apple Developer Portal to run an application on an iOS device:

  1. Create, download, and convert an iOS Certificate.
  2. Create an Application ID.
  3. Register a device.
  4. Create and download a Provisioning Profile.

After you complete the Apple Developer Portal steps, then:

  1. Configure the application package Configuration.
  2. Generate your app.
  3. Copy and run the packaged application.

iOS Certificate Creation, Download and Conversion

Important: Because an iOS Certificate contains signed information about an author (person and company) who creates the application, perform this step normally once. You can use one certificate for multiple applications.

All iOS native applications need to be bundled with iOS Certificates that contain information about the author of the application. These certificates are issued and digitally signed by Apple Inc. through the Apple Developer Portal.

To generate an iOS Certificate:

  1. Generate a Certificate Signing Request (CSR).
  2. Navigate to the Apple Development Portal, Certificates section, and Click Add.
  3. Upload the CSR to the Development Portal and generate an iOS Certificate
  4. Download the iOS Certificate.
  5. Convert to iOS Certificate to P12 format.

When developing under Windows, the steps are the same, but the methods and commands differ slightly.

Mac OS Environment

All of the tools required for your iOS Certificate are included with Mac OS, so creating your certificate is relatively simple and facilated using the Keychain Access utility. This is located in your Applications/Utility folder.

Generate Certificate Signing Request

Launch the KeyChain Access utility. From the application menu, choose:

Keychain access > Certificate Assistant > Request a Certificate from a Certificate Authority.

In the Certificate Information window, enter or select the following information:

  • User Email Address field: Your email address
  • Common Name field: Your name
  • Request is group: Select the Save to disk option
  • Click Continue

The Certificate Assistant saves a Certificate Signing Request (CSR) file to your desktop. The public and private key pair generates when you create the Certificate Signing Request (CSR) if you use the Key Chain Assistant to create the CSR.

Upload CSR and Generate iOS Certificate

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

Convert Certificate to P12 Format

After you download your certificate (the default name is ios_development.cer), convert the certificate to P12 format before you can bundle it into your application. For information on what a P12 certificate is, see the Wikipedia PKCS #12 article.

To convert the certificate to P12 format:

  1. In the Mac Keychain Access utility, click File > Importand navigate to the location of the downloaded ios_development.cer file.
  2. After importing the certificate file, click Keys Category.
  3. Click the private key associated with your Apple iOS Certificate. The private key has the following name pattern: iPhone Developer:<First Name> <Last Name> public key reference.
  4. Click File > Export Items and save the key in P12 format.
  5. Specify this file in the Sencha packager config file in the certificatePath variable.

Windows Environment

OpenSSL is required for you to generate a self-signed certificate for your application. OpenSSL for Windows is available at Shining Light Productions where you can download and install:

  • Visual C++ 2008 Redistributables (required for OpenSSL)
  • Open SSL Light (32 or 64 bit version)

By default, OpenSSL installs in the directory \OpenSSL-WinXX where XX is 32 or 64 depending on the version you installed. Set environment variables first for OpenSSL to run properly before you proceed to generate your private key required for creating your digital certificate.

Create Private Key

The following example generates a private key, which is required for signing a digital certificate:

> cd \OpenSSL_Win64
> set OPENSSL_CONF=\OpenSSL-Win64\bin\openssl.cfg
> set RANDFILE=\OpenSSL-Win64\.rnd
> openssl genrsa -out myprivatekey.key 2048
Loading 'screen' into random state - done
Generating RSA private key, 2048 bit long modulus
................................................................+++
................................................................+++
e is 65537 (0x10001)
>

Note: Safely store the myprivatekey.key file. You need this to generate your P12 certificate.

Generate Certificate Signing Request

A CSR is a message sent to a certificate authority to request an identity certificate. For more information, see Certificate signing request.

To create your CSR, type the following openssl command at a command line:

> 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 [] [email protected]

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
An optional company name []:

>

Upload CSR and Generate iOS Certificate

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.

Convert Certificate to P12 Format

After you download your certificate (default name is ios_development.cer), convert the certificate to P12 format so that you can bundle it into your application. Assuming you are in the directory where you downloaded your iOS Certificate, convert the certificate to P12 by executing the following openssl commands:

> openssl x509 -in ios_development.cer -inform DER -out ios_development.pem -outform PEM
> openssl pkcs12 -export -inkey _myprivatekey.key_ -in ios_development.pem -out ios_development.p12

Loading 'screen' into random state - done
Enter Export Password:
Verifying - Enter Export Password:

Where myprivatekey.key is the keyfile you specified when you generated your CSR.

Note: If you didn't enter a challenge password in your CSR, press the Enter key to leave this request empty.

The resulting .P12 file is the name you specified in your packager configuration file for the certificatePath setting.

App ID Creation

The App ID, also known as the Bundle ID, is a unique string used to identify your application. Obtain the App ID from the Apple Development Portal.

For development purposes, all your apps may use the same ID, however for production, this ID must be unique for each application you submit to the iTunes store. Normally the format of the ID follows reverse domain name convention of tld.domain (for example, com.mydomain.appname).

The App ID is used during the provisioning process to create a relationship between the application you're developing, and iOS certificates and devices permitted to run the application during testing.

Device Registration

(Required once for each device) - Register your device in the Apple Developer portal if you have not already done so. You will need your device's unique ID (UDID), which you can get with iTunes from your device.

To view the UDID:

  1. Open iTunes on your computer (Mac or PC).
  2. Plug in your iOS device (iPhone, iPod, etc).
  3. Click its name under the devices list.
  4. Ensure you're on the Summary tab.
  5. Click the serial number - This changes to your device's UDID.
  6. Click Copy from the Edit menu.

With your UDID in the clipboard ready for use, go to the Developer Portal and open up the Devices section.

To add your device:

  1. Select the Devices menu option.
  2. Click the [+] in the upper right hand corner to open up theAdd iOS Devices page.
  3. Enter a name for your device and its UDID (paste from clipboard).
  4. Click Continue.

Provisioning Profile Creation and Download

At this point, you've created an iOS Certificate with your credentials (Step 1), defined an App ID (Step 2) and registered your iOS device (Step 3).

You only have one step left and that is to put all these together so that your iOS device knows that it can trust your application. That's what provisioning accomplishes.

A Provisioning Profile simply links an App ID with iOS Certificates and devices authorized to run the application.

To create or update a Provisioning profile:

  1. Give your profile a name.
  2. Specify the App ID for this profile along with authorized iOS Certificates and devices.
  3. Generate and download the provisioning file which defaults to the name _profileName_.mobile provision (where profileName is the name you specified for the profile).
  4. Specify the downloaded provisioning file path and location in your packager configuration file with the provisionProfile setting:

    "provisionProfile": "profileName.mobileprovision"

When an application loads on an iOS device, iOS compares the iOS Certificate that is bundled into the application and the device's UDID against the authorized certificates and device UDIDs found in the provisioning file. If either the bundled iOS Certificate or device UDID are not found, the application is not permitted to load onto the device.

You can have mulitple provision files, one for each project you work on, or use just one provision file for all your apps. If you have just started a new app, or still are in the early stages of development, the simple thing to do is to use one provision file for all development. Eventually, though, you may find it prudent to create specific provision files for each app as the AppId added in the provisioning portal is compared to what is configured in the app, and only one AppId is permitted per app in the App Store.

For more information about provisioning files, see the Apple iOS provisioning portal (requires an Apple ID and password).

Package Configuration

The next step is to edit the Sencha packager file with appropriate settings for your environment and application testing.

Note If you are using the Touch Cordova or PhoneGap features, the packager file is not used. Refer to Cordova and PhoneGap app for more information.

In the root directory of your application there should be a packager configuration file - `packager.json'. If this file does not exist, you may easily generate one with this command:

sencha app package generate packager.json

You may now edit the packager file. The following configuration properties pertain to iOS development and are required for both debug and release configurations unless otherwise specified:

  • applicationName

The name you give your application. This name appears under your application's icon on the device's home screen.

  • applicationId

Also known as the Bundle ID, this is a unique identifier for your application. For development, all your apps may share the same App ID; however for production, the App ID must be unique for each application you submit to the iTunes store. Normally the format of the ID follows reverse domain name convention of "tld.domain" (for example, com.mydomain.appname).

The applicationId must match the application ID you enter when creating your App ID.

  • bundleSeedId

This value is the Prefix value found when viewing the App ID in the developer portal. It is a 10-character string and is the same for all your applications in your account.

  • configuration

The type of configuration for your native app build: specify Debug for development and testing, Release for publishing to the iTunes store.

  • platform

The target platform for your application: specify iOS to test on a real device or iOSSimulator to view your application in the iOS Emulator.

  • deviceType

The target device for the application. Specify iPhone or iPad.

  • certificatePath

The path to the location of your certificate file (P12 file).

  • provisionFile

The path to the location of your Provisioning file for this application.

  • permissions

It is safe to leave the permissions set to the default.

Save your packager file settings.

Creating the Packaged Application

Build your native application in the root directory of your application:

sencha app build native

This command reads your packager.json configuration file (if you are not using Cordova or PhoneGap), builds your application, and places it in the build directory. You can locate the resulting app compressed file in the native build target directory by doing a directory listing:

$ cd build/<appname>/native/
$ ls
<applicationName>.app
$

Where <appname> is the application name you specified when you ran your sencha generate app command and <applicationName> is the value you specified for the applicationName property in your packager.json file.

Copy and Run your Application

Now the moment you've been waiting for to test your application on an iOS device!

To load your application onto your device:

  1. Launch iTunes and select the Apps screen in your Library.
  2. Bring up a file browser window and locate the .app directory where your native application was built.
  3. Drag the .app directory the the Apps screen in iTunes.
  4. Select your iOS device under the Devices section of iTunes.
  5. Click the Apps tab on your device.
  6. Locate the app you just copied over to your Apps Library.
  7. Click Install.
  8. Click the Applybutton to copy the app from your Library to your iOS device.

Now switch to your device, find your application and press the icon. You should have your basic application all up and running.

Sencha Touch 2.4