Anatomy of a Sencha Touch 2 App

At its simplest, a Sencha Touch 2 application is just a small collection of text files – html, css and javascript. But applications often grow over time so to keep things organized and maintainable we have a set of simple conventions around how to structure and manage your application’s code.

A little while back we introduced a technology called Sencha Command. Command got a big overhaul for 2.0 and today it can generate all of the files your application needs for you. To get Sencha Command you’ll need to install the SDK Tools and then open up your terminal. To run the app generator you’ll need to make sure you’ve got a copy of the Sencha Touch 2 SDK, cd into it in your terminal and run the app generate command:

sencha generate app MyApp ../MyApp

This creates an application called MyApp with all of the files and folders you’ll need to get started generated for you. You end up with a folder structure that looks like this:

st2-dir-overview

This looks like a fair number of files and folders because I’ve expanded the app folder in the image above but really there are only 4 files and 3 folders at the top level. Let’s look at the files first:

  • index.html: simplest HTML file ever, just includes the app JS and CSS, plus a loading spinner
  • app.js: this is the heart of your app, sets up app name, dependencies and a launch function
  • app.json: used by the microloader to cache your app files in localStorage so it boots up faster
  • packager.json: configuration file used to package your app for native app stores

To begin with you’ll only really need to edit app.js – the others come in useful later on. Now let’s take a look at the folders:

  • app: contains all of your application’s source files – models, views, controllers etc
  • resources: contains the images and CSS used by your app, including the source SASS files
  • sdk: contains the important parts of the Touch SDK, including Sencha Command

The app folder

You’ll spend 90%+ of your time inside the app folder, so let’s drill down and take a look at what’s inside that. We’ve got 5 subfolders, all of which are empty except one – the view folder. This just contains a template view file that renders a tab panel when you first boot the app up. Let’s look at each:

Easy stuff. There’s a bunch of documentation on what each of those things are at the Touch 2 docs site, plus of course the Getting Started video with awesome narration by some British guy.

The resources folder

Moving on, let’s take a look at the resources folder:

st2-dir-resources

Five folders this time – in turn:

  • icons: the set of icons used when your app is added to the home screen. We create some nice default ones for you
  • loading: the loading/startup screen images to use when your app’s on a home screen or natively packaged
  • images: this is where you should put any app images that are not icons or loading images
  • sass: the source SASS files for your app. This is the place to alter the theming for your app, remove any CSS you’re not using and add your own styles
  • css: the compiled SASS files – these are the CSS files your app will use in production and are automatically minified for you

There are quite a few icon and loading images needed to cover all of the different sizes and resolutions of the devices that Sencha Touch 2 supports. We’ve included all of the different formats with the conventional file names as a guide – you can just replace the contents of resources/icons and resources/loading with your own images.

The sdk folder

Finally there’s the SDK directory, which contains the SDK’s source code and all of the dependencies used by Sencha Command. This includes Node.js, Phantom JS and others so it can start to add up. Of course, none of this goes into your production builds, which we keep as tiny and fast-loading as possible, but if you’re not going to use the SDK Tools (bad move, but your call!) you can remove the sdk/command directory to keep things leaner.

By vendoring all third-party dependencies like Node.js into your application directory we can be confident that there are no system-specific dependencies required, so you can zip up your app, send it to a friend and so long as she has the SDK Tools installed, everything should just work.

Hopefully that lays out the large-scale structure of what goes where and why – feel free to ask questions!

11 Responses to Anatomy of a Sencha Touch 2 App

  1. Sean says:

    Thanks for the great article.

    When I run the command “sencha generate app MyApp ../MyApp” in my Sencha SDK folder nothing happens. If I run the command “sencha” on its own I get: Sencha Command v2.0.0 Beta …

    Is there something else I need to set up? I do have the SDK Tools installed on my Macbook.

    Thanks again…

  2. Xyrer says:

    The exact same thing that happens to Sean happens to me :(

  3. Xyrer says:

    ah, forget it, solved it in the forums, thanks a lot hehe

  4. Anil Saraswathy says:

    Just when I thought I had mastered JQuery…Here comes Sencha Touch….Never thought HTML component building would be this simple….Simplification of component querying in 2.0 through references is wonderful…Personally, I like a lot the approach where you partition your application into a Sencha-based UI driving REST services at the backend written in PHP / Java / RoR….One question though, are you guys doing anything to make this SEO friendly ….When Google comes crawling, isn’t she going to index just your home page ?

  5. Suresh says:

    When I run the command “sencha generate app MyApp ../MyApp” i dont see any folder/files generated. Xyrer, can you post the forums link that you referred.

  6. Hudson .K says:

    Hey Ed ,thanks for these sdks but ,i’m having problem with the beta version sencha-touch sdk for windows ,is there work around because ,i have developed a doctor application but i need to package it for the android platform,

    Thanks for help in advance

    Best regards
    Hudson .K

  7. Ed Spencer says:

    @Hudson yes, we just put out a new SDK Tools release yesterday addressing several Windows-related issues – get it at http://www.sencha.com/forum/announcement.php?f=91&a=30

  8. Matt says:

    Hi Ed
    The generated app (which is pretty useful) only has the microloader file in index.html whereas the ST docs:

    http://docs.sencha.com/touch/2-0/#!/guide/building

    describe the html as including the sencha-touch.js directly. I can’t find any documentation about the microloader and what it does. Is there any?

    If I want to build and deploy to the app store do I use the sencha package command with the microloader/production.js?

    Thanks for any help
    Matt

  9. Ben says:

    After executed the command, app.js was created and it has a section:
    startupImage: {
    ‘320×460′: ‘resources/startup/320×460.jpg’,
    ‘640×920′: ‘resources/startup/640×920.png’,
    ‘768×1004′: ‘resources/startup/768×1004.png’,
    ‘748×1024′: ‘resources/startup/748×1024.png’,
    ‘1536×2008′: ‘resources/startup/1536×2008.png’,
    ‘1496×2048′: ‘resources/startup/1496×2048.png’
    },

    What do I need to do to load these images because I put mine in with the same names and they don’t seem to get loaded on startup.

    Thanks,
    Ben

  10. harendra says:

    Hi,
    my name is harendra and working on sencha framework from 1 year. and now i want to use sdk tools. but i am facing some problems when i am using windows machine with 64 bit os win7. Sdk is perfectly working in Apple Mac,.
    i install the sdk tool iin my windows machine. i am using wamp, so i extract sencha- touch in www folder.
    i open the terminal and redirect the path to extracted folder. and when i run the command “sencha” it gives nothing on terminal.
    but when i redirect the path to extJs extracted folder it works. but doesn’t run any other command like generate app or create jsb3.

    please help me out.
    thanks

  11. Rhonnel says:

    Hi Ed, How can i integrate the carousel in that structure inside a container or a tab panel???

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

Follow

Get every new post delivered to your Inbox.

Join 2,608 other followers

%d bloggers like this: