Building Themes for Ext JS
This guide describes the file-level mechanics of building and managing themes with Sencha Cmd, which can automate several of the steps required to build a theme. Note that developing themes or managing styles or SASS variables are not covered here -- these are part of your application development process.
First, in order to build themes from SASS, be sure to install Compass on your system.
Most of this guide assumes you are working in an application generated by Sencha Cmd. If that is not the case, many of these steps will change to reflect different paths and the like. See the section below on "Managing Themes Manually".
All applications start with a "default" theme. Different pieces are stored in two folders:
Use of SASS
The majority of your work on themes is done in SASS. The starter files are generated for
you, and you edit them to complete your theme. When you compile your SASS, it should generate
a CSS file in
If you need two or more themes (as described in Using Sencha Cmd with Ext JS), you can generate new themes with this command:
sencha generate theme foo
This will generate the following:
The SASS should be compiled to
Building an Application's Themes
sencha app build command will produce full image sets for all themes in a given
application as part of the standard build process. To achieve this, images from the
base framework theme are first staged into the
"resources/.img/<theme name>" directory
under the application's root directory. Then, sliced images for each theme are generated
using the technique described in the following section and overlaid over the theme images
provided by the framework. Finally, user supplied images located in the application's
"resources/images" directory are overlaid into the output of the theme build operations to
produce the final image set. The resultant application resource directory will have the
resources/ images/ # application-wide image content and theme image overrides ... theme/ default/ sass/ # sass input files for the default theme ... .res/ default/ images/ # unified image content generate by build process ...
All output images are staged into a
".res" directory under the application's source directory
to enable development-time viewing of a built theme. This
".res" directory is then
copied to the application's build output folder to maintain relative paths for
deployment. As this generated
".res" directory is generated to a file system location
commonly under revision control, it may be desirable to add this directory to the revision
control system's exclusion mechanism (such as a .gitignore entry). Doing so should not
impact application behavior, as this folder is fully generated by Sencha Cmd and is copied
to the build output location during the app build process.
Extracting images for a single theme
Typically, your themes will be compiled and built by the
sencha app build command, but
it is sometimes helpful to produce images for a single theme at a time. To compile a theme,
compass compile command in your SASS directory.
cd /path/to/MyApp/resources/sass/default compass compile
This should produce the CSS in
"../../../../.res/default/app.css" (or from the root of your
The next step is to build the image slices needed for IE browsers. This is done with the following command:
cd /path/to/MyApp sencha theme build -out resources/sliced_images/default
This will place the sliced images in the
"./.res/default/images" folder alongside the
CSS file generated by SASS. If the '-out' parameter is omitted, then sliced images will be placed
in a 'resources/images/default' directory under the default build output folder for the
application. All image paths are relative to the CSS file location to minimize the size
of the CSS file.
Anatomy of a Theme
theme folder is split in to two levels. For clarity, lets consider a
with two themes:
theme/ custom.js manifest.js render.js shortcuts.js default/ theme.html gray/ theme.html
"theme.html" file is the entry point for the image generation phase of the theme
You should be able to open this file in Chrome or any other modern browser and see what the base image will be for your theme. This is an ideal page to test your styling because every component in every state will be present.
This is an example of what the
"resources/theme/default/theme.html" file looks like:
This file is designed to be edited as needed. This file will not be edited or regenerated by Sencha Cmd.
Important. While this file is freely editable, be sure to keep the relative order of
script tags. In particular
"custom.js" must come after
"shortcuts.js" and before
The most likely things you might need to edit in this file are the relative paths. All of
the generated files included in the page need to be preserved. You can add
link tags as needed, but consider their order in the sequence of tags.
The following files should be considered private and should not be edited:
manifest.js- The set of all components to render.
shortcuts.js- Reusable "templates" used by the manifest.
styles.css- Styles specific to the theme builder.
render.js- Renders the components described by the manifest and shortcuts.
Add value to the process through the
"custom.js" file. The primary use of this file is
to add new shortcuts or manifest entries that might be needed by custom components you
have created for your application. This file will not be regenerated by Sencha Cmd.
Third Party Components
If you have received custom components from a third party, you should ask them to provide
a custom theme definition file so that you can include it in your
theme folder and as a
script tag in your '"theme.html"'. The content of such a file should be the same as
described for a
You will probably also need SASS files (or at least CSS files) to add to your SASS theme
link tags in
Managing Themes Manually
Many applications existed before Sencha Cmd provided application management features or for other reasons do not have the structure assumed by the simple commands described here. While the commands to handle this case require more switches and understanding, it is possible to use Sencha Cmd in these more complex situations.
Important. The new version of Sencha Cmd takes a different approach to theme building
than did previous versions (which called this mechanism the "slicer"). There is no longer
sencha slice command. This is now handled by the new
sencha theme build command.
Creating Your Custom Theme
In order to produce sliced images for your theme, you need the necessary files that define
the theme. The easiest way to get these files is to generate an application in some temporary
folder and copy the
"./resources/theme" folder to a location of your choosing using the
sencha generate app /temp/dummyApp
"/temp/dummApp/resources/theme" to your desired location. For example, let's say
that location is
Following the above rules for customization of
"theme.html" you can flatten the folders in
to a single folder and change the relative paths in
"theme.html" accordingly. You can also
correct the relative paths to your CSS file(s) and the framework.
Compiling Your Custom Theme
Once you have moved the theme files to
"/path/to/MyApp/stuff/theme" and editing all of the
relative paths in
"theme.html", you can proceed to generate images. Let's assume you run
the command from the root of your application.
cd /path/to/MyApp sencha theme build -page stuff/theme/theme.html -out images/theme
This will load
"stuff/theme/theme.html" using an embedded WebKit instance and capture an
image of the content of the rendered page as well as a data object describing all of the
image slicing required. From those two results, the image slicing will proceed to generate
all of the images to the
If something is wrong with the generated images, it can be helpful to keep the page image and the data object for diagnostic purposes. This can be done by specifying their names in the command:
cd /path/to/MyApp sencha theme build -page stuff/theme/theme.html -out images/theme \ -image image.png -data data.json
The image is always a PNG file because PNG is both lossless and has a proper alpha channel. The data object is always in JSON format.