But we’ll start with developing a Hello World application before explaining how things work in Ext JS. But the section where we’ll review the code of the Save Sick Child application will serve as a hands-on way of learning the framework. You’ll read the code fragments followed by brief explanations. You’ll be able to run and debug this application on your own computer seeing how various components and program layers work in practice. But first things first - let’s create a couple of versions of Hello World.

Create a new directory (e.g. hello1). Inside hello1 create a subdirectory named ext and copy there the entire content of your Ext JS installation directory. Create yet another subdirectory app inside hello1 - this is where your application JavaScript files will go.

At the very minimum, every Ext JS application will contain one HTML and one JavaScript file - usually index.html and app.js. The file index.html will include the references to the CSS and JavaScript code of Ext JS and will include your app.js containing the code of the Hello World application:

The next comes the content of the app.js that you should place in the app directory of your project. This is how the app.js may look like:

This Ext.application() method gets a configuration object - JavaScript literal - with configured launch method that’s called automatically when the Web page has completely loaded. In our case it mandates to launch the anonymous function that displays the "Hello World" message. In Ext JS you’ll be using such configuration objects a lot.

Open the file index.html in your Web browser and you’ll see this greeting. But this was a plain vanilla Hello World. In the next section we’ll automate the process of creation of a fancier Hello World (or the initial version of any other application) by using the Sencha Cmd tool.

In the pre 4.0 versions ofExt JS you’d be invoking the Ext.onReady() method instead of passing the configuration object with the launch config option.

Providing a function argument as a configuration object overrides configurable properties of the current instance of the class. This is different from the class properties, which are defines at the prototype level and changing a values of a property would apply to all instances of the class. When you’ll be reading Ext JS online documentation for any class, you’ll three three categories of class elements: Configs, Properties, and Methods. For example, this is how you can create a panel passing configs:

In this example we are creating an instance of the panel usinc configuration object with three config options: title, width, and html. The values of these properties will be assigned to the corresponding properties of this instance only. If you’ll read documentation for Ext.panel.Panel, you’ll find 116 available configs that you can set on the panel instance.

In the next section we’ll automate the process of creating of Hello World application and will see another example of the configuration object.

Sencha CMD is a handy command line tool that automates your work starting from scaffolding your application to minimizing, packaging and deploying it.

Download Sencha CMD from http://www.sencha.com/products/sencha-cmd/download. Run the installer, and when it’s complete, open the Terminal or Command window and enter the command sencha - you should see a prompt with all possible commands and options that CMD understands.

For example, to generate the initial project structure for HelloWorld application enter the following command, specifying the absolute path to your ExtJS SDK directory (we keep it in the /Library directory) and to the output folder, where the generated project should reside.

sencha -sdk /Library/ext-4.2 generate app HelloWorld /Users/yfain11/hello

After the code generation was complete, it created the folder hello of the structure shown in CMD-generated project.

The generated project is created with the assumption that your application will be built using the MVC paradigm discussed in the section Best Practice:MVC. The JavaScript is located in the app folder, which includes the view subfolder with the visual portion of your application, the controller folder with controller classes, and the model is for data. The ext folder contains multiple distributions of the Ext JS framework. The sass folder is a place for your application’s CSS files (see the sidebar titled SASS and CSS later in this chapter).

The entry point to your application is index.html, which contains the references to the main application file app.js, the Ext JS framework extdev-js, the CSS file bootstrap.css (imports the classic theme), and the supporting script bootstrap.js, which contains the mapping of the long names if the framework and application classes to their shorter names (xtypes).

The content of the generated app.js is shown next. This script just calls the method Ext.application() passing as an argument configuration object that specifies the application name, and the names of the classes that play roles of views and controller. We’ll go into details a bit later, but at this point let’s concentrate on the big picture.

Finally, if you’ll open index.html in your Web browser, you’ll see our Hello World initial Web page that looks as in [Fig6-2]. This view uses so called border layout and shows a panel on the west and a tabpanel in the central region of the view.

The total size of this version of the Hello World application is pretty large: 4Mb, and the browser makes 173 requests to the server by the time the user sees the application shown on Running the Generated Application. But Sencha Cmd knows how to build the production version of the Ext JS application. It minimizes and merges the application’s and required framework’s JavaScript code into one file. The application css file is also minimized and the references to the image resources become relative hence shorter. Besides, the images may be automatically sliced - cut into smaller rectangular pieces that can be downloaded by the browser simultaneously.

To create optimized version of your application go to the Terminal or a command window and change to the root directory of your application (in our case it’s /Users/yfain11/hello) and run the following command:

