Robert Dougan

Veggie Meals for iPad

2012-02-04T08:03:48Z

Over the past few months I've been working with some incredibly talented people to create Veggie Meals for iPad. This is the first iOS application I have worked on and it has been a lot of fun.

Max Rudberg and Jenny Sundén contacted me after I reached out to Max on Twitter about needing an iOS developer. I didn't have much experience at the time (I still don't) but I thought "what the hell" and replied anyway. After a quick call, it was obvious that they had both spent a lot of time and effort on the app; the UX, the design, and the content. I couldn't say no.

After several months of hard work, the result is a beautifully crafted and designed recipe app that contains 55 easy to cook recipes. A lot of attention to detail has been put into every aspect of the application; the simple but tasty recipes (by Viktor Sundén), the divine photography (by Anna-Maria Will), the pixel perfect UX and design (Max Rudberg and Jenny Sundén) and of course the clean code that no one sees (me!).

Working with such talented people like Jenny and Max has been a pleasure, and I can't wait to collaborate with them again in the future.

So what are you waiting for? Download the app now!

Taking Advantage of ComponentView in Sencha Touch 2

2011-12-19T18:24:51Z

This blog post is redundant and no longer applies to latest version of Sencha Touch 2. Please read the official guide on the Sencha Touch 2 Documentation.

The GitHub project has been updated to the latest version of Sencha Touch 2. It is available here.

Sencha Touch 2 is still in preview (at the time of writing this), and although the release has been focused on performance improvements, there are a few new components that can be incredibly useful. One of the new components I love is Ext.dataview.ComponentView.

What is it?

Ext.dataview.ComponentView is basically a Ext.DataView. You bind a store to it and it shows it in a list-like fashion. However with ComponentView, each list item can be a component. As a result, the possibilities are incredible.

Please be aware that the following API may change before the Sencha Touch 2.0 final release.

Example

I've put together a simple MVC application to show you how Ext.dataview.ComponentView works. The source can be found here.

Oh, and our example application is going to have some kittens in it. NICE. So let's get started!

Structure

The MVC structure in Sencha Touch 2 is similar to Ext JS 4. You have an few important parts:

app/
- controller/
- model/
- store/
- view/
resources/
- css/
- sass/
  - config.rb
  - style.scss
lib/
- touch2/
index.html
index-debug.html

I'm not going to explain what this means here. There is a great post on the subject here and I'm sure there will be several guides in the future when Sencha Touch 2 is released.

Your Application

app.js

We need to define an app.js file so Sencha Touch knows we are creating an application. It is very simple to put together.

Ext.Loader.setConfig({enabled: true});
Ext.Loader.setPath('Ext', 'lib/touch2/src');

Ext.application({
    name: 'Example',

    controllers: ['Application'],
    views: ['Main'],

    launch: function() {
        Ext.Viewport.add({
            xclass: 'Example.view.Main'
        });
    }
});

Enable Ext.Loader.
Set the path location of the Ext.* class namespace.
Define our application.
Give it a name.
Give it the name of our only controller, Application (we don't have to use the full namespace).
Give it the name of our only view, Main (we don't need the full namespace here either);
Define a launch method which added Example.view.Main as an item to Ext.Viewport.

Model

app/model/Kitten.js

Our example is going to have lots of kittens in it which will come from a store, so we obviously need a Kitten model.

Ext.define('Example.model.Kitten', {
    extend: 'Ext.data.Model',

    fields: [
        "name",
        "image",
        { name: "cuteness", type: 'int' }
    ]
});

Define our model and extend Ext.data.Model. Notice how it uses the Example namespace.
Give the model some fields (one of which is an integer).

Store

app/store/Kittens.js

Now we have a Kitten model, we need to setup a store to use that model and give it some data. Simple.

Ext.define('Example.store.Kittens', {
    extend: 'Ext.data.Store',
    model: 'Example.model.Kitten',

    data: [
        {
            name: 'Running kitten',
            image: 'data/images/kitten1.jpg',
            cuteness: 70
        },
        {
            name: 'Spreading legs kitten',
            image: 'data/images/kitten2.jpg',
            cuteness: 90
        },
        {
            name: 'Tongue kitten',
            image: 'data/images/kitten3.jpg',
            cuteness: 70
        },
        {
            name: 'Ginger kitten',
            image: 'data/images/kitten4.jpg',
            cuteness: 80
        },
        {
            name: 'Kitten friends',
            image: 'data/images/kitten5.jpg',
            cuteness: 20
        },
        {
            name: 'Milk kitten',
            image: 'data/images/kitten6.jpg',
            cuteness: 50
        }
    ]
});

Define our store and make it extend Ext.data.Store.
Give it a model of Example.model.Kitten (which we defined above).
Give it some fake data.

Controller

app/controller/Application.js

We only have one controller in our application, and it isn't going to do much. For now, we just need to include our Kittens store and the KittensList view (which we'll create later).

Ext.define('Example.controller.Application', {
    extend: 'Ext.app.Controller',

    stores: ['Kittens'],
    views: ['KittensList']
});

Define our controller and make it extend Ext.app.Controller.
Give it our store (notice how we don't have to add Examples.store., it's done automatically).
Give it our view (no namespace just like above).

Views

app/view/Main.js

We need to add a global view for application, which basically acts as a Viewport. We shall call this Main.js. There isn't much to it.

Ext.define('Example.view.Main', {
    extend: 'Ext.Container',

    requires: ['Example.view.KittensList'],

    config: {
        layout: 'fit',

        items: [
            { xclass: 'Example.view.KittensList' }
        ]
    }
});

Define our view and make it extend Ext.Container.
Give it some requires for our Example.view.KittensList component (defined next).
Give it a fit layout so the list stretches to the size of this container.
Add the Example.view.KittensList as a child item of the container.

app/view/KittensList.js

The first view we will create is Example.view.KittensList. It is going to extend Ext.dataview.ComponentView and it's not gonna do much.

So here's the code:

Ext.define('Example.view.KittensList', {
    extend: 'Ext.dataview.ComponentView',
    xtype: 'kittenlist',

    requires: ['Example.view.KittensListItem'],

    config: {
        cls: 'kitten-list',
        store: 'Kittens',
        defaultType: 'kittenslistitem'
    }
});

We define the class and extend Ext.dataview.ComponentView.
Add a custom cls so we can make it pretty.
Give it a store (Kittens to be exact).
Give it a defaultType which is the default xtype of any components being added to the list.

app/view/KittensListItem.js

This view is going to be used as the defaultType of the above Example.view.KittensList. There is a little bit of magic that goes on in this class, so I will go through it a little slower. Sorry about it's length (that's what she said).

