I’d like to provide a quick tutorial on using EXT-JS. This should be helpful for users creating a site from scratch, or looking to incorporate EXT-JS’s features into an existing site.

1. What Else Should You Start?

First, download the desired version from Sencha’s website! The releases can be found here. I will be demonstrating EXT-JS 3.4, as that is what I have the most experience in. (hope to post a new version with EXT-JS 4 when I have the time)

2. Project

I’ve created a simple example project in Eclipse which contains the site which I will deploy. I’m using Apache Tomcat 6.0.32 as my container, but others are alright too. The structure of my project is as follows:

• WebContents
  • js
    • mainPage.js
  • static
    • extjs
      • adapter
      • resources
      • ext-all.js
      • ext-all-debug.js
      • … other ext-js files …
  • index.jsp
• build.properties
• build.xml

3. Fast Deployment

I’m using the build.xml and build.properties to aide in deployment. Feel free to duplicate these, and save yourself the hassle of deploying! The build.properties is just a flat text file containing the variables for the tomcat.home and deploy.path.

tomcat.home=/users/clearTheHaze/development/apache-tomcat-6.0.32
deploy.path=${tomcat.home}/webapps

Here is my build.xml:

<?xml version="1.0"?>

<project name="springapp" basedir="." default="usage">

    <!-- Load our library directories from the build.properties file -->
    <property file="build.properties" />

    <!-- set global properties for this build -->
    <property name="web.dir" value="WebContent" />
    <property name="dist" value="dist" />
    <property name="name" value="extSite" />
    <property name="war.name" value="${name}.war" />
    <property name="war.buildpath" value="${dist}${war.name}" />

    <property name="env.CATALINA_HOME" value="${tomcat.home}" />
    <property environment="env" />

    <target name="usage">
        <echo message="" />
        <echo message="${name} build file" />
        <echo message="-----------------------------------" />
        <echo message="" />
        <echo message="Available targets are:" />
        <echo message="" />
        <echo message="deploy        --> Deploy application as directory" />
        <echo message="update-live  --> Update the JSPs without shutting down Tomcat" />
        <echo message="start        --> Start Tomcat application" />
        <echo message="stop          --> Stop Tomcat application" />
        <echo message="" />
    </target>

    <target name="war" depends="clean-dev" description="Build the war">
        <!-- Create the distribution directory -->
        <mkdir dir="${dist}" />

        <delete file="${war.buildpath}" />

        <!-- Build the WAR file -->
        <war destfile="${war.buildpath}" webxml="${web.dir}/WEB-INF/web.xml">
            <fileset dir="${web.dir}/">
                <include name="**/*.*" />
            </fileset>

            <fileset dir="${web.dir}">
                <include name="*.jsp" />
            </fileset>
        </war>
    </target>

    <target name="deploy-war" depends="war,clean-server" description="Build and deploy the war">
        <delete file="${deploy.path}/${war.name}" />
        <delete dir="${deploy.path}/${name}" />
        <!-- Copy war to the appserver -->
        <copy todir="${deploy.path}" preservelastmodified="true">
            <fileset dir="${dist}">
                <include name="${war.name}" />
            </fileset>
        </copy>
    </target>

    <target name="update-live" description="Update the JSPs without shutting down Tomcat">
        <copy todir="${deploy.path}/${name}/" preservelastmodified="true">
            <fileset dir="${web.dir}/">
                <include name="**/*.*" />
            </fileset>
        </copy>
        <copy todir="${deploy.path}/${name}" preservelastmodified="true">
            <fileset dir="${web.dir}">
                <include name="*.jsp" />
            </fileset>
        </copy>
    </target>

    <!-- Clean up the environment -->
    <target name="clean-server" description="Clean up the application deployed on the server (including Tomcat cache)">
        <delete file="${deploy.path}/${war.name}" />
        <delete dir="${deploy.path}/${name}" />
        <delete dir="${tomcat.home}/work/Catalina" />
    </target>

    <target name="clean-dev" description="Clean up the local build environment (build dir, WAR file)">
        <delete file="${war.buildpath}" />
    </target>

    <target name="tomcat-start">
        <java dir="${tomcat.home}/bin" jar="${tomcat.home}/bin/bootstrap.jar" fork="true">
            <jvmarg value="-Dcatalina.home=${tomcat.home}" />
            <arg line="start" />
        </java>
    </target>

    <target name="tomcat-stop">
        <java jar="${tomcat.home}/bin/bootstrap.jar" fork="true">
            <jvmarg value="-Dcatalina.home=${tomcat.home}" />
            <arg line="stop" />
        </java>
    </target>