sencha app build

After the build is finished, you’ll see newly generated version of the application in the directory build/HelloWorld/production. Open the file index.html while running Chrome Developers Tools, and you’ll see that the total size of the application is substantially lower (about 900Kb) and the the browser had to make only five requests to the server (see Running production version of HelloWorld). Using gZip will reduce the size of this application to 600Kb, which is still a lot, but Ext JS framework is not the right choice for writing Hello World type of applications or light Web sites.

Later in this chapter we’ll use Sencha CMD tool again in the section "Building Production Version" to create an optimized version of the Save Sick Child application.

In this chapter we’ll switch from Aptana IDE to its parent Eclipse IDE. Although Eclipse is not the best IDE for JavaScript developers, but it’s the most popular IDE among enterprise Java developers, and we’ll need it later in this chapter to demonstrate the application generation using Java and CDB. Besides, Sencha offers Eclipse plugin (not covered in the book) for those who purchased a license of Sencha Complete .

We’ll use two IDEs in this chapter: Eclipse and WebStorm. In particular, we’ll use the version "Eclipse IDE for Java EE developers", which is the most popular IDE among enterprise Java developers. It’s available free of charge at Eclipse Downloads site. The installation comes down to unzipping of the downloaded archive. Then double-click on the Eclipse executable, and you’ll see the workbench that looks very similar to Aptana.

But in our opinion, the best IDE for JavaScript developers (regardless of which framework they use) is JetBrain’s WebStorm IDE. Later in this chapter we’ll show you how to use WebStorm for developing JavaScript portion of the project even if the Java part has to be developed in Eclipse.

First you need to select the packaging of the Ext JS framework that fits your need. You may select its minimized version to be used in production or a larger and commented version with detailed comments and error messages. Besides, you may select a version of Ext JS that include either all or only the core classes. The third option is to create a custom build of Ext JS that will include only the those framework classes that are used by your application.

The file with the minimized production version of Ext JS is called ext-all.js and its size is pretty large: 1.4Mb. But as we described in the section on Sencha CMD, your can create a build fine tuned to your application . If this application will be used on the high-speed networks and size is not the object, simply add it to your index.html from your local servers or see if Sencha offers the CDN for the Ext JS version you need, which may look similar to the following:

In Chapter 1 we’ve stated that JavaScript doesn’t have classes and that constructor functions were the closest to classes language elements. Ext JS extends the JavaScript language and introduces classes and a special way to define and instantiate them with functions Ext.define() and Ext.create(). Ext JS also allows to extend one class from another using the property extend and define class constructors using the property constructor.

With Ext.define() contains you declare a class declaration, and Ext.create() instantiate it. Basically, define() serves as a template for creation of one or more instances.

Usually the first argument you specify to define() is a fully qualified class name, the second argument is an object literal that contains the class definition. If you use null as the first argument Ext JS creates an anonymous class.

The next class Header has 200 pixel height, uses the hbox layout, has a custom config property logo, extends Ext.panel.Panel:

1. Render this panel to an HTML element with id=content.

2. Defining a custom config property logo.

3. This is a constructor function. In this example it calls the constructor of its superclass Ext.panel.Panel. In general, it’s a good practice to pass the standard JavaScript array arguments in one shot rather than trying to explicitly define each and every parameter.

You can optionally include a third argument for define(), which is a function to be called when the class definition is created. Now you can create one or more instances of the class class, for example:

The values of custom config properties from the config{} section of the class can be reassigned during the class instantiation. For example, the next code snippet will print sony.png for the first instance of the header, and sony_small.png for the second one. Please not that Ext JS automatically generated getters and setters for all config properties, which allowed us to use the method getLogo().

If a class has dependencies on other classes, which must be preloaded, use the requires parameter. For example, the next code snippet shows that the class SSC.view.Viewport requires the Panel and the Column classes. So the Ext JS loader will check if Panel and/or Column was not loaded yet, it’ll dynamically load them first.

Ext.create() is a preferred way of instantiation as it does more than the new operator that is also allowed in Ext JS. But Ext.create() may perform some additional functionality, for example id Ext.Loader is enabled, create() will attempt to synchronously load dependencies (if you haven’t used the option require). But with requires your preloads all dependencies asynchronously in parallel and is a preferred way of specifying dependencies. Besides, the async mode allows loading from different domains, while sync loading doesn’t.

For each class Ext JS creates one instance of special class Ext.Class, which will be shared by all objects instantiated from this class.