So first up, the base of the class:

Ext.define('Example.view.KittensListItem', {
    extend: 'Ext.dataview.DataItem',
    xtype : 'kittenslistitem',

    config: {
        cls: 'kitten-list-item'
    }
});

We extend Ext.dataview.DataItem.
Give it an xtype (which we are using above).
Add the cls config so we can style it.

So we have the basics of the application put together now. If you open it up in a browser, it will show a list with a bunch of items. Unfortunately, because the ListItem has no content, it will be blank.

So what we gotta do to make it display?

New Configurations

First up, we need to add new configurations for each of the different views we are going to have in each list item. To do this, we need to know what it is going to look like.

So you can see we are going to show an image of the kitten, the name of the kitten and a slider which will show the cuteness of the kitten; all inside the Examples.view.KittensListItem.

So let's go ahead and add a configuration for each one of these components:

config: {
    ...

    image: true,

    name: {
        cls: 'x-name',
        flex: 1
    },

    slider: {
        flex: 2
    }
}

The image configuration will be transformed into a Ext.Img component.
The name configuration will be transformed into a Ext.Component component.
The slider configuration will be transformed into a Ext.slider.Slider component.

So how do these configurations get transformed?

What we need to do is add apply and update methods for each of this configurations. Let me show you the code.

applyImage: function(config) {
    return Ext.factory(config, Ext.Img, this.getImage());
},

updateImage: function(newImage, oldImage) {
    if (newImage) {
        this.add(newImage);
    }

    if (oldImage) {
        this.remove(oldImage);
    }
}

The apply method (which is called when setImage is called) will use Ext.factory to take the passed configuration, and any existing instance (using getImage) and return a new instance of the type passed (in this case, Ext.Img).

Then in our updateImage method, we simply add the newImage into the list item, and remove oldImage item if one exists.

Make sense? If not, take a look at the Class System guide.

We need to now do the same for the other two configurations:

applyName: function(config) {
    return Ext.factory(config, Ext.Component, this.getName());
},

updateName: function(newName, oldName) {
    if (newName) {
        this.add(newName);
    }

    if (oldName) {
        this.remove(oldName);
    }
},

applySlider: function(config) {
    return Ext.factory(config, Ext.slider.Slider, this.getSlider());
},

updateSlider: function(newSlider, oldSlider) {
    if (newSlider) {
        this.add(newSlider);
    }

    if (oldSlider) {
        this.remove(oldSlider);
    }
}

The same idea again, only using Ext.Component and Ext.slider.Slider as the component of choice.

Requires

We are now using the Ext.Img and Ext.slider.Slider components in our list item, so we must require those classes so when this list item class is loaded, the required class are also loaded.

... 

requires: [
    'Ext.Img',
    'Ext.slider.Slider'
]

...

Note: this is not inside the config block.

Layout

Now we have items inside each list item, we must have them displayed properly. For this, we use the layout configuration and set it to hbox.

