Upgrade to ExtJS 4.0.1 - Released 05/18/2011
[extjs.git] / docs / guides / theming / _README.md
1 # Theming
2 ______________________________________________
3
4 With Ext JS 4 we’ve built on our experience with Sencha Touch to make the framework more themable than ever before by unlocking the power of SASS and Compass. Every aspect of the framework’s appearance can be customized, often by simply tweaking a color variable.
5
6 <iframe src="http://player.vimeo.com/video/19159630?byline=0" width="500" height="281" frameborder="0"></iframe>
7
8 Sencha Touch has introduced a revolutionary new theming system, built on SASS and Compass, that allows you to create versions of our base theme custom tailored to your application and brand. Because Sencha Touch is built on web standards and targets WebKit, developers are free to use the wide variety of CSS3 properties already available to the platform, like border-radius, background gradients, and even more advanced properties like the CSS3 flexible box model. To create a custom variant of the bundled theme that uses SASS and Compass is very straight-forward as well.
9
10 (original article http://www.sencha.com/blog/an-introduction-to-theming-sencha-touch/)
11
12 ## A Brief Introduction to SASS & Compass
13
14 <iframe src="http://player.vimeo.com/video/18084338?byline=0" width="500" height="281" frameborder="0"></iframe>
15
16 SASS is a pre-processor which adds new syntax to CSS allowing for things like variables, mixins, nesting, and math/color functions. For example, in SASS we can write:
17
18     $blue: #3bbfce;
19     $margin: 16px;
20  
21     .content-navigation {
22         border-color: $blue;
23         color: darken($blue, 9%);
24     }
25  
26     .border {
27         padding: $margin / 2;
28         margin: $margin / 2;
29         border-color: $blue;
30     }
31  
32 And it will compile to:
33
34     .content-navigation {
35         border-color: #3bbfce;
36         color: #2b9eab;
37     }
38  
39     .border {
40         padding: 8px;
41         margin: 8px;
42         border-color: #3bbfce;
43     }
44  
45 To see the wide variety of other features available in SASS, please see http://sass-lang.com/. Compass extends SASS by adding a variety of CSS3 mixins and providing the extension system that Sencha Touch leverages. With Compass, one can include rules like:
46
47     $boxheight: 10em;
48  
49     .mybox {
50         @include border-radius($boxheight/4);
51     }
52  
53 Which compiles into:
54
55     .mybox {
56         -webkit-border-radius: 2.5em;
57         -moz-border-radius: 2.5em;
58         -o-border-radius: 2.5em;
59         -ms-border-radius: 2.5em;
60         -khtml-border-radius: 2.5em;
61         border-radius: 2.5em;
62     }
63  
64 You can learn more about the pre-included mixins with Compass and the other tools which it provides here: http://compass-style.org/docs/. I’ve only really touched the surface of what’s possible with these technologies, so I can focus on our use of them in Sencha Touch, but I highly encourage you to briefly look at their respective sites to get a better sense of their capabilities. Now, though, let’s look at setting up a SASS/Compass environment where we can create custom Sencha Touch themes.
65
66 ## Setting Up Custom Stylesheets
67 First, we’ll need to make sure we have SASS and Compass installed. Because these technologies are based on Ruby, Windows users will need to install Ruby and RubyGems (these come pre-bundled on Macs). Because SASS is bundled with Compass, you can install both with the following Terminal command:
68
69   gem install compass
70
71 Note: You may need to install using “sudo gem install…” for administrative privileges.
72
73 Once everything is installed, we’ll need to create a new directory in our project to house our new SASS stylesheets. I typically use resources/scss (SCSS is the syntax language for SASS, and stands for “Sassy CSS”). Within the directory, we’ll create two files, config.rb and application.scss.
74
75 __config.rb__ The config.rb is written in Ruby, and is very straight-forward to set up (so don’t worry if you don’t know Ruby). The file is typically a set-it-and-forget-it:
76
77     # Delineate the directory for our SASS/SCSS files (this directory)
78     sass_path = File.dirname(__FILE__)
79  
80     # Delineate the CSS directory (under resources/css in this demo)
81     css_path = File.join(sass_path, "..", "css")
82  
83     # Delinate the images directory
84     images_dir = File.join(sass_path, "..", "img")
85  
86     # Load the sencha-touch framework
87     load File.join(sass_path, '..', '..', '..', '..', 'resources', 'themes')
88  
89     # Specify the output style/environment
90     output_style = :compressed
91     environment = :production
92  
93 If you are debugging your custom stylesheet, you may also want to set your output_style to “:expanded,” which will compile your CSS line-by-line and actually show, with comments, where the rules are being generated in your SCSS. “:compressed,” as shown above, compacts all of your CSS to one line and removes any comments/extraneous spaces — which is ideal for minimizing footprint in production environments.
94
95 __application.scss__ The application.scss file is written in SCSS and has the following structure (we’ll go over what some of these terms mean in a moment):
96
97     // 1. Variable overrides, example:
98     // $base-color: #af2584;
99  
100     // 2. Include Sencha Touch styles
101     @import 'sencha-touch/default/all';
102     @include sencha-panel;
103     @include sencha-buttons;
104     @include sencha-sheet;
105     @include sencha-picker;
106     @include sencha-toolbar-forms;
107     @include sencha-tabs;
108     @include sencha-toolbar;
109     @include sencha-carousel;
110     @include sencha-indexbar;
111     @include sencha-list;
112     @include sencha-layout;
113     @include sencha-form;
114     @include sencha-loading-spinner;
115  
116     // 3. Define custom styles (can use SASS/Compass), example:
117     // .mybox {
118     //     @include border-radius(4px);
119     // }
120  
121 As you can see, the main gist of this is that we are importing styles from Sencha Touch, component by component. The area above (1) is where we can actually override variables used by the default Sencha Touch theme to change the output when the actually stylesheets are created/included. There are currently about 50 variables available to override, though we’ll just focus on a few key ones in this article.
122
123 ![Base color](basecolor.png)
124
125 ## Sencha Touch Variables
126 __$base-color__ Perhaps the easiest way to create a sweeping change in your app’s design, you can change the $base-color to drastically alter the appearance of all components. The screenshots above demonstrate how the UI changes by simply altering the $base-color.
127
128 Other global color variables include $alert-color (red by default), $confirm-color (green by default), $active-color (a saturated version of $base-color, blue by default).
129
130 __$base_gradient__ Similar to $base-color, $base-gradient allows you to drastically change the appearance of your app by modifying the gradient style of all elements like buttons, toolbars, and tabbars. The four included values for gradients are ‘matte’, ‘bevel’, ‘glossy’, ‘recessed’, and ‘flat’.
131
132 ## Custom Styles & Sencha Touch Mixins
133 In our application.scss shown above, you will notice there is a specific area (3) for custom styles, after we’ve imported the library stylesheets. This is your area to write your application’s custom CSS, and make use of any mixins provided by Sencha Touch. Some common mixins provided by Sencha Touch allow you to embed extra icons in your application and create custom “ui” styles to apply to buttons, toolbars, or tabbars.
134
135 __@include pictos-iconmask($name)__ This allows you to embed a custom icon mask for use in buttons or tabs. There are over 300 icons that you can include in your application, thanks to Drew Wilson’s fine Pictos set. All of the icons are base64 encoded into your CSS to cut down on server requests, which is useful in the mobile context. The icons can be found in the Sencha Touch distribution under resources/themes/images/default/pictos/. To include a new icon, simply pass the name of the icon you want, minus the .png extension:
136
137     @include pictos-iconmask(‘wifi’);
138  
139 You can then use it in your application like so:
140
141     var btn = new Ext.Button({
142         iconMask: true,
143         iconCls: 'wifi'
144     });
145  
146 __@include sencha-button-ui($ui-label, $color, $gradient)__ By default, Sencha Touch comes with a variety of button colors and forms, but sometimes you may want another color option for alternative actions. This mixin creates a button UI with the color/gradient specified in the corresponding variables. In addition, this mixin also generates ‘{your-ui-name}-round’ and ‘{your-ui-name}-small’. The text color and shading will be automatically calculated from the background color. Likewise, there are mixins for sencha-toolbar-ui, and sencha-tabbar-ui.
147
148     @include sencha-button-ui('orange', #ff8000, 'glossy');
149     And then use in your JavaScript:
150
151
152     var glossy_orange_btn = new Ext.Button({
153         ui: 'orange',
154         text: 'Orange'
155     });
156  
157     var round_glossy_orange_btn = new Ext.Button({
158         ui: 'orange-round',
159         text: 'Orange Round'
160     });
161
162 ![Buttons](btn.png)
163
164 ## Compiling Our Stylesheet & Adding to Our Application
165 To compile our stylesheet, we simply run the command “compass compile” in the Terminal from within the scss directory. This command will automatically look for the config.rb, and take care of compiling the CSS into the proper directory.
166
167 When you add the stylesheet to your HTML file, don’t forget to remove the included sencha-touch.css — as you’re newly compiled stylesheet includes all of the framework styles as well.
168
169 ## Some Sample Stylesheets
170
171 ### Demo #1
172
173     $base-color: #7A1E08;
174     $base-gradient: 'glossy';
175  
176     @import 'sencha-touch/default/all';
177  
178     @include sencha-panel;
179     @include sencha-buttons;
180     @include sencha-sheet;
181     @include sencha-picker;
182     @include sencha-toolbar-forms;
183     @include sencha-tabs;
184     @include sencha-toolbar;
185     @include sencha-carousel;
186     @include sencha-indexbar;
187     @include sencha-list;
188     @include sencha-layout;
189     @include sencha-form;
190     @include sencha-loading-spinner;
191  
192 ![Demo 1](demo1.png)
193  
194 ### Demo #2
195
196     $body-bg-color: #fbf5e6;
197     $base-color: #efe1d0;
198     $active-color: #aa3030;
199  
200     @import 'sencha-touch/default/all';
201     @include sencha-panel;
202     @include sencha-buttons;
203     @include sencha-sheet; 
204     @include sencha-picker;
205     @include sencha-toolbar-forms;
206     @include sencha-tabs;
207     @include sencha-toolbar;
208     @include sencha-carousel;
209     @include sencha-indexbar;
210     @include sencha-list;
211     @include sencha-layout;
212     @include sencha-form;
213     @include sencha-sheet;
214  
215     body {
216         font-family: Georgia;
217         color: #5a3d23;
218     }
219  
220     .x-toolbar .x-toolbar-title {
221         color: #5a3d23;
222     }
223
224 ![Demo 2](demo2.png)
225  
226 ### Demo #3
227
228     $body-bg-color: #000;
229  
230     $base-color: #333;
231     $base-gradient: 'matte';
232     $active-color: #B2DF1E;
233  
234     $tabs-dark: $base-color;
235     $tabs-light: #555;
236  
237     $tabs-bottom-radius: .4em;
238     $tabs-bottom-gradient: 'bevel';
239     $tabs-bar-gradient: 'matte';
240     $tabs-bottom-active-gradient: 'recessed';
241  
242     $toolbar-gradient: 'glossy';
243  
244     @import 'sencha-touch/default/all';
245     @include sencha-panel;
246     @include sencha-buttons;
247     @include sencha-sheet; 
248     @include sencha-picker;
249     @include sencha-toolbar-forms;
250     @include sencha-tabs;
251     @include sencha-toolbar;
252     @include sencha-carousel;
253     @include sencha-indexbar;
254     @include sencha-list;
255     @include sencha-layout;
256     @include sencha-form;
257     @include sencha-sheet;
258  
259     .x-toolbar .x-toolbar-title {
260         color: saturate(lighten($active-color, 10%), 20%);
261         text-shadow: rgba(#fff, .8) 0 1px 20px;
262     }
263  
264     .x-tab-active img {
265         background: white none !important;
266     }
267  
268     .x-tabbar.x-docked-bottom .x-tab {
269         &amp;.x-tab-active {
270             -webkit-box-shadow: inset rgba(#000, .8) 0 0 5px !important;
271         }
272     }
273
274 ![Demo 3](demo3.png)
275
276 ### Next Steps & Extended Resources
277 We’ve really just touched on the power of theming in Sencha Touch, but already, with just a few small changes, we have radically changed the style of the base Sencha Touch theme. For other great examples of custom stylesheets, look at the Kiva and GeoCongress demos bundled with Sencha Touch. Also be sure to look out for my second article on the subject, “Optimizing Sencha Touch Themes,” where I show how we can take a full-fledged application and reduce the included CSS to under 50kb (with base64 encoded icons!).