Prior to creating a class, Ext JS will run some pre-processors and some post-processors based on the class definition. For example, the class 'SSC.view.Viewport' from the code sample above uses extend: 'Ext.container.Viewport', which will engage the extend pre-processor that will do some background work to properly build a subclass of extend: Viewport. If your class includes the config section, the config preprocessor will be engaged.

While Ext JS doesn’t force you to architect your application based on the MVC paradigm, it’s a really good idea to do so. Earlier in the section on Sencha CMD you’ve seen how this tool generates a project, which separates model, views, controllers and stores into separate directories as in CMD-generated project that depicted the structure of the Hello World project. But later in this chapter we’ll build our Save Sick Child application the same way. Model-View-Controller in Ext JS presents a diagram illustration how the Ext JS application that contains all Model-View-Controller tiers.

• Controller is an object that serves as an intermediary between the data and the views. The data has arrived to your application, and controller has to notify the appropriate view. The user changed the data on the view - the controller should pass the changes to the model (or stores in the Ext JS world). Controller is the place to write event listeners reaction to some important events of your application (e.g. a user clicked on the button). In other words, Controller maps the events to actions to be performed on the data or the view.

• View is a certain portion of the UI that the user sees. The view is populated with the data from the model (or stores).

• Model represents some business entity, e.g. Donor, Campaign, Customer, Order e.t.c. In Ext JS models are access via stores.

• Store contains one or more model instances. Typically, a Model is a separate class that is instantiated by the store object, but in simple cases a store can have the model data embedded in its own class. A store may use more than one model if need be. Both stores and model can communicate with the data feed that in a Web application is usually provided by some server-side data feed.

The application object defines its controllers, views, models, and stores. When the Save Sick Child will be ready, the code of its app.js will look as follows:

The above code is a clean and simple to read/write code helps Ext JS framework in generating additional code required for wiring views, models, controllers and stores together. For better understanding of the rest of this chapter you should read the MVC Architecture section from Ext JS documentation. We don’t want to repeat the content of Sencha product documentation, but rather will be giving you brief descriptions while doing code review of the Save Sick Child application.

In previous versions of our Save Sick Chils application CSS was responsible for all layouts of the UI components. In Chapter 11 you’ll be learning about the responsive design techniques and CSS media queries, which allow to create fluid layouts that automatically adjust to the size of the viewport.

But this section is about Ext JS proprietary way of creating and adding UI components to Web pages. Before the user will see a component, Ext JS framework will go through the following phases for each component:

• Load - load the required (or all) Ext JS classes and their dependencies

• Initialize components when the DOM is ready

• Rendering - convert components to HTML elements

• Layout - measuring and assigning sizes

• Destruction - removing the reference from DOM, removing event listeners and unregistering from the component manager.

Rendering and layout are the most time consuming phases. The rendering does a lot of preparations to give the browser’s rendering engine HTML elements and not Ext JS classes. The layout phase is slow because the calculation of sizes and positions (unless they are in absolute coordinates) and applying of cascading stylesheets takes time. Ext JS 4.1 was redesigned to minimize the number of reflows, which happen when the code reads-measures-writes to the DOM and makes dynamic style modifications. Now a large portion or recalculations is done in a batch before modifying the DOM.

Each Web page consists of one or more containers, which include some children - components (in Ext JS they are subclasses of Ext.Component), for example, Ext.button.Button. If a component can contain other components, it’s a container (e.g. Ext.panel.Panel) and will have Ext.container.Container as one of its ancestors. In Ext JS class hierarchy, Container is a subclass of Component, so all methods and properties defined for a component are available for a container too.

You’ll be defining your container class with as a subclass of a container by including extend: Ext.container.Container. The child elements of a container are accessible via its property items. In the Ext.define() statement of the container you may specify the code that will loop through this items array and, say style the components, but actual instances of the children will be provided during the Ext.create() call via configuration object.

The process of adding a component to a container will typically consist of invoking Ext.create() and specifying in a configuration object where to render the component to, for example renderTo: Ext.getBody().

But under the hood Ext JS will do a lot more work. The framework will auto-generate a unique ID for the component, assign some event listeners, instantiate component plugins if specified, invoke the initComponent(), and add the component to Ext.ComponentManager.

Events in Ext JS are defined in the mixin Ext.util.Observable. Components interested in receiving events can subscribe to them using on of the following methods:

• By calling the method addListener()

• By using the method on().

• Declaratively

The next code snippet shows two different ways of how a combobox can subscribe to the event change. The handler function is a callback that will be invoked if the event change will be dispatched on this combobox:

To unsubscribe from the event call the method removeListener() or its shorter version un():

You can also declarativly subscribe to events using listeners property of the component:

In Chapter 1 you’ve learned about event bubbling. In Ext JS event bubbling mechanism enables events dispatched by components that include Ext.util.Observable bubble up through all enclosing containers. For components it means that you can handle component’s event on container level. It can be handy to subscribe and handle multiple similar events in one place. To enable bubbling for selected events use the enableBubble() method, for example:

To define custom events use the method addEvents(), where you can provide one or more of the custom event names:

For components you have to define custom events inside the initComponent() method. For controllers - inside init(), and for any other class – inside its constructor.

In Ext JS each container has a property items, which stores references to its child components. The container’s property layout controls how its children are laid out inside. If you won’t explicitly set the layout property, its default value is Auto, which is just placing components inside the container top to bottom regardless of the component size.

Usually you’ll be explicitly specifying the layout. For example, the hbox layout would arrange all components inside the container horizontally next to each other, but vbox layout would arrange them vertically. The card layout places the components one under another, but only the top component is visible (think of a tab folder, where the content of only one tab is visible at any given time).

The border layout is often used to arrange the components in the main viewport (a.k.a. home page) of your application. This layout allows you to split the container’s real estate into five imaginary regions: north, east, west, south, and center. If you need to allocate the top menu items, place them to the region north. The footer of the page is in the south as shown in the code sample below.

Then select Eclipse menu File | Import | General | Existing projects into workspace and press the button Next. Then select the option Select archive file and press browse to find SSC_Top_ExJS.zip on your disk. This will import the entire Dynamic Web Project, and most likely you’ll see one error in the Problems view indicating that the target runtime with so-and-so name is not defined. This may happen because the name of the Tomcat configuration in your Eclipse is different from the one in the file SSC_Top_ExJS.zip.

To fix this issue right-click on the project name and select the menu Properties | Targeted runtimes. Then uncheck the Tomcat name that was imported from our archive and check the name of your Tomcat configuration. This action will make the project SSC_Top_ExtJS deployable under your Tomcat server. Right-click on the server name in the Servers view and select Add and Remove menu item. You’ll see a popup window similar to Deploying Dynamic Web Project, which depicts a state when the project SSC_Top_ExtJS is deployed, but SSC_Complete_ExtJS.

Right-click on the project name SSC_Top_ExtJS, select the menu Run as | Run on server. Eclipse may offer to restart the server - accept it, and you’ll see the top portion of the Save Sick Child application running in the internal browser of Eclipse as shown on Running the SSC_Top_ExtJS in Eclipse. You can either configure Eclipse to use your system browser or just enter the URL http://localhost:8080/SSC_Top_ExtJS/ in the browser of your choice - the Web page will look the same.

It’s time for a code review. The initial application was generated by Sencha CMD so the directory structure complies with the MVC paradigm. This version has one controller Donate.js and three views: DonateForm.js, Viewport.js, and Header.js as shown in Controller, views and images of SSC_Top_ExtJS. The images are located under the folder resources.

The app.js is pretty short - it just declares SSC as the application name, views and controllers. By adding the property autoCreateViewport: true we requested the application to automatically load the main window, which must be called Viewport.js and located in the view directory.

In this version of the application controller Donate.js is listening to the events from the view DonateForm. It’s responsible just for the showing and hiding the Donate form panel. We’ve implemented the same behavior as in the previous version of the SaveSick Child application - click on the Donate Now button reveals the donation form. If the application would need to make some AJAX calls to the server, such code would also be placed in the controller. The code of the Donate controller looks as follows:

1. The init() method is invoked only once on instantiation of the controller.

2. The control() method of the controller takes selectors as arguments to find components with the corresponding event listeners to be added. For example, 'button[action=showform]' means "find a button that has a property action with the value `showform`" - it has the same meaning as in CSS selectors.

3. Event handler functions to process show, hide, and submit events.

4. In containers with card layout, you can make one of the components visible (the top one in the card deck) by passing its index to the method setActiveItem(). The Viewport.js includes a container with the card layout (see ` cls: 'donate-panel'` in the next code sample).

5. Finding the children of the container can be done using the method down() method. in this case we are finding the child <form> element of a donate panel. If you need to find the parents of the component use up().

The top level window is a SSC.view.Viewport, which will contain the Header and the Donate form views.

1. Our viewport has a column layout, and will be explained after the Collapsed Code of Viewport.js Collapse Code of Viewport.js below.

2. The vertical box layout will display the components from the items array one under another : the appheader and the container, which is explained next.

