Sample Code

We are going to build on the sample project we created in part one so if you haven’t already, grab a copy from the GitHub repository. The code from this article can be found in the “TakingItFurther” branch.

NOTE: To try this code you will need a TestFlight account and upload a new build of the sample application to TestFlight in order to try out each new feature.

Custom Environment Information

When you track a user’s session with the TestFlight SDK it automatically collects various bits of information about the user’s device and setup. The image below shows this information from my phone when using our test application.

This collects a lot of details and you probably see everything you might need on that list but TestFlight allows us to grab as many other bits of information we are want and add them to this list.

We use the addCustomEnvironmentInformation method of our TestFlight object to add a name/value pair to the environment information. This data will then be sent up to TestFlight when we ‘take off’.

If you add the following code snippet to your onDeviceReady method, right after the setDeviceIdentifier call, we will add an environment variable named “My Environment Variable” with a value of “Some environment info”. As usual the method accepts success and failure callback methods as the first two parameters.

TF.addCustomEnvironmentInformation(function(){
    console.log('Add Custom Environment Info Success');
}, function(){
    console.log('Add Custom Environment Info Failure');
}, 'My Environment Variable', 'Some environment info');

By adding this code and starting a new session, we will see our new variable added to the Session Details screen.

Please note that these calls should be made before ‘take off’.

Remote Logging

In our application we are performing several console.logs at various points to indicate what is happening in our code. This is great for when we are testing in the browser and when debugging on a device via xCode but this information isn’t available once the app is loose on testers’ devices. The TestFlight SDK offers a remote logging mechanism that will send up logging strings and attach them to the user’s session. You can then browse these items and see what happened during the session.

We will add a simple logging message when we have successfully completed our ‘take off’. We add the following code into the callback function of the takeOff call, passing in success and failure callback functions and the string we would like to log.

TF.remoteLog(function(){
    console.log('Remote Log Success');
}, function(){
    console.log('Remote Log Failure');
}, 'Take Off Success');

It is important to note that logging can only be done after “take off” which is when the session starts.

On the TestFlight website we can browse the logs that have been made during a session by clicking the “Sessions” item on the left hand menu and then clicking the blue “i” icon beside the relevant Session (you may have to click the user’s row to expand the Sessions if they have more than one). On the modal window that appears you must use the dropdown menu at the top right to display the log messages. The Log record will show all the auto-generated log messages (such as Checkpoints and internal logs) as well as your custom ones.

Collecting Feedback

The TestFlight SDK makes it very easy for us to collect feedback from our users at any point within our application. The openFeedbackView method will open a native form, overlaying our application, which allows the user to enter some text that, when submitted, will be attached to the build for viewing on the website and also emailed to you.

We will add another link to our app that will show this view and collect feedback from the user. You might prefer to have the form automatically appear when the user completes an action in your application, for example, after updating their profile, ask them how easy it was.

The following HTML is added below our existing links:

<a href="#" onclick="doOpenFeedback()">Submit Feedback</a>

We then add the doOpenFeedback function inside our JavaScript tags:

function doOpenFeedback(){
    console.log('Opening Feedback');
    // Open the TestFlight SDK's feedback form
    TF.openFeedbackView(function(){
        console.log('Feedback Callback Success');
    }, function(){
        console.log('Feedback Callback Failure')
    });
}

Once again we pass in success and failure callback functions but that is all we need to add – the SDK takes care of the submission.

You can view all feedback received from a build on the TestFlight website by clicking the “Feedback” link in the left hand menu.

Custom Feedback Submission

Although the previous technique for collecting feedback is very easy, it might not be versatile enough for those who want to collect more in-depth feedback. To address this we can use the submitFeedback method which allows us to collect our own feedback string and submit it ourselves.

We are going to demonstrate this by creating a small feedback form with a textarea and a select field. We add this to the bottom of our HTML document.

<div id="customFeedback" style="display: none;">
    <h1>Custom Feedback</h1>
    <label for="feedback">Feedback</label>
    <br/>
    <textarea id="feedback"></textarea>
    <br/><br/>
    <label for="rating">Rating</label>
    <br/>
    <select id="rating">
        <option value="1">1</option>
        <option value="2">2</option>
        <option value="3">3</option>
        <option value="4">4</option>
        <option value="5">5</option>
    </select>
    <br/><br/>
    <button onclick="submitCustomFeedback()">Submit</button>
</div>

When tapped, the Submit button will execute the submitCustomFeedback method which will collect the data from the form and pass it to the SDK’s submitFeedback method. The following code does this:

function submitCustomFeedback(){
    console.log('Submitting Custom Feedback');
    // Get references to our form and fields, and build our feedback string
    var feedbackForm    = document.querySelectorAll('#customFeedback')[0],
        feedbackField   = document.querySelectorAll('#feedback')[0],
        ratingField     = document.querySelectorAll('#rating')[0],
        feedbackString  = 'Feedback: ' + feedbackField.value + '. Rating: ' + ratingField.value;
    // hide the form
    feedbackForm.style.display = 'none';
    // Submit our custom feedback string
    TF.submitFeedback(function(){
        console.log('Custom Feedback Submit Success');
    }, function(){
        console.log('Custom Feedback Submit Failure');
    }, feedbackString);
}

This short function will grab references to the form and its fields, then use the fields’ values to create a feedback string. The feedback string is then passed to the SDK’s submitFeedback method as its third parameter (the first and second being success and failure callback functions respectively).

In order for the form to be shown we add another link to our app that will show the form’s DIV.

<a href="#" onclick="doCustomFeedback()">Custom Feedback</a>

The doCustomFeedback function simply gets a reference to the form and toggles its display property.

function doCustomFeedback(){
    console.log('Opening Custom Feedback');
    var feedbackForm = document.querySelectorAll('#customFeedback')[0];
    if(feedbackForm.style.display === 'none'){
        feedbackForm.style.display = 'block';
    } else {
        feedbackForm.style.display = 'none';
    }
}

The feedback submitted through this method will be dealt with in the same way as feedback submitted using the built-in form.

Collecting User Feedback with Questions

The TestFlight SDK allows us to attach questions to each of our defined Checkpoints that allows us to collect specific information from users. This is an alternative to creating your own custom feedback form like we did in the previous section but it is important to note the difference in the way the collected data is handled.

Questions are defined and attached to a build after it has been uploaded to TestFlight and are attached to the Checkpoints that the app knows about.

In our app we will add a question to our “Awesome Feature 2″ Checkpoint. We log into TestFlight and navigate to our latest build. We then click the “Questions” link at the bottom of the left hand menu.

Click the “Add Question” button and a form is shown where we define our question. Questions can have 3 formats: Yes/No, Multiple Choice or Long Answer. We are going to create a very simple Yes/No question (shown below) and attach it to the “Awesome Feature 2″ Checkpoint.

After clicking Save we see our question in the list and the fact it has zero answers. If we now launch our application on our device (you will need to quit and then restart the app first) and tap the “Awesome Feature 2″ link we will be presented with a new view containing our question.

If we answer the question with “Yes” (of course…) then we can refresh our dashboard screen and see the response being logged.

