X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/6746dc89c47ed01b165cc1152533605f97eb8e8d..f562e4c6e5fac7bcb445985b99acbea4d706e6f0:/docs/guides/theming/README.md?ds=sidebyside diff --git a/docs/guides/theming/README.md b/docs/guides/theming/README.md new file mode 100644 index 00000000..9d54cb75 --- /dev/null +++ b/docs/guides/theming/README.md @@ -0,0 +1,316 @@ +# Theming + +Ext JS 4 has a brand new theming system to customize the look of your application while still supporting all browsers. + +## A Brief Introduction to SASS & Compass + +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: + + $blue: #3bbfce; + $margin: 16px; + + .content-navigation { + border-color: $blue; + color: darken($blue, 9%); + } + + .border { + padding: $margin / 2; + margin: $margin / 2; + border-color: $blue; + } + +And it will compile to: + + .content-navigation { + border-color: #3bbfce; + color: #2b9eab; + } + + .border { + padding: 8px; + margin: 8px; + border-color: #3bbfce; + } + +To see the wide variety of other features available in SASS, please see [http://sass-lang.com/](http://sass-lang.com/). Compass extends SASS by adding a variety of CSS3 mixins and providing the extension system that Ext JS leverages. With Compass, one can include rules like: + + $boxheight: 10em; + + .mybox { + @include border-radius($boxheight/4); + } + +Which compiles into: + + .mybox { + -webkit-border-radius: 2.5em; + -moz-border-radius: 2.5em; + -o-border-radius: 2.5em; + -ms-border-radius: 2.5em; + -khtml-border-radius: 2.5em; + border-radius: 2.5em; + } + +You can learn more about the pre-included mixins with Compass and the other tools it provides here: [http://compass-style.org/docs/](http://compass-style.org/docs/). + +## Requirements + +### Ruby + +#### Mac OSX + +XCode installs Ruby and all necessary dependencies to your Mac when installed. + +Xcode can be found on the Apple Developer Website: [http://developer.apple.com/xcode/](http://developer.apple.com/xcode/) + +#### Windows + +Visit [http://rubyinstaller.org/](http://rubyinstaller.org/) and download the latest packaged version of Ruby (1.9.2 at the time of writing) + +### Compass/SASS gem + +#### Mac OSX + +In `/Applications/Utilities/Terminal.app`, run the following code (you will be asked for your password): + + sudo gem install compass + +You can verify you have Compass and Sass installed by running the following in `Terminal.app`: + + compass -v + + sass -v + +At the time of writing, the latest version of Compass is `0.11.1 (Antares)`. The latest version of Sass is `3.1.1 (Brainy Betty)` + +#### Windows + +Select **Start Command Prompt with Ruby** from the new Start Menu option. + +Type the following: + + gem install compass + +You can verify you have Compass and Sass installed by running the following in **Terminal.app**: + + compass -v + sass -v + +At the time of writing, the latest version of Compass is `0.11.1 (Antares)`. The latest version of Sass is `3.1.1 (Brainy Betty)` + +## Directory Structure + +The Ext JS SDK comes with a template which can be used as a base for your new theme. If you followed the [Getting Started](#/guide/getting_started) guide, you should have a directory for your application with a subfolder `extjs` containing the Ext JS SDK. It should look something like this: + + appname/ + appname/extjs/ + appname/app.js + appname/index.html + +Copy the template resources folder from `appname/extjs/resources/themes/templates/resource` to your root application folder: + + appname/ + appname/resources/ + appname/resources/css/ + appname/resources/sass/ + appname/resources/sass/config.rb + appname/resources/sass/my-ext-theme.sass + +You will also need to copy the images from `appname/extjs/resources/themes/images/default` to `appname/resources/images`. + +Ensure the path to your Ext JS folder is correct in `appname/resources/sass/config.rb`: + + # $ext_path: This should be the path of the Ext JS SDK relative to this file + $ext_path = "../../extjs" + +Due to a bug in Ext JS 4.0.2a you will also need to edit line 62 of `appname/extjs/resources/themes/lib/utils.rb` from this: + + images_path = File.join($ext_path, 'resources', 'themes', 'images', theme) + +to this: + + images_path = relative_path + +This ensures images will be served from `appname/resources/images` rather than `appname/extjs/resources/images` + +## Compiling your CSS + +Compiling your CSS is a simple process using Compass. + +First, change to your sass directory in `appname/resources/sass`, then run the following command in **Terminal.app on Mac OSX** or **Command Prompt on Windows**: + + > compass compile + +This should output the following: + + > create ../css/my-ext-theme.css + +Your minified css file should now be in `appname/resources/css/my-ext-theme.css`. + +## Changing global SASS variables + +The Ext JS theming system comes with global SASS variables which you can use to change the look of your application with a few lines of code. + +These SASS variables can be added to your `appname/resources/sass/my-ext-theme.scss` file, but they **must** be inserted before the call to `@import 'ext4/default/all'`. You can see an example commented out at the top of your `my-ext-theme.scss` file: + + // Insert your custom variables here. + // $base-color: #aa0000; + +Try uncommenting this line and changing the base-color to something else, perhaps the green #a1c148. + +Now regenerate your theme by navigating to `appname/resources/sass` and running `compass compile` + +### Available Variables + +Navigate to `appname/extjs/resources/themes/stylesheets/ext4/default/variables` directory. This directory contains all defined variables for each component in Ext JS 4. + +The naming convention for variables follows CSS property names, prepends by the component name. For example: + +- **Panel border radius** + - CSS Property: `border-radius` + - Variable: ``$panel-border-radius`` + +- **Panel body background color** + - CSS Property: `background-color` + - Variable: `$panel-body-background-color` + +- **Toolbar background color** + - CSS Property: `background-color` + - Variable: `$toolbar-background-color` + +You can copy any of these variables and add them to your `appname/resources/sass/my-ext-theme.scss` file **before** the `@import 'ext4/default/all'` line. + +## View the Results + +To view your new theme, lets overwrite `app.js` with the Theme example from the main SDK. This example shows most Ext JS components on a single page. Copy `appname/extjs/examples/themes/themes.js` to `appname/app.js`. + +Update `appname/index.html` to the following: + + +
+