3. The container with the class selector donate-panel includes two components, but since they are laid out as card, only one of them will be shown at a time: either the one with the "Lorem ipsum" text, or the donateform. Which one to show is mandated by the Donate controller by invoking the method setActiveItem() with the appropriate index.

The following figure shows a snapshot from WebStorm IDE, with collapsed code section just to see the big picture of what are the columns in the column layout - they are marked with arrows.

In Ext JS the column layout is used when you are planning to present the information in columns as explained in the product documentation. Even though there are three columns in this layout, the entire content on this page is located in the middle column having the width of 980. The column on the left and the column on the right just hold one non-breakable space each to provide centering of the middle column in monitors with high resolution wider than 980 pixels (plus the browser’s chrome).

The width of 0.5, 980, 0.5 means to give the middle column 980 pixels and share the remaining space equally between empty columns.

Tip: There is another way to lay out this screen using Horizontal Box hbox with the pack configuration property, but we decided to keep the column layout for illustration purposes.

Now let’s look at the child elements of the SSC.view.Viewport. The SSC.view.Header is the simplest view. Since Save Sick Child is not a typical enterprise application with a bunch of forms and grids, we’ll use the lightest top-level container class Container where possible. The class Container gives you the most freedom in what to put inside and how to layout its child elements. Our SSC.view.Header view extends Ext.Container and contains child elements, some of which have the xtype: component, and some - container:

1. We assigned appheader as the xtype value of this view, which will be used as a reference inside the SSC.view.Viewport.

2. cls is a class attribute of a DOM element. In this case it the same as writing class=app-header in the HTML element.

3. The header uses hbox layout with center alignment

4. Child components of the top container are the logo image, the text "Save Sick Child", and another container with buttons

5. A container with button components

Let’s review the view DonateForm next, which is a subclass of Ext.form.Panel and contains the form with radio buttons, fields and labels. This component named donateform will be placed under SSC.view.Header inside SSC.view.Viewport.

1. DonateForm depends on several classes listed in the requires property. The Ext JS will check to see if these classes are present in memory, and if not, the loader will load all dependencies first, and only after the DonateForm class.

2. Our DonateForm uses horizontal box (hbox) layout, which means that certain components or containers will be laid out next to each other horizontally. But which ones? The children of the container located in the items[] arrays hence they are the once that will be laid out horisontally in this case. But the above code contains several of items[] arrays with different level of nesting. How quickly find those that belong to the topmost container DonateForm? This is the case that clearly shows that having a good IDE can be of great help.

   Collapsed Code of Viewport.js shows a snapshot from the WebStorm IDE illustrating how can you find the matching elements in the long listings. The top level items[] arrays starts from line 23 and we see that the first element to be laid out by in hbox has the xtype: container, which in turn has some children. If you’ll move the blinking cursor of the WebStorm editor right after the firs open curly brace in line 23, you’ll see a thin blue vertical line that goes down to line 60. This is where the first object literal ends.

   Hence the second object to be governed by the hbox layout starts on line 61. You can repeat the same trick with the cursor to see where that object ends and the fieldcontainer starts . This might seem like a not overly important top, but it really saves developer’s time.

3. The first element of the hbox is a container that internally laid out as a vbox (see DonateForm.js: an hbox with three vbox containers).Tthe radiogroup is on top and the textfield for entering Other amount at the bottom.

4. The fieldcontainer is a light-weight Ext JS container useful to group components - the donor information in this case. It’s the central element in the hbox container shown in DonateForm.js: an hbox with three vbox containers.

5. The right side of the hbox is another container with the vbox internal layout to show the "We accept Paypal" message, "DONATE NOW", and "I’ll donate later" buttons (see DonateForm.js: an hbox with three vbox containers). These buttons respond to clicks because

The code review of the top portion of the Save Sick Child application is finished. Run the SSC_Top_ExtJS project and turn on the Chrome Developers Tools. Scroll to the bottom of the Network tab, and you’ll see that the browser made about 250 requests to the server and downloaded 4.5Mb in total. Not too exciting isn’t it?

On the next runs these numbers will drop to about 30 requests and 1.7Mb transferred - the browser’s caching kicked in. These numbers would be better if instead of ext-all.js we’d be linking ext.js, and even better if we’d created a custom build (see Sencha CMB section above) for the Save Sick Child application merging the application code into one file to contain only those framework classes that were actually used.

In this section we’ll review the code supporting the lower half of the Save Sick Child UI, which you should import into Eclipse IDE from the file SSC_Complete_ExtJS.zip. If you see the target runtime error, read the beginning of the section "Save Sick Child: The Top Portion" for the cure. Stop the Tomcat server if running, and deploy the SSC_Complete_ExtJS under Tomcat server in the Servers view (the right-click menu, Add and Remove…​). Start Tomcat in Eclipse, right-click on the project and run it on the server. It’ll open up a Web browser pointing at http://localhost:8080/SSC_Complete_ExtJS showing the window similar to the one depicted on Save Sick Child with live charts.

This version has some additions comparing to the previous ones. Notice the bottom left panel with charts. First of all, the charts are placed inside the panel with tabs: Charts and Table. The same data can be rendered either as a chart or as a grid. Second, the charts became live thanks to ExtJS. We took snapshot of the Window shown in Save Sick Child with live charts while hovering the mouse over the pie slice representing New York, and the slice has extended from the pie showing a tooltip.

The SSC_Complete_ExtJS has more Ext JS classes comparing to SSC_Top_ExtJS. You can see more views on JavaScript classes of SSC_Complete_ExtJS. Besides, we’ve added two classes Donors.js and Campaigns.js to serve as data stores for the panels with charts and maps.

In this part we’ll cover the following topics:

• What is Clear Toolkit for Ext JS

• How to create an Ext JS MVC front end for a Java-based project

• How to deploy and run your first Ext JS and Java application on Apache Tomcat server

Clear Toolkit for Ext JS includes the following:

• Clear Data Builder - an Eclipse plugin that supports code generation Ext JS MVC artifacts based on the code written in Java. CDB comes with wizards to start new project with plain Java or with popular frameworks like Hibernate, Spring, MyBatis.

• Clear JS - a set of JavaScript components that extends Ext JS standard components. In particular, it includes a ChangeObject that traces the modifications of any item in a store.

• Clear Runtime - Java components that implements server side part of ChangeObject, DirectOptions an others.

CDB distribution available as plug-in for a popular among Java developers Eclipse IDE. The current update site of CDB is located here. The current version is 4.1.4. You can install this plug-in via the Install New Software menu in Eclipse IDE. The Verifying CDB installation shows "Clear Data Builder for Ext JS feature" in the list of Installed Software in your Eclipse IDE, which means that CDB is installed.

Clear Data Builder comes with a set of prepared examples that demonstrate the integration with popular Java frameworks - MyBatis, Hibernate, and Spring. There is also a plain Java project example that doesn’t use any persistence frameworks. Let’s start with the creation of the new project by selecting Eclipse menu File → New → Other → Clear. You’ll see a window similar to New CDB Project Wizard.

Name the new project episode_1_intro. CDB supports different ways of linking the Ext JS framework to the application. CDB automatically copies the Ext JS framework under the Web server (Apache Tomcat in our case). We’re going to use this local Ext JS URL, but you can specify any folder in your machine and CDB will copy the Ext JS file from there into your project. You can also use Ext JS from the Sencha’s CDN, if you don’t want to store these libraries inside your project. Besides, using a common CDN will allow Web browser to reuse the cached version of Ext JS.

For this project we are not going to use any server-side persistence frameworks like MyBatis or Hibernate. Just click the button Finish, and you’ll see some some initial CDB messages on the Eclipse console. When CDB runs for the first time it creates in your project’s WebContent folder the directory structure recommended by Sencha for MVC applications. It also generates index.html for this application, which contains the link to the entry point of our Ext JS application.

CDB generates an empty project with one sample controller and one view - Viewport.js. To run this application, you need to add the newly generated Dynamic Web Project to Tomcat and start the server (right-click on the Tomcat in the Servers view of Eclipse IDE).

Open this application in your Web browser at http://localhost:8080/episode_1_intro . Voila! In less than a couple of minutes we’ve created a new Dynamic Web Project with the Ext JS framework and one fancy button as shown on Running scaffolded application.

The next step is to make something useful out of this basic application.

The Part Two of the CDB section covers the process of creation of a simple CRUD application that uses Ext JS and Java. We’ll go through the following steps:

• Create a plain old Java object (POJO) and the corresponding Ext.data.Model

• Create a Java service and populate Ext.data.Store with data from service

• Use the auto-generated Ext JS application

• Extend the auto-generated CRUD methods

• Use ChangeObject to track the data changes

Now let’s use CDB to create a CRUD application. You’ll learn how turn a POJO into an Ext JS model, namely:

• how to populate the Ext JS store from a remote service

• how to use automatically generated UI for that application

• how to extend the UI

• what the ChangeObject class is for

First, we’ll extend the application from Part One - the CRUD application needs a Java POJO. To start, create a Java class Person in the package dto. Then add to this class the properties (as well as getters and setters) firstName, lastName, address, ssn and phone and id. Add the class constructor that initializes these properties as shown in the code listing below.

You may also add a toString() method to the class. Now you’ll need the same corresponding Ext JS model for the Java class Person. Just annotate this class with the annotation @JSClass to have CDB generate the Ext JS model.

The next step is to annotate the id field with the CDB annotation @JSGeneratedId. This annotation instructs CDB to threat this field as an auto generated id. Let’s examine the directory of Ext JS MVC application to see what’s inside the model folder. In the JavaScript section there is the folder dto which corresponds to the Java dto package where the PersonModel resides as illustrated on Generated from Java class Ext JS model.

Clear Data Builder generated two files as recommended by the Generation Gap pattern, which is about keeping the generated and handwritten parts separate by putting them in different classes linked by inheritance. Let’s open the person model. In our case the PersonModel.js is extended from the generated _PersonModel.js. Should we need to customize this class, we’ll do it inside the Person.js, but this underscore-prefixed file will be regenerated each and every time when we change something in our model. CDB follows this pattern for all generated artifacts - Java services, Ext JS models and stores. This model contains all the fields from our Person DTO.

Now we need to create a Java service to populate the Ext JS store with the data. Let’s create a Java interface PersonService in the package service. This service will to return the list of Person objects. This interface contains one method -List<Person> getPersons().

To have CDB to expose this service as a remote object, we’ll use the annotation called @JSService. Another annotation @JSGenetareStore will instruct CDB to generate the store. In this case CDB will create the destination-aware store. This means that store will know from where to populate its content. All configurations of the store’s proxies will be handled by the code generator. With @JSFillMethod annotation we will identify our main read method (the "R" from CRUD).

Also it would be nice to have some sort of a sample UI to test the service - the annotation @JSGenerateSample will help here. CDB will examine the interface PersonService, and based on these annotations will generate all Ext JS MVC artifacts (models, views, controller) and the sample application.

When the code generation is complete, you’ll get the implementation for the service - PersonServiceImpl. The store folder inside the application folder (WebContent\app) has the Ext JS store, which is bound to the previously generated PersonModel. In this case, CDB generated store that binds to the remote service.

All this intermediate translation from the JavaScript to Java and from Java to JavaScript is done by DirectJNgine, which is a server side implementation of the Ext Direct Protocol. You can read about this protocol in Ext JS documentation.

CDB has generated a sample UI for us too. Check out the samples directory shown on Folder with generated UI files.

CDB has generated SampleController.js, SampleGridPanel.js, and the Ext JS application entry point sampleApp.js. To test this application just copy the file SampleController.js into the controller folder, SampleGridPanel.js panel into the view folder, and the sample application in the root of the WebContent folder. Change the application entry point with to be sampleApp.js in the index.html of the Eclipse project as shown below.

This is how the generated UI of the sample application looks like Scaffolded CRUD application template.

On the server side, CDB also follows the Generation Gap Pattern and it generated stubs for the service methods. Override these methods when you’re ready to implement the CRUD functionality, similar to the below code sample.

1. Extend the generated class and provide the actual implementation

2. The getPerson() is our retrieve method (the R in CRUD)

3. For this sample application we can use java.util.ArrayList class as in-memory server side storage of the Person objects. In the real world applications you’d use a database or other persistent storage

4. fillmethod+doCreate() is our create method (the C in CRUD)

5. fillmethod+` doUpdate` is our update method (the U in CRUD)

6. fillmethod+` doDelete` is our delete method (the D in CRUD)

Click on the Load menu on the UI, and the application will retrieve four persons from our server

To test the rest of the CRUD methods, we’ll ask the user to insert one new row, modify three existing ones and remove two rows using the generated Web client. The Clear.data.DirectStore object will automatically create a collection of six `ChangeObject`s - one to represent a new row, three to represent the modified ones, and two for the removed rows.

When the user clicks on the Sync UI menu the changes will be sent to the corresponding do…​ remote method. When you sync() a standard Ext.data.DirectStore Ext JS is POST-ing new, modified and deleted items to the server. When the request is complete the server’s response data is applied to the store expecting that some items can be modified by the server. In case of Clear.data.DirectStore instead of passing around items, we pass the deltas, wrapped in the ChangeObject.

Each instance of the ChangeOject contains the following:

• newVersion - it’s an instance of the newly inserted or modified item. On the Java side it’s available via getNewVersion().