Summary

This has been a quick rundown of the more advanced features of the TestFlight SDK that are made very easy to integrate using the PhoneGap plugin. You should now be able to perform Remote Logging; collect Feedback using the built-in form and a custom HTML form; track Custom Environment Information and prompt users to answer Questions about a specific Checkpoint they have just passed. Not bad!

Let me know if you have any questions or comments below!

Supporting Code

All the code that we create in this tutorial can be found on our GitHub account so you can grab it from there and reference it as you follow if you prefer.

Create a Blank iOS Project

We’re going to create a blank iOS PhoneGap project to work with in this tutorial but if you already have a project you want to integrate the plugin with then you can skip ahead to the next step.

We start by creating a new project folder somewhere on your hard drive – I’m going to create one called “TestFlightPG”.

Next we’re going to download the latest version of PhoneGap and paste a copy into our project folder. We are doing this purely for convenience when it comes to commands so if you’re comfortable modifying the next commands to reference the PhoneGap folder somewhere else then go for it!

With that in place we can create our iOS project. PhoneGap comes with some nifty command line tools for getting us up and running extremely quickly by creating an iOS project with everything set up already. We create our project by opening up a Terminal window and “cd”ing to our “TestFlightPG”" folder. In my case the command is:

cd Workspace/TestFlightPG

Now we’re in the right place we run the following command to create our blank project:

PhoneGap2.7/lib/ios/bin/create iOS com.SwarmOnline.TestFlightPG TestFlightPG

This will call the iOS create command which will create a new folder called iOS and generate an iOS project named TestFlightPG in that folder with the identifier com.SwarmOnline.TestFlightPG. Easy!

Integrating the TestFlight Plugin

Before we can integrate the plugin we need to grab a copy of it from its GitHub repository. It is currenly hosted outside of the usual PhoneGap Plugins repo – (https://github.com/shazron/TestFlightPlugin). Either clone the repository or download the ZIP archive and then move this folder into our TestFlightPG project folder. We should have something like this:

Adding TestFlight SDK

Now that we have a new project and the plugin code, we need to open the project in xCode, where we see a blank PhoneGap project.

Fortunately, the plugin already contains the latest TestFlight SDK code (1.2 as of writing) so our first step is to copy this into our project.

We start by creating a new group under the TestFlightPG heading and name it TestFlight. We do this by right clicking the TestFlightPG heading and choosing “Create Group”.

Next we add the TestFlight SDK files into our new group by right clicking it and choosing “Add Files to TestFlightPG…”. We navigate to the TestFlightPlugin folder inside our parent project folder and find the libTestFlight.a and TestFlight.h files inside the “src/ios” folder. Make sure you tick the “Copy items into destination group’s folder” option so the files get moved into our project.

Adding TestFlight Plugin Code

Our next step is to add the PhoneGap plugin files into the project. We follow a similar process as above by creating a new Group inside the Plugins group and naming it TestFlight.

We can then right click it and choose the “Add Files to TestFlightPG…” option. In the file chooser, we add the other two files from the “src/ios” folder – CDVTestFlight.h and CDVTestFlight.m. Once again, we make sure the “Copy items into destination group’s folder” option is ticked.

Once we have done this we should have a project that looks similar to the following:

Adding Library References

Once this has been done we need to add a reference to a library called libz.dylib. We do this by selecting our TestFlightPG “Target” and then clicking the Build Phases tab. We then expand the “Link Binary with Libraries” section. You should be seeing something similar to the screenshot below:

We add the library by clicking the “+” button at the lower left of the section and then filtering the list by typing in the library name.

You can then select the last option (the one without any version numbers) and click “Add”.

Updating Config.xml

The final step in integrating the plugin is to update the config.xml file which holds all the PhoneGap configuration. We must add two things:

First we must reference the TestFlight plugin so it is initialised correctly. We do this by adding the following line inside <plugins> tags.

<plugin name="TestFlightSDK" value="CDVTestFlight" />

Secondly, we update the external hosts whitelist to allow calls to all “testflightapp.com” domains. In our example we have a wildcard set up so we don’t need to do this but if you are integrating into an existing app then add the following line to your config.xml.

<access origin="*.testflightapp.com" />

Our final config.xml should look like this:

We have now integrated the TestFlight SDK and the PhoneGap plugin into our project, so now all that’s left is to set up our JavaScript so we can start using it.

Adding and Configuring the TestFlight Plugin’s JavaScript

This section is going to focus on how we set up and interact with the TestFlight plugin from our app’s JavaScript.

Creating our Test “App”

In our blank PhoneGap project we are given a sample web app (inside the www folder) – we’re going to go ahead and remove all these files apart from the index.html and cordova-2.7.0.js.

W’re going to replace the contents of the index.html with the following code. We want to have a very simple page that references the Cordova (nee PhoneGap) JavaScript file and adds a handler to the deviceready event (which will log a message to the console). This event fires when PhoneGap has sorted itself out and all of its interfaces are available for us to interact with.

<!DOCTYPE html>
<html>
    <head>
        <title>TestFlightPG</title>
        <script type="text/javascript" src="cordova-2.7.0.js"></script>
        <script type="text/javascript">
            document.addEventListener('deviceready', onDeviceReady, false);
            function onDeviceReady() {
                console.log('Device Ready');
            }
        </script>
    </head>
    <body>
    </body>
</html>

Add the TestFlight Plugin’s JavaScript Script

Just like PhoneGap itself, the TestFlight plugin has its own JavaScript script which gives us a nice interface to interact with the plugin’s native code. We import the file (testflight.js) from the “TestFlightPlugin/www” folder we added to our project earlier, into our own “www” folder.

We can then add a reference to this new script in our HTML page after the one for the Cordova script.

<script type="text/javascript" src="testflight.js"></script>

This now means once that the “deviceready” event fires we can start interacting with the TestFlight plugin.

Requiring the Plugin

The first thing we must do is “require” the TestFlightPlugin so it gets loaded up and we have an object to work with throughout our codebase. We do this by simply adding the following line to our onDeviceReady method.

window.TF = cordova.require("cordova/plugin/testflightsdk");

We assign the output of this cordova.require call in a global variable name TF. We do this so we can reference it anywhere in our code.

Identifying the User

Now we have a global reference to the initialised plugin we start by identifying the user. The SDK no longer uses the device’s UUID, so in order to allow identification of a user’s data we must provide an ID – in your own application you might wait until login and use the user’s Username or UserID. In our case we’re going to use the UUID provided by PhoneGap – it’s not ideal but serves the purpose here.

So after the require call we call the setDeviceIdentifier method passing in a success callback function, a failure callback function and the ID itself.

TF.setDeviceIdentifier(function(){
    console.log('Device Identify Success');
}, function(){
    console.log('Device Identify Fail');
}, window.device.uuid);

We just log a message on success/failure but you can do something more interesting, or just pass in an empty function.

At this point our onDeviceReady function should look like this and if we launch our app we should see a blank screen and our two console logs in the output window (among others).

function onDeviceReady() {
    console.log('Device Ready');
    // Require the TestFlight SDK
    window.TF = cordova.require("cordova/plugin/testflightsdk");
    // Identify the current Device
    TF.setDeviceIdentifier(function(){
        console.log('Device Identify Success');
    }, function(){
        console.log('Device Identify Fail');
    }, window.device.uuid);
}

Ready for TakeOff?

Inkeeping with the aeronautical theme of TestFlight we start the SDK’s tracking session by using the takeOff method. Into this we pass the standard success and failure callback functions and also your TestFlight Application’s App Token. This token is used to hook up the SDK to your account – we’ll explain where to get that in a moment.

First, let’s add this takeOff call to our onDeviceReady:

TF.takeOff(function(){
    console.log('Take Off Success');
}, function(){
    console.log('Take Off Fail');
}, '<TEST FLIGHT APP TOKEN>');

Interestingly, if you run your app now, the success callback will be executed but we also get an error alerting us that the App Token is incorrect. Which it is.

Finding your Application Token

Before we can go any further we need to locate your TestFlight Application Token – I’m going to assume you already have a TestFlight account so fire up your browser and navigate to TestFlightApp.com and login.

Navigate to your App by clicking on the Apps link on the main navigation bar, then click your app’s name from the list – in our case the app is called “TestFlightPG”.

On the following screen you need to click the cunningly named App Token item on the left menu so you get a screen like this:

The big string in the middle is the token we are after, so go ahead and copy and paste it into our takeOff call.

Now let’s launch our app in xCode and see how far we get this time! We should now see a more encouraging message in the output saying our App Token has been recognized. Yaldi!

Adding Checkpoints

So now we’re at the step we all wanted to be at the start… tracking user interactions. We’ll start by adding a couple of links to our page to represent our app’s actions and bind them to an onclick handler – inline… I know, old-school!

Fire the following code into your <BODY>:

<a onclick="doTrackLink('Awesome Feature 1')">Awesome Feature 1</a>
<br/><br/>
<a onclick="doTrackLink('Awesome Feature 2')">Awesome Feature 2</a>

and this JavaScript function into our <SCRIPT> tag:

function doTrackLink(name){
    console.log('Tracking Link: ' + name);
}

Launching the app now and tapping our two links should see them being logged to the console output – all’s working nicely (see things can work without jQuery or Sencha ).

Now we add in our call to send the checkpoint to the TestFlight SDK – we use the passCheckpoint method which accepts a success and failure callback and a string that will be used as the checkpoint’s identifier. TestFlight will group and count checkpoint passes by this identifier so make it unique and human readable so you can understand your stats!

Add the following code to the doTrackLink method:

TF.passCheckpoint(function(){
    console.log('Pass Checkpoint Success');
}, function(){
    console.log('Pass Checkpoint Fail');
}, name);

When we run our app now and click some links we should get some nice noises coming back from TestFlight – our checkpoints are working!

Viewing our Checkpoints

Having our app log checkpoints is all well and good but if we can’t see the data it’s no use, right? Fortunately, TestFlight has created a neat little tool to allow us to view our SDK interactions in real-time and verfiy that things are working correctly and the SDK is really receiving our calls.

The SDK Debugger can be accessed via the link named “SDK Debugger” just under the “App Token” link we used earlier. When you get there you will see an Events list and a couple of action buttons.

If we launch our app and start clicking on the links we should be able to go back to the SDK Debugger and see these events coming up with various details about the device etc. Noice!

At this point you won’t see any stats inside the TestFlight Live dashboard – stats will only here once a build has been properly submitted to TestFlight.

Summary

So by now we should have the TestFlight SDK integrated with our iOS PhoneGap application (via the TestFlight PhoneGap plugin) and have it hooked up to our TestFlight account and recording checkpoint markers.

We are going to make this into a mini-series of posts and next time will look at some of the other features (over and above Checkpoints) that the TestFlight SDK has to offer. We will then look at integrating it neatly with a Sencha Touch application.

Keep checking back for updates and as always let us know if you have any questions or comments in the comments area below!

PhoneGap and the TestFlight SDK – Taking if Further, the second part of this mini-series, is available now!

When adding logic to Sencha Touch views we often need to grab references to internal Components to manipulate them.

We find ourselves having to either cache a reference to items by creating them individually or adding getter methods that performed a ComponentQuery or that delved into the items collection.

The code below shows these techniques in a sample component:

Ext.define('MyContainer', {
    extend: 'Ext.Container',
    config: {
        items: [
            {
                xtype: 'component',
                itemId: 'myComponent',
                html: 'My Component'
            },
            {
                xtype: 'component',
                itemId: 'myOtherComponent',
                html: 'My Other Component'
            }
        ]
    },
    initialize: function(){
        this.callParent(arguments);
        this.myButton = Ext.create('Ext.Button', {
            text: 'My Button'
        });
        this.add(this.myButton);
    },
    getMyComponent: function(){
        return this.query('#myComponent')[0];
    },
    getMyOtherComponent: function(){
        return this.getItems().getAt(1);
    }
});

The Solution

This override allows you to define quick references, based on ComponentQueries, to the Components in a view, like you would in a Controller, so that the references to those components exist in the view automatically.

We use this override by adding a refs property to your view’s definition and giving it an object literal where each key is the property the reference will be assigned to and the value, a Component Query that is used to target it.

Our previous example could be rewritten as follows:

Ext.define('MyContainer', {
    extend: 'Ext.Container',
    refs: {
        myComponent     : '#myComponent',
        myOtherComponent: '#myOtherComponent',
        myButton        : 'button'
    },
    config: {
        items: [
            {
                xtype: 'component',
                itemId: 'myComponent',
                html: 'My Component'
            },
            {
                xtype: 'component',
                itemId: 'myOtherComponent',
                html: 'My Other Component'
            },
            {
                xtype: 'button',
                text: 'My Button'
            }
        ]
    },
    initialize: function(){
        this.callParent(arguments);
        // reference components using the new properties
        // this.myComponent
        // this.myOtherComponent
        // this.myButton
    }
});

This technique saves us few lines of code and makes things a little tidier for us to code against.

The Override

The override adds a new method called processRefs to the Ext.Container class which iterates over each item in the refs property, executing its Component Query and assigning the first result to a property with the name you gave it in your config.

This processRefs called in an override of the applyItems method.

The full override code can be seen below:

Ext.define('Ext.overrides.Container', {
    override: 'Ext.Container',
    applyItems: function(items, collection){
        var returnVal = this.callOverridden(arguments);
        this.processRefs();
        return returnVal;
    },
    /**
     * Iterates over the 'refs' property performing each query and assigning its result
     * to a property with the right name.
     * @method
     * @private
     */
    processRefs: function(){
        var refs = this.refs;
        if(refs){
            Ext.Object.each(refs, function(key, val){
                this[key] = this.query(val)[0];
            }, this);
        }
    }
});

To Integrate the override in your project just add it to a file called “Container” in your “app/overrides” folder and “required” it in your application.

In the week running up to the first issue being released we have had close to 100 subscribers signing up and are delighted to see that number growing every day. We hope to continue this growth once the first issue is sent out and the word begins to spread.

What is Sencha Insights?

Sencha Insights is a curated newsletter focusing on Sencha and other related web technologies. We created Sencha Insights because we we felt that there was a lot of great content being produced and thought that it wasn’t always being seen by the community (ourselves included!). A place where this material was collected and distributed in an easy to consume way would be very beneficial to the community.

How can I subscribe?

You can subscribe to the newsletter by heading over to www.SenchaInsights.com and entering your email address in the form. Once you’ve confirmed your email address you will receive the newsletter every second Wednesday.]]> http://www.swarmonline.com/2013/03/launching-sencha-insights/feed/ 0 http://www.swarmonline.com/2013/02/documenting-your-sencha-apps-with-jsduck/ http://www.swarmonline.com/2013/02/documenting-your-sencha-apps-with-jsduck/#comments Thu, 28 Feb 2013 02:52:12 +0000 Stuart http://www.swarmonline.com/?p=1724 JSDuck is an API Documentation generator created to make documenting Ext JS, Sencha Touch and any other JavaScript applications a walk in the park. JSDuck was originally created by Rene Saarsoo but is now maintained by SenchaLabs and is available on GitHub.

In a nutshell JSDuck parses your source code and generates documentation based on the comments within the code – with a similarly awesome interface as the Ext JS and Sencha Touch docs.

In this blog post we’re going to talk about how you can easily get JSDuck integrated into your project and easily generate some excellent documentation for you app*.

*Unfortunately, JSDuck won’t improve the content or relevancy of your documentation!

Installing JSDuck

Installing JSDuck is very straightforward and involves very few steps.

On Mac

Mac users should be able to install the package using the gem. Open a Terminal window and type the following:

[sudo] gem install jsduck

On Windows

Windows users can download an EXE package that contains all the dependencies needed from the SoureForge downloads page. Simply save this file somewhere convenient and accesible from your project and you’re good to go!

Running JSDuck

To get started we’re going to run JSDuck on the Ext JS SDK and generate the documentation for the entire Ext JS framework with the bare bones command. We start by opening a Terminal(or Command Prompt) window and navigate to the SDK folder on your hard drive. If you don’t have the SDK on your machine you can download it from the Sencha website. From here we can type the following command to generate our documentation set:

For Mac

jsduck src --output newdocs

For Windows

path/to/jsduck.exe src --output newdocs

If you open the SDK in Finder/Explorer you should see the new “newdocs” folder, and if you open the index.html you should see a familiar set of Ext JS docs.

So what did we actually do here? The first part – “jsduck” – is the command to be executed. The second – “src” – is the folder we want JSDuck to analyse and parse. Lastly we specify the output folder by using the “–output” argument.

In this example we are pointing to the framework’s source code folder but for your own application you would point to your application’s “app” folder or, if you wanted to include the Ext JS docs in your documentation the folder above so your app folder and the Ext JS source are both parsed.

There are various other arguments that can be added to this basic command which we will introduce later in the series.

Our Sample Application

Now that we can generate our documentation we can start to add comments to our own application’s code which will then be picked up by JSDuck and included in our documentation. We will be using a simple application as the basis of our demonstration. The code for this application can be found on GitHub.

The application consists of the following classes and components and is extremely trivial and contrived:
- a Person model
- a People store
- a People controller
- a PeopleDataView

The app simply creates and shows the PeopleDataView which displays the contents of the People stor, displaying each person’s Name and Date Of Birth. It will also, optionally, colour the background the Person’s Favourite Colour. The functionality of the app is irrelevant – as long as we have a few methods, config options and events to document!

Whenever we say we are building the documentation we are using the following command (from our root project folder) – unless otherwise stated! This will generate our documentation into a “docs” folder within our project.

jsduck JSDuckDemo --output docs

If you run this command now and take a look at the output you will see an empty documentation app.

Commenting you Source Code

Now we have a small app to document we will get stuck in!

Classes

We will start by adding comments to each of our classes so they are recognised by JSDuck. We are using the standard Ext.define class syntax so we don’t have to worry about explicitly telling JSDuck what our class is called, what it extends etc – JSDuck already knows!

As a demonstration we will add the following comment to the top of our JSDuckDemo.model.Person class and then regenerate the documentation.

/**
 * Holds data about a Person.
 */
Ext.define('JSDuckDemo.model.Person', {
    ...
});

Once regenerated we will see the Person model class appear in the documentation – something similar to the screenshot below:

You will also notice that the Person model’s documentation page references the class’ inheritance hierarchy and includes all of the config options, methods and events that these classes bring.

The content of our comment is displayed in the header of the class’ documentation page.

We will add similar comments to each of the other classes and regenerate our documentation so we have the following structure in our docs:

Config Options

As you will have seen from the main framework’s documentation each class has various ‘config’ options that allow users to customise the components. We will first look at how to annotate the config options in our application.

Our app has one config option – the useFavouriteColour config found in the JSDuckDemo.view.PeopleDataView component. This config accepts a boolean value and decides whether or not the background of each Person row will be coloured.

We can annotate this with the following comment:

/**
 * @cfg {Boolean} useFavouriteColour This option determines whether the Person's details
 * will use their FavouriteColour as the background.
 */
 useFavouriteColour: true

So let’s look at each part:

@cfg – This part tells JSDuck that the following property is a Config option and so will be filed under the “Config” section.

{Boolean} – We put the config option’s type within curly braces after the @cfg. This could be a simple type such as String, Date, Boolean, Number or an Ext or application class such as Ext.data.Store or JSDuckDemo.store.People.

useFavouriteColour – This is the name of the config option and should match the property’s name in the code.

<text> – After the config’s name we can describe what the option does and how to use it.

With this comment in place if we regenerate our docs we will see a new item in the “config” dropdown and an entry that contains all the details we added:

For the observant among you, you will notice that we automatically get documentation entries for a “getUseFavouriteColour” and “setUseFavouriteColour” method. This is because the useFavouriteColour property is nested in the “config” property.

Methods

We document methods in a very similar way, by annotating the code with structured comments which will later be parsed.

We have added a custom method to the Person model class called “getAge” which returns the Person’s age, in years. It includes a parameter that will optionally return their age with decimal precision. We will document this by adding the following comment:

/**
 * Returns the Person's age in years.
 * @param {Boolean} noRounding If true this will return the value as a decimal with no rounding. If false the value with be rounded to the nearest year.
 * @return {Number} The Person's age
 */
getAge: function(noRounding){
    ...
}

The first sentence provides the docs with the description of the method and what it does.

Secondly we use the “@param” flag to describe the parameters that the method accepts. In a similar manner to the Config option we define the type the parameter expects, within curly brackets. We then add the parameter’s name which should match the name in the code. Finally we describe the parameter and what the value means and does.

We can include as many @param items as we like and, if the parameter expects multiple types these can be included by separating them with a slash, e.g. {Boolean/String}.

In our example we really want the “noRounding” parameter to be optional so it defaults to false to give a round number. We can do this by changing the way we write the parameter’s name. If we wrap it in square brackets and provide a default value, this will document the parameter as optional. For example, we might change it to:

* @param {Boolean} [noRounding=false] If true this will return the value as a decimal with no rounding. If false the value with be rounded to the nearest year.

The next flag we use is the “@return” which describes the data type that the method returns to us. If no value is returned we can use the “{void}” type.

When we regnerate the docs we see our method included with our comments and parameters.

If your method is private we can add the “@private” flag to it which will mark it as private and only display it in the docs when the user has checked the “private” box.

Events

Events are another major thing that must be documented. In our PeopleDataView component we have added a custom event called ‘personclick’ that will fire when a PersonDataView row is clicked. The event will pass the DataView and the Person record to any handler functions.

We document events by adding familiar looking comment to the class. This comment is usually added above the event’s inclusion in the call to the “addEvents” method but can be included anywhere in your class.

/**
 * @event personclick Fires when a Person row is clicked
 * @param {JSDuckDemo.view.PeopleDataView} view The PeopleDataView that raised the event
 * @param {JSDuckDemo.model.Person} record The Person record that was clicked
 */
'personclick'

The “@event” flag marks this comment as describing an event. We follow the flag by the event’s name and a description of the event and when it is fired.

We describe each of the event’s parameters in an identical way as we did with the methods. Notice the way we reference the custom types.

When we regenerate our docs we will see a new item in the events dropdown and an entry containing our documentation.

Notice how our parameters’ types are automatically linked to the relavant class’ documentation making it extremely easy for people to follow what types are expected.

Properties

Properties are the final item we’re going to discuss. We will add a property to our PeopleDataView class to keep track of whether the useFavouriteColour has been manually updated. In our updateUseFavouriteColour method we assign a boolean value to the property useFavouriteColourUpdated. To document this we add the following comments above this statement.

/**
 * @property {Boolean} useFavouriteColourUpdated True if the useFavouriteColour configuration has been updated since init
 */
this.useFavouriteColourUpdated = true;

When we regenerate this we can see the property in our documentation.

Conclusion

We’ve covered quite a few things in this post, namely how to:

• install JSDuck
• generate documentation using JSDuck
• Annotate your configs, methods, events and properties with JSDuck-parseable comments

Armed with this knowledge there is now no excuse for your project not to have good, navigable and up to date documentation! With the command line tools it is ridiculously easy to include documentation building in your build process so your project’s docs are never out of date.

There are a lot more features of JSDuck that we haven’t gone into here so we will continue looking into JSDuck in future blog posts.]]> http://www.swarmonline.com/2013/02/documenting-your-sencha-apps-with-jsduck/feed/ 2 http://www.swarmonline.com/2013/02/localising-sencha-touch-and-ext-js-applications-with-ux-locale-manager/ http://www.swarmonline.com/2013/02/localising-sencha-touch-and-ext-js-applications-with-ux-locale-manager/#comments Tue, 19 Feb 2013 05:00:10 +0000 Stuart http://www.swarmonline.com/?p=1589 Using the Ux.locale.Manager extension

This blog post is going to discuss how to use the excellent Ux.locale.Manager extension (created by Sencha’s Mitchell Simoens) which allows us to easily integrate localisation into our Sencha Touch and Ext JS applications.

We will focus primarily on Sencha Touch in this tutorial but the principles and techniques can equally be applied to Ext JS 4 projects without too many tweaks.

By the end of the article we should have achieved the following:

• Integrated the extension with a blank Sencha Touch project.
• Explained the configuration options available.
• Demonstrated its use with an example
• Created our own overrides to customise it further
• Dealt with more complex situations such as DataViews

And if you’re still awake by the end then please leave a comment if you have any questions, comments or, heaven forbid, corrections!

Extension Purpose & Anatomy

As I’m sure you are aware the purpose of this extension is to allow an entire application to be localised to any language. It does this by loading in external locale files containing all string literals that need to be used. The components that use these strings are then located and updated to the loaded value.

The extension is made up of a Manager class, which is responsible for coordinating the updates and loading of the locale files, and the component overrides. These overrides define a setLocale method which processes the keys provided and updates the component’s markup with the translated value. The base Ext.Component also has an override to its constructor so this translation and replacement occurs when new components are created.

Creating a Blank Project

We’ll start by creating a blank Sencha Touch project structure using Sencha Cmd which does all the heavy lifting for us. If you prefer to create your projects manually or if you have an existing project you want to work with then that’s fine – just be sure you have the auto-loading mechanism working as we will make use of it throughout.

We will create our new project using the following command from inside a Sencha Touch 2.1 SDK directory.

Once this is complete you should have a project structure similar to the one in the screenshot below.

If you’re in a rush then you can download the blank project structure and save a bit of time!

Integrating the Extension

Now we have our plain vanilla project we can now start integrating the extension. We’ll start by getting all the right files into our project, then move on to how we integrate it with our code so the extension is loaded.

Importing the extension

We’ll first need to grab the source from its GitHub repository by downloading its source as a zip or by cloning the entire repository.

Once we have a local copy of the extension’s source we can paste the “Ux” folder into the “touch/src/ux“ folder within our project. We place it here so the Ext.Loader class can easily locate it and pull in all the classes we need when loading and building our application.

Our new project structure should resemble the following screenshot:

Autoloading the extension

Our next step is to reference the extension in our code so it is loaded and available to us.

We start by setting up an Ext.Loader path at the start of our app.js file. We update the existing Ext.Loader.setPath call’s object parameter with an additional key/value pair.

This code instructs Sencha Touch to look for any classes we reference with a root namespace of “Ux“ to be loaded from the folder we copied in during the previous step.

Next we add all of the Sencha Touch locale overrides, and the Manager itself, to the requires array in the Ext.application setup. This will ensure they are loaded when the application starts and so our components can take advantage of their functionality.

The Ext.application call in app.js should now look like the following:

Ext.application({
name: ‘LocaleManagerTutorial’,

requires: [
'Ext.MessageBox',

'Ux.locale.Manager',
'Ux.locale.override.st.Component',
'Ux.locale.override.st.Button',
'Ux.locale.override.st.Container',
'Ux.locale.override.st.TitleBar',
'Ux.locale.override.st.field.Field',
'Ux.locale.override.st.field.DatePicker',
'Ux.locale.override.st.form.FieldSet',
'Ux.locale.override.st.picker.Picker',
'Ux.locale.override.st.picker.Date'

]

// ommitted for brevity
});
[/javascript]

If you now load your sample application you should be able to open the Developer Tools and type “Ux.locale.Manager“, hit enter and see it returns an object. This means it’s all loaded and we’re ready to go!

Initialising and Configuring

After taking a moment to bask in our success of getting the extension integrated with our project we can move onto the real work – initialising and configuring it!

Before we start we’re going to go ahead and remove everything from the launch function within our app.js except the line that destroys the loading indicator. We are going to work from a clean slate so we’ll throw away the example code for now:

Before we initialise the extension we must call its setConfig method to configure it with any options we want. For the majority of cases we won’t need to change the default values but it’s good to include it so we can make changes when we need to. To do this we add the following snippet to the start of the launch method:

So let’s go through what each of these actually do:

• ajaxConfig – this object allows us to configure the AJAX request that is sent to retrieve the locale’s data. This can take any of the standard Ext.Ajax.request options. It is important to note that if you include a url or callback option in this object it will be overridden by the extension.
• language – this defines the default language to load when the extension is initialised. This value will be combined with the tpl value to produce the URL the locale is loaded from.
• tpl – we can customise the location that our locales are loaded from by editing this value. The locale (initially based on the language config) is injected into the string before loading. You could change this, for example, to load from a PHP page by providing the following tpl value: ‘../locales/getLocaleData.php?language={locale}’
• type – this will be used to switch the method that the locale data is loaded by. At the moment only AJAX is supported but loading via a script tag is in the future plans.

Once we have set any configuration options we want we can call the Manager’s init method and the extension will get to work and load our locale file and customise each component that is configured to be. We call this just after the setConfig call so our launch method looks like this:

Ux.locale.Manager.init();
[/javascript]

If you run your application now you will see a nasty console error telling us that there is no such file as en.json! We will follow the default structure and create a locales folder in the main project folder. We will then create a JSON file named en.json and populate it with an empty object.

Running your application now should result in a nice empty screen and no console errors. If you take a look in your Network tab and filter by “XHR” you will see our en.json file being loaded.

Before we go any further we’ll create a second locale file and demonstrate how to switch between locales. Create a second JSON file in the locales folder called fr.json and populate it with an empty object.

If we reload our application, open the console and type the following then hit enter:

We should see a flash of load mask and if you look in the Network tab once more you should see the fr.jsonfile being loaded in – perfect!

We’ll demonstrate what this is actually means in the next section so keep reading!

Simple Usage

By now you’ll be itching to get something localised so your app has instant international appeal, so let’s get to it!

We’re going to start by creating a simple Ext.field.Text (purely because it has multiple things we can localise!); localise its label and placeHolder values and then add it to a Container in the Viewport. We’ll start by defining our localised strings in our en.json and fr.json files. Update the files with the following:

en.json

fr.json

We can now create the textfield that these translations will become part of. We will simply create a new Ext.field.Text in the launch method within app.js.

// wrap in container so it doesn’t get stretched
Ext.Viewport.add({
xtype: ‘container’,
items: [field] });
[/javascript]

If we reload our app we can see the field with its label and placeHolder displayed in English with no way to change it to French (or German, or Spanish etc etc).

Finally we’ve got to the bit where the magic happens that we’ve been building to since the start of the article… We update the field’s configuration to remove the hard-coded English values and instead use a locales config option to define the “dot-notation” path to the required string in our JSON language files for each property. You can see this in the code below:

If we now reload our application – what do we see? Exactly the same thing? Hopefully! The field looks the same but its label and placeHolder values are coming from our locale file rather than the hard-coded values we had before.

You’ll remember in the last section we updated the locale to French using the following code:

If we do the same now we will see the benefits of using this extension immediately. The app is now in French! C’est très bien!

An Explanation

So what did we just do here?

Our JSON locale files can contain any depth of nested objects that are referenced using the standard dot-notation within the extension. These items should be used to populate any string literal within your application.

We applied them to our TextField component by using the locales configuration option. When a new locale is loaded the extension locates all of the existing components that have this option set (using ComponentQuery) and, if it exists in one of the included overrides, calls the setLocale method of that component. Within this method each of the defined options are looked up against the current locale file (using the dot-notation string we provided) and then updates it using the property’s setter method.

Filling in the blanks

Occasionally you might find that the extension’s overrides aren’t sufficient for the components you are using and you need to create your own. This is very easy and, by following the pattern the existing ones do, we can create our own.

A Scenario

Imagine you have a Select Field with a series of options (we’ll use colours as an example) and we want these to be translated in the same way the field’s label is. Unfortunately that functionality isn’t covered by the built in overrides so we’ll describe how we can achieve this by creating our own.

We begin by creating a simple SelectField with our colour options and adding it to our Viewport container.

Ext.Viewport.add({
xtype: ‘container’,
items: [field, selectField] });
[/javascript]

The Ext.field.Select component extends from the base Ext.field.Field class and so inherits the label localisation defined there but it doesn’t have any localisation of its own. We will create a new override in the extension’s folder.

We then create a basic override for the Select field and include a simple setLocale method copied from another override to get us started. We have added an options variable which picks up the options config of the locales object. We will use this to localise the field’s options.

requires : [
'Ux.locale.override.st.field.Field'
],

setLocale : function(locale) {
var me = this,
locales = me.locales || me.getInitialConfig().locales,
options = locales.options,
manager = me.locale;

me.callParent(arguments);
}
});
[/javascript]

Now we must perform the actual localisation of the Select field’s options. We do this by first checking that the options have been specified for localisation (we might not want to localise them in every select field). Once we’re happy it has been defined we can lookup the options’ value using the Ux.locale.Manager’s get method and then pass the result of this into the Select field’s setOptions method.

requires : [
'Ux.locale.override.st.field.Field'
],

setLocale : function(locale) {
var me = this,
locales = me.locales || me.getInitialConfig().locales,
options = locales.options,
manager = me.locale;

if(options){
options = manager.get(options, []);

this.setOptions(options);
}

me.callParent(arguments);
}
});
[/javascript]

We must now go back to our app.js file and add a reference to this new override to the require config option.

'Ux.locale.Manager',
'Ux.locale.override.st.Component',
'Ux.locale.override.st.Button',
'Ux.locale.override.st.Container',
'Ux.locale.override.st.TitleBar',
'Ux.locale.override.st.field.Field',
'Ux.locale.override.st.field.DatePicker',
'Ux.locale.override.st.form.FieldSet',
'Ux.locale.override.st.picker.Picker',
'Ux.locale.override.st.picker.Date',
'Ux.locale.override.st.field.Select'
] …
[/javascript]

Finally we add our options to our English and French locale files and update our SelectField’s configuration to include an options config in the locales object.

app.js

en.json

"SelectField1": {
"label" : "Colour:",
"options": [{
"name": "Blue",
"value": "Blue"
}, {
"name": "Red",
"value": "Red"
}, {
"name": "Green",
"value": "Green"
}] }
}
[/javascript]

fr.json

"SelectField1": {
"label" : "Coleur:",
"options": [{
"name": "Bleu",
"value": "Bleu"
}, {
"name": "Rouge",
"value": "Rouge"
}, {
"name": "Vert",
"value": "Vert"
}] }
}
[/javascript]

You can now reload your app and call the updateLocale method to switch languages and see the options change.

Dealing with DataViews

DataViews (and Lists of course) are a slightly trickier customer with regards to localisation using this approach because they don’t quite follow the same rules. The most common scenario is that the DataView’s template includes string literals in the form of labels which, unfortunately, don’t have a built in setter for as they are embedded in the view’s generated HTML. This section is going to explain one approach for overcoming this problem.

First we’ll create a quick DataView to demonstrate our problem and to use with our solution. In this example we must create a class extending the Ext.DataView component so we can add custom methods to it. We create a new file in the view folder called MyDataView.js and add it to the require option in our app.js. We can then instantiate it in the launch method, adding to the Viewport’s child container

view/MyDataView.js

extend: ‘Ext.DataView’,

alias: ‘widget.mydataview’,

config: {
height: 500,
itemTpl: ‘Name: {name}’,
store: Ext.create(‘Ext.data.Store’, {
fields: ['name'],
data: [{name: 'Stuart'}, {name: 'Andrew'}] })
}
});
[/javascript]

app.js

app.js launch method

We should now have a dataview in our Viewport but unfortunately the “Name” labels are hardcoded to their English translation. So how do we fix this?

We start by adding a method to the MyDataView class called getStringLiterals – we will use this to look up and return all string literals used in the template. In our case we only have one but you could return many key/value pairs in the returned object.

Next we must override the prepareData method which is used to process each records before sending it to be rendered. We can hijack this method and use it to merge the string literals (returned from the getStringLiterals method) with the data object being sent to the template.

return Ext.apply(data, this.getStringLiterals());
}
…
[/javascript]

We start by calling the original prepareData method so we don’t alter its functionality and then we merge the translated data with the data object. Now we have a nameLabel property in our data being passed to the template so we can replace the hardcoded “Name:” value with a placeholder for the “nameLabel”
property.

Finally we must add the translations to our en.json and fr.json files otherwise the DataView won’t display a label.

Our labels are now coming from our locale file but you’ll notice that it doesn’t get updated when we call the updateLocale method. We now need to fill in the blank and create an override for the DataView class to perform a refresh of the view when the locale is changed.

We do this in the same way as before by creating a DataView.js file in the “src/ux/Ux/locale/override/st“ with the following code to perform the refresh.

Ux/locale/override/st/DataView.js

requires : [
'Ux.locale.override.st.Component'
],

setLocale : function(locale) {
var me = this,
locales = me.locales || me.getInitialConfig().locales,
manager = me.locale;

me.callParent(arguments);

me.refresh();
}
});
[/javascript]

We must also add this class to the require config in the app.js file.

app.js

Lastly, we must tell the Locale Manager that we want the MyDataView to be localised so we must add the enableLocale and a blank locales (a quirk of the extension) to the config.

Once we have done that we can refresh our app and switch the locales and see the dataview refresh itself with the new localised labels being merged into the template.

Phew! We made it!

Hopefully you have seen just how easy it is to integrate localisation with your Sencha Touch and Ext JS applications with this excellent extension and how it can be customised and extended further to suit your needs.

Please let us know what you think below, if you have any comments, questions or corrections – we’d be happy to hear from you!

2013 is looking to be a very exciting year for SwarmOnline and we would like to thank all of our previous and current clients for making this possible. We have many new things in the pipeline and hope to be able to share these with you all very soon!

For now, enjoy the website and please don’t hesitate to get in touch if you want to discuss your project or if you have any questions!

- info@swarmonline.com]]> http://www.swarmonline.com/2013/02/announcing-swarmonlines-new-website/feed/ 0 http://www.swarmonline.com/2012/12/constructing-a-complex-form-layout-with-ext-js-4/ http://www.swarmonline.com/2012/12/constructing-a-complex-form-layout-with-ext-js-4/#comments Mon, 10 Dec 2012 20:23:22 +0000 Andrew Duncan http://www.swarmonline.com/?p=1541

Ext JS 4 takes a different approach and utilizes the Ext.form.Labelable mixin, which allows form fields to be decorated with labels and error messages without requiring a specific layout to be applied to the container. This means we can combine all of the layout types the framework has to offer (which are discussed in detail in Chapter 3, Laying Out your Components) without having to overnest components in order to satisfy the form field’s layout requirements.

We will describe how to create a complex form using multiple, nested layouts and demonstrate how easy it is to get a form to look exactly as we want. Our example will take the structure of a Support Ticket Request form and, once we are finished, it will look like the following screenshot:

How to do it…

1. We start this recipe by creating a simple form panel that will contain all of the layout containers and their fields:

2. Now, we will create our first set of fields—the FirstName and LastName fields. These will be wrapped in an Ext.container.Container component, which is given an hbox layout so our fields appear next to each other on one line:

3. We have added a CSS class (field-margin) to each field, to provide some spacing between them. We can now add this style inside <style> tags in the head of our document:

4. Next, we create a container with a column layout to position our e-mail address and telephone number fields. We nest our telephone number fields in an Ext.form.FieldContainer class, which we will discuss later in the recipe:

5. The text area and checkbox group are created and laid out in a similar way to the previous sets, by using an hbox layout:

6.Finally, we add the last field, which is a file upload field, to allow users to provide attachments:

All together now…

This code snippet is a concatenation of the above seven steps.

1. Constructing a complex form layout
<!– Library Files –>
<script type="text/javascript" src="../../ext-all-debug.js"></script><script type="text/javascript">// <![CDATA[
Ext.onReady(function(){

var formPanel = Ext.create('Ext.form.Panel', {
title: 'Support Ticket Request',
width: 650,
height: 500,
renderTo: Ext.getBody(),
style: 'margin: 50px', // move panel off browser's edge
items: [{
xtype: 'container',
layout: 'hbox',
items: [{
xtype: 'textfield',
fieldLabel: 'First Name',
name: 'FirstName',
labelAlign: 'top',
cls: 'field-margin',
flex: 1
}, {
xtype: 'textfield',
fieldLabel: 'Last Name',
name: 'LastName',
labelAlign: 'top',
cls: 'field-margin',
flex: 1
}] }, {
xtype: ‘container’,
layout: ‘column’,
items: [{
xtype: 'textfield',
fieldLabel: 'Email Address',
name: 'EmailAddress',
labelAlign: 'top',
cls: 'field-margin',
columnWidth: 0.6
}, {
xtype: 'fieldcontainer',
layout: 'hbox',
fieldLabel: 'Tel. Number',
labelAlign: 'top',
cls: 'field-margin',
columnWidth: 0.4,
items: [{
xtype: 'textfield',
name: 'TelNumberCode',
style: 'margin-right: 5px;',
flex: 2
}, {
xtype: 'textfield',
name: 'TelNumber',
flex: 4
}] }] }, {
xtype: ‘container’,
layout: ‘hbox’,
items: [{
xtype: 'textarea',
fieldLabel: 'Request Details',
name: 'RequestDetails',
labelAlign: 'top',
cls: 'field-margin',
height: 250,
flex: 2
}, {
xtype: 'checkboxgroup',
name: 'RequestType',
fieldLabel: 'Request Type',
labelAlign: 'top',
columns: 1,
cls: 'field-margin',
vertical: true,
items: [{
boxLabel: 'Type 1',
name: 'type1',
inputValue: '1'
}, {
boxLabel: 'Type 2',
name: 'type2',
inputValue: '2'
}, {
boxLabel: 'Type 3',
name: 'type3',
inputValue: '3'
}, {
boxLabel: 'Type 4',
name: 'type4',
inputValue: '4'
}, {
boxLabel: 'Type 5',
name: 'type5',
inputValue: '5'
}, {
boxLabel: 'Type 6',
name: 'type6',
inputValue: '6'
}],
flex: 1
}] }, {
xtype: ‘filefield’,
cls: ‘field-margin’,
fieldLabel: ‘Attachment’,
width: 300
}] });

});