config: {
    ...

    layout: {
        type: 'hbox',
        align: 'center'
    }
}

dataMap

This is were the magic begins.

The dataMap configuration allows you to call functions with a value of a field, on functions of your list item.

Stumped? Let's look at the code:

config: {
    ...

    dataMap: {
        getImage: {
            setSrc: 'image'
        }
    }
}

So you can see we defined the dataMap configuration. It is just an object with a few keys and values. The key of each item is the method name you want to call. This method name must return something, and then with that returned value, it will call the key of the inner object with the value (which is a field name).

So with the above code, this is what happens when the record of the list item is updated:

We get the new record.
We then call: listItem.getImage().setSrc(record.get('image'));

Understand now? Good job!

So now we have figured this out, we need to add the correct dataMap for each of the fields so the whole item has the correct look.

config: {
    ...

    dataMap: {
        getImage: {
            setSrc: 'image'
        },

        getName: {
            setHtml: 'name'
        },

        getSlider: {
            setValue: 'cuteness'
        }
    }
}

Custom CSS

For this example I have used SCSS to make it look a little better.

As always, there isn't much too it:

//include sencha touch
@import 'sencha-touch/default/all';

//include layout and form parts of sencha touch
@include sencha-layout;
@include sencha-form-sliders;

//define a variable so we can have consistant padding throughout the app
$list-padding: .7em;

//body background
body {
    background: #eee;
}

//kitten list styling
.kitten-list {
    .x-dataview-inner {
        padding: $list-padding;
    }

    //kitten list item styling
    .kitten-list-item {
        padding: $list-padding/2;
        background: #fff;
        border: 1px solid #ccc;
        border-bottom-width: 0;

        //add rounded corners to the last item
        &:last-child {
            border-bottom-width: 1px;
            @include border-bottom-radius($list-padding/2);
        }
    }

    //add rounded corners to the first item
    .x-mask + .kitten-list-item {
        @include border-top-radius($list-padding/2);
    }

    .kitten-list-item .x-img {
        background: #eee;
        background-size: cover;
        background-position: center center;

        @include border-radius($list-padding/2);

        width: 80px;
        height: 80px;
    }

    .kitten-list-item .x-name {
        padding: 0 $list-padding/2;
    }
}

I've added inline comments to explain everything.

Before

After

What if we want to know when the slider changed?

Each list item now has a slider, of which the value can change. So what if you want to know when that happens? Doing this is pretty simple.

Let's go back to our controller.

app/controller/Application.js

What we want to do is override our init method in our controller, so we can call control with any listeners we have on our views.

init: function() {
    this.control({
        'kittenslistitem slider': {
            change: this.onCutenessChange
        }
    });
},

onCutenessChange: function(slider, value) {
    //we should do something here
    console.log('onCutenessChange', value);
}

We define the init method
We call the control method, which you can pass a ComponentQuery and then which events you want to listen to (change in this case), and then we give it a method to call.
Define the onCutenessChange method so we know something happens.

Now if you reload and move one of the sliders, you will get a billion logs of value being changed. NICE.

Incredible, but be careful

As you can see, the flexibility and power available when using the new Ext.dataview.ComponentView is incredible. This can be so very useful in many, many occasions.

But it's not all good..

So let's say we created this same example with a Ext.DataView (but without the slider). In total, your application would have 2 component; Main.js and KittensList.js. With Ext.dataview.ComponentView though, that number goes up to 20, and that is with only 6 rows in the store. This can drastically increase memory usage and the amount of DOM generated for all your list items. So you must watch out when using this.

Conclusion