</project>

For our example, you only need to execute the “update-live” target. This will deploy the entire structure to the webapps directory, and you can tinker and add and never have to restart Tomcat.

4. The Entrance

The index.jsp file is the entry point for our application. In it, we declare all the imports for the EXT-JS library, set any css, and import all custom javascript files. In the project setup, you’ll see that I plan to use the js folder to hold those custom javascript files. I plan to put static JS in the extjs folder, and will add an img folder when needed. Thus, my index.jsp reads:

<html>
    <head>
        <title>ExtJS Example Site</title>

        <!-- ExtJS CSS -->
        <link rel="stylesheet" type="text/css" href="/static/extjs/resources/css/ext-all.css" />

        <!-- ExtJS JS -->
        <script type="text/javascript" src="./static/extjs/adapter/ext/ext-base.js"></script>
        <script type="text/javascript" src="./static/extjs/ext-all.js"></script>

        <script type="text/javascript" src="./js/mainPage.js"></script>
    </head>
    <body>
        <script type="text/javascript">
            Ext.onReady(function() {
                new ExtSite.Example.Workspace();
            });
        </script>
    </body>
</html>

As you can see, I have my title, and within the head of my html, I have the imports. You’ll see I import the ext-all.js and the adapter for ext-base.js. The latter is not necessary in EXT-JS 4. The body contains a small script in EXT-JS. Ext is ready when the document is ready (before onload and before images are loaded). It then fires this function, creating a new ExtSite.Example.Workspace (whatever that is, right?). Now, let’s see what that is supposed to be…

5. The First EXT-JS

The mainPage.js is the ViewPort for rendering all of our Panels. To start, it’ll just contain a pair of Panels. Let’s start with looking at the script:

Ext.namespace("ExtSite.Example");

ExtSite.Example.Workspace = Ext.extend(Ext.Viewport, {
  constructor: function (config) {
    config = config || {};

    Ext.applyIf(config, {
      layout: "border",
      items: [
        {
          region: "north",
          bodyStyle: "padding:5;",
          html: "<h1>Clear the Haze Examples</h1>",
          autoHeight: true,
          border: true,
        },
        {
          region: "center",
          html: "Welcome to our page!",
        },
      ],
    });

    ExtSite.Example.Workspace.superclass.constructor.call(this, config);
  },
});

As you can see, it’s very lightweight. It starts similar to Java with the package declaration. The namespace is useful for separating the modules. I tend to have all modules relating to a common area under the same package, though they may span several JS files. I like to keep files small and clean.

Another observation is that the JS file name does not have to match anything within the file. This is helpful because the name can represent the broad scope of a file’s content.

The next part of the definition is the extension (through Ext.extend) of the Ext.ViewPort class. We are saying the ExtSite.Example.Workspace is a ViewPort. The Ext.ViewPort is a specialized rendering container for displaying panels in our page.

The next step is to override the constructor, which is a function taking a configuration. I like to verify the config is available by writing “config = config || {};”. Next, we enter the Ext.applyIf section. This is appending configurations to the config. It is here that we define the custom components for our ViewPort. I’ve set the layout to ‘border’, which separates the part of the page into 5 sections, which you’ll likely understand as you read them – ‘north’, ‘east’, ‘south’, ‘west’, and ‘center’. You must always have a ‘center’ region when using the ‘border’ layout. This wasn’t clear when I started out, and I learned the hard way. Don’t learn the hard way!

The items I’ve defined are two Panels. This is the cool thing about EXT-JS — you do not need to define every thing. It interprets it for you sometimes! Since I won’t ever want to re-use those segments, they are fine defined as they are. We’ll see other examples soon to demonstrate where it’s better to define an object.

Lastly, we call the super constructor, passing it our config.

6. Finished Product

Once complete, we deploy it and have a simple interface, which can quickly grow into a larger UI. Start Tomcat ($TOMCAT_HOME/bin/catalina.sh start), and go to localhost:8080/extSite/ (or whatever extension you named your site). You will be presented with this simple hello: