X-Git-Url: http://git.ithinksw.org/extjs.git/blobdiff_plain/3789b528d8dd8aad4558e38e22d775bcab1cbd36..6746dc89c47ed01b165cc1152533605f97eb8e8d:/docs/guides/theming/README.js diff --git a/docs/guides/theming/README.js b/docs/guides/theming/README.js index d26a3571..39b797d2 100644 --- a/docs/guides/theming/README.js +++ b/docs/guides/theming/README.js @@ -1,3 +1,3 @@ Ext.data.JsonP.theming({ - "guide": "
Ext JS 4 has a brand new theming system to customize the look of you application which still supporting all browsers.
\n\nSASS 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:
\n\n$blue: #3bbfce;\n$margin: 16px;\n\n.content-navigation {\n border-color: $blue;\n color: darken($blue, 9%);\n}\n\n.border {\n padding: $margin / 2;\n margin: $margin / 2;\n border-color: $blue;\n}\n
\n\nAnd it will compile to:
\n\n.content-navigation {\n border-color: #3bbfce;\n color: #2b9eab;\n}\n\n.border {\n padding: 8px;\n margin: 8px;\n border-color: #3bbfce;\n}\n
\n\nTo 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:
\n\n$boxheight: 10em;\n\n.mybox {\n @include border-radius($boxheight/4);\n}\n
\n\nWhich compiles into:
\n\n.mybox {\n -webkit-border-radius: 2.5em;\n -moz-border-radius: 2.5em;\n -o-border-radius: 2.5em;\n -ms-border-radius: 2.5em;\n -khtml-border-radius: 2.5em;\n border-radius: 2.5em;\n}\n
\n\nYou can learn more about the pre-included mixins with Compass and the other tools which it provides here: http://compass-style.org/docs/.
\n\nXCode installs Ruby and all necessary dependancies onto your Mac when installed.
\n\nXcode can be found on the Apple Developer Website: http://developer.apple.com/xcode/
\n\nVisit http://rubyinstaller.org/ and download the latest packaged version of Ruby (1.9.2 at the time of writing this)
\n\nIn /Applications/Utilities/Terminal.app, run the following code (you will be asked for your password):
\n\nsudo gem install compass\n
\n\nYou can verify you have Compass and Sass installed by running the following in Terminal.app:
\n\ncompass -v\n\nsass -v\n
\n\nAt the time of writing this, the latest version of Compass is 0.11.1 (Antares)
. The latest version of Sass is 3.1.1 (Brainy Betty)
Select Start Command Prompt with Ruby from the new Start Menu option.
\n\nType the following:
\n\ngem install compass\n
\n\nYou can verify you have Compass and Sass installed by running the following in Terminal.app:
\n\n`compass -v`\n`sass -v`\n
\n\nAt the time of writing this, the latest version of Compass is 0.11.1 (Antares)
. The latest version of Sass is 3.1.1 (Brainy Betty)
The Ext JS SDK comes with a template which can be used as a base for your new theme. You can find this in the /resources/themes/templates
folder.
Everything in the included resources
directory should be moved into your applications root folder:
<application-root>/\n<application-root>/resources/\n<application-root>/resources/css/\n<application-root>/resources/sass/\n<application-root>/resources/sass/config.rb\n<application-root>/resources/images/\n
\n\nYou also must ensure the Ext JS SDK is in the correct location:
\n\n<application-root>/lib/Ext JS\n<application-root>/lib/Ext JS/ext-all.js\n<application-root>/lib/Ext JS/resources/\n<application-root>/lib/Ext JS/...\n
\n\nIf for some reason the Ext JS SDK is located elsewhere, you must also change the path in resources/sass/config.rb:
\n\n# $ext_path: This should be the path of where the Ext JS SDK is installed\n# Generally this will be in a lib/Ext JS folder in your applications root\n# <root>/lib/Ext JS\n$ext_path = \"../../lib/Ext JS\"\n
\n\nCompiling your CSS is a very simple process using Compass.
\n\nFrom applications root directory, run the following command in Terminal.app on Mac OSX or Command Prompt on Windows:
\n\n\n\ncompass compile resources/sass
This should output the following:
\n\n\n\ncreate resources/sass/../css/my-ext-theme.css
That is your CSS compiled! You can now view it in the resources/css
folder.
You can also setup Compass to watch your SASS directory and compile the CSS when you make a change:
\n\n\n\ncompass watch resources/sass
The Ext JS theming system comes with a few basic global SASS variables which you can use to change the whole look of your application with just a few lines of code.
\n\nThese SASS variables can be added in your .scss file, but they must be inserted before the call to @import the Ext JS4 framework is called. You can see an example of this in the my-ext-theme.scss file, in the templates/resources/sass folder:
\n\n// Unless you want to include all components, you must set $include-default to false\n// IF you set this to true, you can also remove lines 10 to 38 of this file\n$include-default: false;\n\n// Insert your custom variables here.\n$base-color: #aa0000;\n\n@import 'ext4/default/all';\n
\n\nIn this case, both$include-default
and $base-color
are being changed - and then the Ext JS4 theming files are being imported.
Unfortunately at this time there is not a complete list of all available variables in the theme, however you can easily find variables that are available by navigating to the resources/themes/stylesheets/ext4/default/variables
directory. This directory contains all defined variables for each component in Ext JS4.
The naming convention for variables follows CSS property names, prepends by the component name. For example:
\n\nPanel border radius
\n CSS Property: border-radius
\n Variable: $panel-border-radius
Panel body background color
\n CSS Property: background-color
\n Variable: $panel-body-background-color
Toolbar background color
\n CSS Property: background-color
\n Variable: $toolbar-background-color
Every component in the Ext JS framework has a ui
configuration (which defaults to default
). This property can be changed to allow components in your application to have different styles.
The ui
of any component can be changed at anytime, even after render, by using the setUI
method. An example of this can be found in examples/panel/bubble-panel.html
.
Some Ext JS components have SASS @mixin
's which allow you to quickly generate new UIs. These include: Ext.panel.Panel
, Ext.button.Button
, Ext.Toolbar
and Ext.window.Window
.
To create these new UIs is extremely simple. Simple call the associated @mixin
(found in the documentation) for the component you want to create a new UI for.
Lets look at the Panel @mixin
as an example (example can be found in examples/panel/bubble-panel/sass/bubble-panel.scss
):
@include Ext JS-panel-ui(\n 'bubble',\n\n $ui-header-font-size: 12px,\n $ui-header-font-weight: bold,\n $ui-header-color: #0D2A59,\n $ui-header-background-color: #fff,\n $ui-header-background-gradient: null,\n\n $ui-border-color: #fff,\n $ui-border-radius: 4px,\n $ui-body-background-color: #fff,\n $ui-body-font-size: 14px\n);\n
\n\nThe above code will create a new ui
for any Ext.panel.Panel component, which you can then use in your application by specifiying the ui
configuration:
Ext.create('widget.panel', {\n ui: 'bubble',\n width: 300,\n height: 300,\n title: 'Panel with a bubble UI!'\n});\n
\n\nIn most cases when creating new UI's, you will want to include background gradients or rounded corners. Unfortunately legacy browsers do not support the corresponding CSS3 properties to do this, so we must use images.
\n\nFortunately with Ext JS 4, we have included a Slicing tool which does this for you. You simply pass it a manifest file of your new UI's (if you have created any) and run the tool from the command line - and you're done!
\n\nThe slicing tool creates a new browser instance, which loads Ext JS and a specified CSS file. Once loaded, it parses a JavaScript file which includes every Ext JS component that needs styled (panel, window, toolbar, etc.). It then analyzes each of those components and determines the size and location of each image that needs sliced. It then slices each of the images and sprites them together, and saves them in the location defined in the manifest.
\n\nThe slicer itself is a command line tool which is installed as part of the SDK Tools package, which can be run by calling sencha slice theme
from the command line. Example usage:
sencha slice theme -d ~/Downloads/ext-4.0 -c mytheme.css -o mytheme -v\n
\n\nIt accepts several arguments:
\n\n--css[=]value, -c[=]value
\n\nThe path to your theme's complete CSS file, e.g., ext-all-access.css. Uses\nthe default Ext JS 4 theme CSS if not provided.
--ext-dir[=]value, -d[=]value (required)
\n\nThe path to the root of your Ext JS 4 SDK directory.
--manifest[=]value, -m[=]value
\n\nThe path to your Theme Generator JSON manifest file, e.g., manifest.json.\nUses the default packaged manifest if not provided.
--output-dir[=]value, -o[=]value
\n\nThe destination path to save all generated theme images. This should be inside the
resources/themes/images/<themename>/
directory.\nDefaults to the current working directory.
--verbose, -v
\n\nDisplay a message for every image that is generated.
Compile your CSS
\n\nYou must ensure your SASS theme file has been compiled as this is used for the slicer. Passing no CSS file would result in the slicer to revert to the default ext-all.css file, which would be pointless in most cases.
Creating your manifest file (optional)
\n\nThe manifest file is a simple JavaScript file which tells the Slicing tool which custom UI's you want to slice. This step is only neseccary when you have created new UI's.
\n\nLet's look at the bubble panel example again:
\n\nExt.onReady(function() {\n Ext.manifest = {\n widgets: [\n {\n xtype: 'widget.header',\n ui : 'bubble'\n },\n {\n xtype: 'widget.panel',\n ui : 'bubble'\n }\n ]\n };\n});\n
\n\nAs you can see, you define an Object called Ext.manifest
and give it an Array property called widgets
. In this Array, you should insert an object containing the xtype
and the ui
of the component you want to generate the images for.
It is important that the Ext.manifest
Object is defined inside the Ext.onReady
method.
Generating your images
\n\nNow all that is left is to run the command, including the arguments to the Ext JS SDK folder, your theme CSS file and the output directory of the sliced images.
\n\n sencha slice theme -d ~/Downloads/ext-4.0 -c mytheme.css -o mytheme -v\n
I am getting a 'error resources/sass/my-ext-theme.scss (Line 8: File to import not found or unreadable: ext4/default/all)
' error when I compile?
This is because Compass cannot file the Ext JS 4 theme files. Ensure the
$ext_path
in thesass/config.rb
file is correct.
Please check back soon
\n" + "guide": "Ext JS 4 has a brand new theming system to customize the look of your application while still supporting all browsers.
\n\nSASS 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:
\n\n$blue: #3bbfce;\n$margin: 16px;\n\n.content-navigation {\n border-color: $blue;\n color: darken($blue, 9%);\n}\n\n.border {\n padding: $margin / 2;\n margin: $margin / 2;\n border-color: $blue;\n}\n
\n\nAnd it will compile to:
\n\n.content-navigation {\n border-color: #3bbfce;\n color: #2b9eab;\n}\n\n.border {\n padding: 8px;\n margin: 8px;\n border-color: #3bbfce;\n}\n
\n\nTo 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:
\n\n$boxheight: 10em;\n\n.mybox {\n @include border-radius($boxheight/4);\n}\n
\n\nWhich compiles into:
\n\n.mybox {\n -webkit-border-radius: 2.5em;\n -moz-border-radius: 2.5em;\n -o-border-radius: 2.5em;\n -ms-border-radius: 2.5em;\n -khtml-border-radius: 2.5em;\n border-radius: 2.5em;\n}\n
\n\nYou can learn more about the pre-included mixins with Compass and the other tools it provides here: http://compass-style.org/docs/.
\n\nXCode installs Ruby and all necessary dependencies to your Mac when installed.
\n\nXcode can be found on the Apple Developer Website: http://developer.apple.com/xcode/
\n\nVisit http://rubyinstaller.org/ and download the latest packaged version of Ruby (1.9.2 at the time of writing)
\n\nIn /Applications/Utilities/Terminal.app
, run the following code (you will be asked for your password):
sudo gem install compass\n
\n\nYou can verify you have Compass and Sass installed by running the following in Terminal.app
:
compass -v\n\nsass -v\n
\n\nAt 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)
Select Start Command Prompt with Ruby from the new Start Menu option.
\n\nType the following:
\n\ngem install compass\n
\n\nYou can verify you have Compass and Sass installed by running the following in Terminal.app:
\n\ncompass -v\nsass -v\n
\n\nAt 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)
The Ext JS SDK comes with a template which can be used as a base for your new theme. You can find this in the /resources/themes/templates
folder.
Everything in the included resources
directory should be moved to your application's root folder:
<application-root>/\n<application-root>/resources/\n<application-root>/resources/css/\n<application-root>/resources/sass/\n<application-root>/resources/sass/config.rb\n<application-root>/resources/images/\n
\n\nYou must also ensure the Ext JS SDK is in the correct location:
\n\n<application-root>/lib/Ext JS\n<application-root>/lib/Ext JS/ext-all.js\n<application-root>/lib/Ext JS/resources/\n<application-root>/lib/Ext JS/...\n
\n\nIf for some reason the Ext JS SDK is located elsewhere, you must also change the path in resources/sass/config.rb:
\n\n# $ext_path: This should be the path of where the Ext JS SDK is installed\n# Generally this will be in a lib/Ext JS folder in your applications root\n# <root>/lib/Ext JS\n$ext_path = \"../../lib/Ext JS\"\n
\n\nCompiling your CSS is a very simple process using Compass.
\n\nFrom the application root directory, run the following command in Terminal.app on Mac OSX or Command Prompt on Windows:
\n\n> compass compile resources/sass\n
\n\nThis should output the following:
\n\n> create resources/sass/../css/my-ext-theme.css\n
\n\nThat is your CSS compiled! You can now view it in the resources/css
folder.
You can also setup Compass to watch your SASS directory and compile the CSS when you make a change:
\n\n> compass watch resources/sass\n
\n\nThe Ext JS theming system comes with a few basic global SASS variables which you can use to change the whole look of your application with just a few lines of code.
\n\nThese SASS variables can be added in your .scss file, but they must be inserted before the call to @import 'ext4/default/all'
. You can see an example of this in the my-ext-theme.scss file, in the templates/resources/sass folder:
// Unless you want to include all components, you must set $include-default to false\n// IF you set this to true, you can also remove lines 10 to 38 of this file\n$include-default: false;\n\n// Insert your custom variables here.\n$base-color: #aa0000;\n\n@import 'ext4/default/all';\n
\n\nIn this case, both $include-default
and $base-color
are being changed. Then the Ext JS 4 theming files are imported.
You can easily find variables that are available by navigating to the 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:
\n\nPanel border radius
\n CSS Property: border-radius
\n Variable: $panel-border-radius
Panel body background color
\n CSS Property: background-color
\n Variable: $panel-body-background-color
Toolbar background color
\n CSS Property: background-color
\n Variable: $toolbar-background-color
Every component in the Ext JS framework has a ui
configuration (which defaults to default
). This property can be changed to allow components in your application to have different styles.
The ui
of any component can be changed at any time, even after render, by using the setUI
method. An example of this can be found in examples/panel/bubble-panel.html
.
Some Ext JS components have SASS @mixin
's which allow you to quickly generate new UIs. These include: Ext.panel.Panel
, Ext.button.Button
, Ext.Toolbar
and Ext.window.Window
.
Creating these new UIs is simple. Simply call the associated @mixin
(found in the documentation) for the component you want to create a new UI for.
Lets look at the Panel @mixin
as an example (which can be found in examples/panel/bubble-panel/sass/bubble-panel.scss
):
@include Ext JS-panel-ui(\n 'bubble',\n\n $ui-header-font-size: 12px,\n $ui-header-font-weight: bold,\n $ui-header-color: #0D2A59,\n $ui-header-background-color: #fff,\n $ui-header-background-gradient: null,\n\n $ui-border-color: #fff,\n $ui-border-radius: 4px,\n $ui-body-background-color: #fff,\n $ui-body-font-size: 14px\n);\n
\n\nThe above code will create a new ui
for any Ext.panel.Panel component, which you can then use in your application by specifying the ui
configuration:
Ext.create('widget.panel', {\n ui: 'bubble',\n width: 300,\n height: 300,\n title: 'Panel with a bubble UI!'\n});\n
\n\nIn most cases when creating new UI's, you will want to include background gradients or rounded corners. Unfortunately legacy browsers do not support the corresponding CSS3 properties, so we must use images instead.
\n\nWith Ext JS 4, we have included a Slicing tool which does the hard work for you. Simply pass it a manifest file of your new UI's (if you have created any) and run the tool from the command line.
\n\nThe slicing tool creates a new browser instance, which loads Ext JS and a specified CSS file. Once loaded, it parses a JavaScript file which includes every Ext JS component that needs styling (panel, window, toolbar, etc.). It then analyzes each of those components and determines the size and location of each image that needs to be sliced. It then slices each of the images, sprites them together and saves them in the location defined in the manifest.
\n\nThe slicer too itself can be run from the command line and is installed as part of the SDK Tools package. It can be run by calling sencha slice theme
. Example usage:
sencha slice theme -d ~/Downloads/ext-4.0 -c mytheme.css -o mytheme -v\n
\n\nIt accepts several arguments:
\n\n--css[=]value, -c[=]value
\n\nThe path to your theme's complete CSS file, e.g., ext-all-access.css. Uses\nthe default Ext JS 4 theme CSS if not provided.
--ext-dir[=]value, -d[=]value (required)
\n\nThe path to the root of your Ext JS 4 SDK directory.
--manifest[=]value, -m[=]value
\n\nThe path to your Theme Generator JSON manifest file, e.g., manifest.json.\nUses the default packaged manifest if not provided.
--output-dir[=]value, -o[=]value
\n\nThe destination path to save all generated theme images. This should be inside the
resources/themes/images/<themename>/
directory.\nDefaults to the current working directory.
--verbose, -v
\n\nDisplay a message for every image that is generated.
Compile your CSS
\n\nYou must ensure your SASS theme file has been compiled as this is used for the slicer. Passing no CSS file would result in the slicer to revert to the default ext-all.css file, which would be pointless in most cases.
Creating your manifest file (optional)
\n\nThe manifest file is a simple JavaScript file which tells the Slicing tool which custom UI's you would like to slice. This step is only necessary when you have created new UI's.
\n\nLet's look at the bubble panel example again:
\n\nExt.onReady(function() {\n Ext.manifest = {\n widgets: [\n {\n xtype: 'widget.header',\n ui : 'bubble'\n },\n {\n xtype: 'widget.panel',\n ui : 'bubble'\n }\n ]\n };\n});\n
\n\nAs you can see, you define an Object called Ext.manifest
and give it an Array property called widgets
. In this Array you should insert an object containing the xtype
and ui
of the component you want to generate the images for.
It is important that the Ext.manifest
Object is defined inside the Ext.onReady
method.
Generating your images
\n\nNow all that is left is to run the command, including the arguments to the Ext JS SDK folder, your theme CSS file and the output directory of the sliced images.
\n\n sencha slice theme -d ~/Downloads/ext-4.0 -c mytheme.css -o mytheme -v\n
I am getting a 'error resources/sass/my-ext-theme.scss (Line 8: File to import not found or unreadable: ext4/default/all)
' error when I compile?
This is because Compass cannot file the Ext JS 4 theme files. Ensure the
$ext_path
in thesass/config.rb
file is correct.