If you have any issues, feel free to comment below; but only after you checkout the source over on GitHub (I've included loads of documentation in the actual source code).

That will be all.

Packaging your Sencha Touch 2 Application using the Sencha SDK Tools

2011-12-10T02:35:39Z

Once your application is ready for production, you should compile all your JavaScript files into one. There are two reasons for this:

There will only be one request for your Application. Having several file requests in a mobile browser can dramatically reduce your application's loading time.
You can compress your JavaScript, so you can cut down on the final file size.

Sencha have their SDK Tools product which allows you to do just that. Not only that, but the SDK Tools will allow you to only include parts of Sencha Touch your application actually uses. In most cases, this could help you reduce your application file size by hundreds of kilobytes, which is huge!

So lets get started.

Installation

You can find the SDK Tools download link over on the Sencha Website.

Ensure you download the SDK Tools 2 beta version, as it is compatible with Sencha Touch 2. Unfortunately it is only available for Mac at the time of writing this.

Once installed, open up Terminal.app and confirm that the sencha command is available (you will need to open a new Terminal window for it to work).

If for some reason it is not available, open up your ~/.profile file (or your bash profile, if different) and check if the following lines are there:

export PATH=/Applications/SenchaSDKTools-2.0.0-Developer-Preview:$PATH
export PATH=/Applications/SenchaSDKTools-2.0.0-Developer-Preview/command:$PATH
export PATH=/Applications/SenchaSDKTools-2.0.0-Developer-Preview/jsbuilder:$PATH

If not, add them and save the file. Then open a new Terminal window and try again.

If the sencha command is still not available, please contact me at rdougan@me.com.

Your Application

By this point, I presume your application is fully functional, and is available on a web server. My local setup uses the Apache web server available on OSX by default. If you don't know how to do this, Google is your friend.

If you do not have an application but still want to follow along, you can download my sample application from GitHub. Please follow the README to download and include Sencha Touch 2 into the project.

Next, setup the example up so you can view it on a server. I can view the application at http://rob.local/cocktails/ (local URL), and it looks a little like this:

The actual files on my Mac are available at ~/github/cocktails.

Notes before we continue

Right now the SDK Tools builder is a little buggy. One of the main issues is that you must require all Sencha Touch components you use.

So let's say you have a view called MyApp.view.Detail:

Ext.define('MyApp.view.Detail', {
    extend: 'Ext.Container', 

    config: {
        items: [
            {
                xtype: 'button',
                text: 'My Button'
            }
        ]
    }
});

Notice how we have one item in this view, which is a button. Now when you are running in development mode, Sencha Touch will know to load this file correctly, but in production mode, it will not. So you must add a requires statement into your view for any components you are using (third line):

Ext.define('MyApp.view.Detail', {
    extend: 'Ext.Container',
    requires: ['Ext.Button'],

    config: {
        items: [
            {
                xtype: 'button',
                text: 'My Button'
            }
        ]
    }
});

You must do this for all of your views, or when you build, it will not include those components for you.

This will be fixed in a future release of the builder.

HTML Files

Your application probably already has a index.html file, but we must create one for both development and production.

index-debug.html - development

This index file is the one you should use for development. It will include uncompressed versions of Sencha Touch, and your application. It also uses dynamic loading, so loading time for your application will be much slower.

Here is an example of my index-debug.html file:

<!doctype html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>Cocktails</title>

        <!-- Sencha Touch -->
        <script src="lib/touch2/sencha-touch-debug.js"></script>

        <!-- Google Maps -->
        <script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true"></script>

        <!-- CSS -->
        <link rel="stylesheet" href="resources/css/style.css"/>

        <!-- Application -->
        <script src="app.js"></script>
    </head>

    <body></body>
</html>

Two parts of this which are important:

Line 8 - you must include the sencha-touch-debug.js file from the Sencha Touch SDK. You must use this file.
Line 17 - the app.js file is the base file of your application. All other application files will automatically get loaded.

index.html - production

Here is an example of a index.html file. Your version should not vary much from this, other than the <title> and perhaps including some extra resources.

<!doctype html>
<html>
    <head>
        <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
        <title>Cocktails</title>

        <!-- Google Maps -->
        <script type="text/javascript" src="http://maps.google.com/maps/api/js?sensor=true"></script>

        <!-- CSS -->
        <link rel="stylesheet" href="resources/css/style.css"/>

        <!-- Application -->
        <script src="app-all.js"></script>
    </head>

    <body></body>
</html>

There is one very important part of this which must be correct:

Line 14 - the app-all.js file, which will be the compressed version of Sencha Touch and your application.

Creating your JSB3 file

The first thing you need to do is generate a jsb3 file. This file will contain a URL to every file your application uses, both custom and Sencha Touch source files. The SDK Tools builder will use this to then compile your application into 1 file.

To generate your jsb3 file, run the following command from Terminal.app:

sencha create jsb -a http://rob.local/cocktails/index-debug.html -p app.jsb3

As you can see, we just pass in a link to your index-debug.html file (which must be on a server) and the path where we want to output the jsb3 file.

You should now have a app.jsb3 that looks a little like this:

Updating the JSB3 file

There are a few bits we need to adjust to finish off the JSB3 configuration:

Update the projectName and licenseText properties right at the top of the file.
Scroll down to the bottom of the file, to where you see Application - Production. What we want to do is include sencha-touch-debug.js so all JavaScript your application needs is compressed into one file. You need to add an object into the files array, and it must be the first file.

Here is an example of #2:

{
    "name": "Application - Production",
    "target": "app-all.js",
    "compress": true,
    "files": [
        {
            "path": "lib/touch2/",
            "name": "sencha-touch-debug.js"
        },
        {
            "path": "",
            "name": "all-classes.js"
        },
        {
            "path": "",
            "name": "app.js"
        }
    ]
}

Building the compressed application files

Finally, we are ready to roll. Open up Terminal.app again and run the follow command.

sencha build  -p app.jsb3 -d .

Once the command has completed, you will have a new app-all.js file. If you open up index.html in a browser, your application should load, but only with just one request for JavaScript.