• prevVersion - it’s an instance of the deleted of old version of modified item. On the Java side it’s available via getPrevVersion().

• array of changepropertyNames if this ChangeObject represents an update operation.

The rest of ChangeObject details described on the Clear Toolkit Wiki.

The corresponding Java implementation of ChangeObject is available on the server side and Clear Toolkit passes ChangeObject instances to the appropriate do* method of the service class. Take a look at the getPersons_doCreate() method from Implementation of PersonService interface. When the server needs to read the new or updated data arrived from the client your Java class has to invoke the method changeObject.getNewVersion(). This method will return the JSON object that you need to deserialize into the object Person. This is done in Implementation of PersonService interface and looks like this.

When the new version of the Person object is extracted from the ChangeObject you can do with it whatever has to be done to persist it in the appropriate storage. In our example we just print the new person information on the server-side Java console. This is why we said earlier, that it may be a good idea to provide a pretty printing feature on the class Person by overriding method toString(). Similarly, when you need to do a delete, the changeObject.getPrevVersion() would give you a person to be deleted.

The pagination feature is needed in almost every enterprise web application. Often you don’t want to bring all the data to the client at once - a page by page feed brings the data to the user a lot faster. The user can navigate back and forth between the pages using pagination UI components. To do that, we need to split our data on the server side into chunks, to send them page by page by the client request. Implementing pagination is the agenda for this section. We’ll do the following:

• Add the data pagination to our sample CRUD application:

  • Add the Ext.toolbar.Paging component

  • Bind both grid and pagingtoolbar to the same store

  • Use DirectOptions class to read the pagination parameters

We are going to improve our CRUD application by adding the paging toolbar component bound to the same store as the grid. The class DirectOptions will handle the pagination parameters on the server side.

So far CDB has generate the UI from the Java back end service as well as the Ext JS store and model. We’ll refactor the service code from previous example to generate more data (a thousand objects) so we have something to paginate, see below.

If you’ll re-run the application now, the Google Chrome Console will show that PersonStore is populated with one thousand records. Now we’ll add the the Ext JS paging toolbarpaging UI component to the file sampleApp.js as shown below.

1. Manual store instantiation - create a separate variable myStore for this store with empty config object

2. Adding the xtype pagingtoolbar to this component docked items property to display the information and dock this element at the top.

3. Now the paging toolbar is also connected to same store.

The next step is to fix the automatically generated controller to take care of the loading of data on click of Load button as shown in the code below.

1. Bind the store instance to our grid panel. In controller’s refs property we’re referencing our simplegrid panel with ThePanel alias.

2. In this case there is no need to explicitly retrieve the store instance by name. Instead, we can use getters getPanel() and getStore() automatically generated by the Ext JS framework.

When the user clicks the button next or previous the method loadPage of the underlying store is called. Let’s examine the directprovider URL - the server side router of the remoting calls - to see how the direct request looks like. Open Google Chrome Developer Tools from the menu View → Developer, refresh the Web page and go to the Network tab. You’ll see that each time the user clicks on the next or previous buttons on the pagination toolbar the component sends directOptions as a part of the request.

The default Ext Direct request doesn’t carry any information about the page size. Clear JS has the client side extension of the Ext JS framework that adds some extra functionality to Ext.data.DirectStore component to pass the page start and limit values to the server side. At this point, the directOptions request property (see Request payload details) can be extracted on the server side to get the information about the page boundaries. Let’s add some code to the PersonServiceImpl.java. At this point the pagination doesn’t work. The server sends the entire thousand records, because it doesn’t know that the data has to be paginated. We’ll fix it in the following listing.

1. On the server side there is a special object called DirectOptions, which comes with Clear Toolkit.

2. We want to monitor the start and in limit values (see Request payload details).

3. Calculate the actual limit. Assign the size of the data collection to the limit variable if it’s less than the page size (start+limit).

4. Notify the component about the total number of elements on the server side by using DirectOptions.setOption() method with total option.

5. Before returning the result, create a subset, an actual page of data using the method java.util.List.sublist() which produces the view of the portion of this list between indexes specified by the start and the limit parameters.

As you can see from the Network tab in Scaffolded CRUD application template, we’ve limited the data load to 25 elements per page. Clicking on next or previous buttons will get you only a page worth of data. The Google Chrome Developers Tools Network tab shows that that we are sending the start and limit values with every request, and the response contains the object with 25 elements.

If you’d like to repeat all of the above steps on you own, watch the screencasts where we demonstrate all the actions described in the section on CDB.