// ]]></script>

How it works…

All Ext JS form fields inherit from the base Ext.Component class and so can be included in all of the framework’s layouts. For this reason, we can include form fields as children of containers with layouts (such as hbox and column layouts) and their position and size will be calculated accordingly.

The Ext.form.FieldContainer class used in Step 3 is a special component that allows us to combine multiple fields into a single container, which also implements the Ext.form.Labelable mixin. This allows the container itself to display its own label that applies to all of its child fields while also giving us the opportunity to configure a layout for its child components.]]> http://www.swarmonline.com/2012/12/constructing-a-complex-form-layout-with-ext-js-4/feed/ 0 http://www.swarmonline.com/2012/09/cook-up-some-ext-js-4-recipes-for-free-this-weekend/ http://www.swarmonline.com/2012/09/cook-up-some-ext-js-4-recipes-for-free-this-weekend/#comments Fri, 28 Sep 2012 10:18:09 +0000 Andrew Duncan http://www.swarmonline.com/?p=1566 Ext JS 4 Web Application Development Cookbook which we released last month!

You’ll need to hurry because the offer is only available from 28-30th September 2012.

Click http://bit.ly/RXnAMc to for more information and start building apps with Sencha’s Ext JS 4 Framework today!

Official Statement from Packt Publishing:

28^th September 2012

Packt Publishing reaches 1000 IT titles and celebrates with an open invitation

Birmingham-based IT publisher Packt Publishing is about to publish its 1000^th title. Packt books are renowned among developers for being uniquely practical and focused, but you’d be forgiven for not yet being in the know – Packt books cover highly specific tools and technologies which you might not expect to see a high quality book on.

Packt is certain that in its 1000 titles there is at least one book that everyone in IT will find useful right away, and are inviting anyone to choose and download any one of its eBooks for free over its celebration weekend of 28-30^th Sep 2012. Packt is also opening its online library for a week for free to give customers an easy to way to research their choice of free eBook.

Packt supports many of the Open Source projects covered by its books through a project royalty donation, which has contributed over $400,000 to Open Source projects up to now. As part of the celebration Packt is allocating $30,000 to share between projects and authors as part of the weekend giveaway, allocated based on the number of copies of each title downloaded.

Dave Maclean, founder of Packt Publishing:

“At Packt we set out 8 years ago to bring practical, up to date and easy to use technical books to the specialist tools and technologies that had been largely overlooked by IT publishers. Today, I am really proud that with our authors and partners we have been able to make useful books available on over 1000 topics and make our contribution to the development community.”]]> http://www.swarmonline.com/2012/09/cook-up-some-ext-js-4-recipes-for-free-this-weekend/feed/ 0 http://www.swarmonline.com/2012/08/ext-js-4-web-application-development-cookbook-released/ http://www.swarmonline.com/2012/08/ext-js-4-web-application-development-cookbook-released/#comments Fri, 31 Aug 2012 08:11:15 +0000 Andrew Duncan http://www.swarmonline.com/?p=1528 It gives the two of us great pleasure to announce the release of our writing efforts over the past year.

Packed with over 100 easy to follow recipes which demonstrate, through real life examples, numerous features of Ext JS 4. This book will help you create anything from basic components to advanced web applications using Sencha’s unrivalled Ext JS framework.

Sample Chapter

Packt Publishing have made available a chapter of the book which you can download for free. Chapter 5 – Loading, Submitting and Validating Forms explores the topic of forms with Ext JS 4. We begin the chapter by creating a support-ticket form in the first recipe which we use throughout.

Instead of focusing on how to configure specific fields (see Chapter 6), we demonstrate more generic tasks for working with forms. Specifically, these are populating forms, submitting forms, performing client-side validation, and handling callbacks/exceptions.

Download the sample chapter directly from Packt Publishing.

Additional Content

In addition to the content in the book we have prepared an appendix with a further 20 recipes!

“Ext JS 4 Cookbook – Exploring Further” takes a look at a range of other useful topics that we weren’t able to fit in the book. Here we cover:

1. Creating your Applications Folder Structure
2. Encoding & Decoding HTML Strings
3. Detecting Available Browser Features
4. Evaluating Object Types and Values
5. Presenting Tabular Data with the TableLayout
6. Absolutely Positioning Components
7. Positioning Panel Headers
8. Animated filtering of a DataView
9. Specifying a form field’s length limits
10. Displaying validation alerts to the User
11. Dynamically generate forms from loaded JSON
12. Positioning Field Labels
13. Configuring a grid from MetaData
14. Combining several Chart types into one
15. Displaying detailed information when hovering over charts
16. Persisting User Interface State
17. Retaining support for the browser back button
18. Using Ext Direct with Grids
19. Handling Exceptions with Ext Direct
20. Handling session timeouts with a TaskManager

Synopsis

Ext JS 4 is Sencha’s latest JavaScript framework for developing cross-platform web applications. Built upon web standards, Ext JS provides a comprehensive library of user interface widgets and data manipulation classes to turbo-charge your application’s development. Ext JS 4 builds on Ext JS 3, introducing a number of new widgets and features including the popular MVC architecture, easily customisable themes and plugin-free charting.

Ext JS 4 Web Application Development Cookbook works through the framework from the fundamentals to advanced features and application design. More than 130 detailed and practical recipes demonstrate all of the key widgets and features the framework has to offer. With this book, and the Ext JS framework, learn how to develop truly interactive and responsive web applications.

Starting with the framework fundamentals, you will work through all of the widgets and features the framework has to offer, finishing with extensive coverage of application design and code structure.

Over 130 practical and detailed recipes describe how to create and work with forms, grids, data views, and charts. You will also learn about the best practices for structuring and designing your application and how to deal with storing and manipulating data. The cookbook structure is such that you may read the recipes in any order.

The Ext JS 4 Web Application Development Cookbook will provide you with the knowledge to create interactive and responsive web applications, using real life examples.

What you will learn from this book :

• Structure your application according to best practices, manipulate the DOM, and handle events raised by users and the framework
• Learn the layouts available in Ext JS and understand how to combine these to make complex layouts
• Create aesthetic and user-friendly forms, validate these on the client, and submit data to your server
• Present and organize data with Trees, Tabbed layouts, Data Views, and Templates
• Make AJAX requests, model data objects, incorporate Ext.Direct, perform CRUD operations on data, and integrate HTML5 local storage with Ext JS
• Work with Grids to present and manipulate tabular data by editing rows, dragging and dropping records, scrolling infinitely, and grouping data
• Represent data visually with flexible and interactive Charts and Drawing components
• Customize the look and feel of your application with SASS and Compass
<]]> http://www.swarmonline.com/2012/08/ext-js-4-web-application-development-cookbook-released/feed/ 1