This is an automated email from the ASF dual-hosted git repository.
carlosrovira pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/royale-docs.git
The following commit(s) were added to refs/heads/master by this push:
new 69f78d6 more improvements to jewel theme docs
69f78d6 is described below
commit 69f78d6c189b392b8adef5a1337973f04cf3a9c5
Author: Carlos Rovira <[email protected]>
AuthorDate: Sat Aug 10 18:31:52 2019 +0200
more improvements to jewel theme docs
---
component-sets/jewel/jewel-theme-creation.md | 62 +++++++++++++--------
component-sets/jewel/jewel-themes.md | 82 ++++++++++++++++++++++++++--
2 files changed, 118 insertions(+), 26 deletions(-)
diff --git a/component-sets/jewel/jewel-theme-creation.md
b/component-sets/jewel/jewel-theme-creation.md
index 60e4857..e20acad 100644
--- a/component-sets/jewel/jewel-theme-creation.md
+++ b/component-sets/jewel/jewel-theme-creation.md
@@ -28,39 +28,41 @@ Jewel is a component set designed with change of appearance
in mind. Jewel comes
Themes are a combination of files that define styles in [Cascading Style
Sheets
(CSS)](https://en.wikipedia.org/wiki/Cascading_Style_Sheets){:target='_blank'}
and other assets like images (JPG, PNG, SVG,...). In Jewel we use
[SASS](https://sass-lang.com){:target='_blank'} to define the CSS style rules
since is a preprocessor scripting language that is interpreted or compiled into
CSS.
-> Note that you can create your own theme without the need of SASS, since is
not obligatory, but we strongly recommend to use it for the same reason you use
AS3 instead of plain javascript
+> You can create your own theme without the need of SASS, since is not
obligatory, but we strongly recommend to use it for the same reason you use AS3
instead of plain javascript
-One of the advantages of using SASS is that we can organize style definitions
by separating styles into files. In Jewel we use a `.sass` file per component
so that in that file we will find all the definitions of that component.
+One of the advantages of using SASS is that we can organize style definitions
by separating styles into files. In Jewel we use a `.sass` file per component
so in that file we will find all the definitions of that component.
## Generation of default.css file
-`default.css` file is the resultant CSS file that compile and holds all CSS
definitions for Jewel. This file is generated by __SASS__ compiler. When the
library is compiled we use __SASS__ to generate
'src/main/resuorces/default.css` file as part of the build process.
+`default.css` file is the resultant CSS file that holds all CSS definitions
for a jewel theme. This file is generated by the SASS compiler. When a library
with styles in it is compiled we use SASS to generate
`src/main/resuorces/default.css` file as part of the build process.
-> Notice that SASS generation actually is only set up in Maven build, but not
in ANT. Apache Royale generates all default.css files in the SDK and make them
available to users using ANT. In the future we expect contributors add SASS
generation for ANT.
+> SASS generation actually is only set up in Maven build. Not in ANT build.
Apache Royale generates all `default.css` files in the SDK and make them
available to users using ANT, other build tools or IDEs. In the future we
expect contributors add SASS generation for ANT so ANT processes can trigger
the generation of CSS.
-### Jewel Library
+## Jewel Library
-Here you'll find the ActionScript classes that define each component and many
other support class files each component need in order to work properly. You'll
find a `sass` folder with a `.sass` file per component where all "structural"
definitions are defined. Those definitions can be normal _CSS rules_ or _royale
bead definition rules_.
+Here you'll find the [ActionScript](welcome/features/as3.html) classes that
define each component and many other support class files each component need in
order to work properly. You'll find a `sass` folder with a `.sass` file per
component where all _structural_ definitions are defined. Those definitions can
be normal _CSS rules_ or _royale bead definition rules_.
-By design, you'll never find any style rule in __Jewel library__ that define
_colors, lines, fonts, or shapes_. We'll find only the CSS rules that is needed
to generate each Jewel component visual structure (i.e: display, position,
z-index, overflow,...), and the default ActionScript bead classes that ship
with a concrete component per platform (i.e: BeadView, BeadModel,
BeadController, BeadLayout,...)
+By design, you'll never find any style rule in __Jewel library__ that define
_colors, lines, fonts, or shapes_ (those will be part of the theme so we'll
locate in the theme library). We'll find only the CSS rules that are needed to
generate each jewel component visual structure (i.e: display, position,
z-index, overflow,...), and the default ActionScript bead classes that ship
with a concrete component per platform (i.e: BeadView, BeadModel,
BeadController, BeadLayout,...)
-### Jewel Theme Library
+> Apache Royale uses CSS through all the framwework to link [beads to the
component strand](welcome/features/strands-and-beads.html) so components define
the default compositions of beads via CSS.
-This library is like a __Master Theme__ where _colors, fonts, icons or shapes_
are defined and is the library from wich the rest of Jewel theme variants are
generated thanks to SASS preprocess power. Each Jewel Theme in Royale use the
definitions in Jewel Theme library and just change a few variables to generate
the variants.
+## Jewel Theme Library
-### Primary, Secondary and Emphasized colors
+This library is like a __master theme__ where _colors, fonts, icons or shapes_
are defined and is the library from wich the rest of Jewel theme variants are
generated thanks to SASS preprocess power. Each jewel theme in Apache Royale
use the definitions in this jewel theme library and [just change a few
variables to generate the
variants](component-sets/jewel/jewel-theme-creation.html#theme-sass-file)
-Since Jewel Themes support 3 diferent colors __Primary__, __Secondary__ and
__Emphasized__, then the __Jewel Theme Library__ folder structure is the
following:
+## Primary, Secondary and Emphasized colors
-* For __Primary__ color: `sass/components-primary`
-* For __Secondary__ color: `sass/components-secondary`
-* For __Emphasized__ color: `sass/components-empahsized`
+Since jewel themes support 3 diferent colors: __Primary__, __Secondary__ and
__Emphasized__, then the __Jewel Theme Library__ folder structure is the
following:
-`primary` folder holds primary and default colors and is used by most of the
components in Jewel, while `secondary` and `emphasized` folder is only used for
some of them (i.e: Button, Badge or SnackBar).
+* For __Primary__ color: `sass/components-primary` for styles that use primary
and default colors.
+* For __Secondary__ color: `sass/components-secondary` for styles that use
secondary colors.
+* For __Emphasized__ color: `sass/components-empahsized` for styles that use
emphasized colors.
-### Theme SASS file
+`primary` is used by most of the components in Jewel, while `secondary` and
`emphasized` is only used for some of them (i.e: Button, Badge or SnackBar)
that could need these variants.
-`_theme.sass` is the SASS file where we can make Jewel Themes take significant
visual changes. It's a very simple configuration file with 5 variables that
SASS will use when we want to generate `default.css` file.
+## Theme SASS file
+
+`sass/_theme.sass` is the SASS file where we can make jewel themes take
significant visual changes. It's a very simple configuration file with few
variables that SASS will use when we want to generate a `default.css` file.
This is essentialy what each of the jewel themes that comes with Apache Royale
defines in a different way.
@@ -75,11 +77,13 @@ $secondary-color: $topaz
$emphasized-color: $emerald
```
+so this `_theme.sass` file will create a jewel theme variant that will look
_no-flat_ and _light_, with _blue as primary color_, _topaz as secondary color_
and _emerald as emphasized color_.
+
## Jewel Theme Summary
-So, in summary, __Jewel library__ has defintions that normally users does not
need to change, while __Jewel Theme library__ is like a master theme for all
royale jewel themes and a good starting point to create a new user define jewel
theme or just modify one of the ones that comes with the royale distribution.
+So, in summary, __Jewel library__ has defintions that normally users does not
need to change, while __Jewel Theme library__ is like a __master theme__ for
all royale jewel themes and a good starting point to create a new user defined
jewel theme or just modify one of the ones that comes with the royale
distribution.
-> A user should just need to duplicate Jewel Theme library to start modify
each style per jewel component.
+> A user should just need to duplicate the __Jewel Theme Library__ to start
modifing each style per jewel component to create a new custom jewel theme.
## Looking to a concrete jewel component as an example
@@ -88,7 +92,7 @@ Lets take [Jewel
Alert](component-sets/jewel/jewel-alert.html) component as an e
In __Jewel library__ you can find:
*
[org.apache.royale.jewel.Alert](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel/Alert){:target='_blank'}:
This is the main __Alert__ component file
-* `sass/components/_alert.sass`: This is the main __Alert__ SASS definition
that holds all structural CSS rules and the default beads for Alert. The beads
defined here for Javascript platform are:
+* `sass/components/_alert.sass`: This is the main __Alert__ SASS definition
that holds all structural CSS rules and the default beads for Alert. The beads
defined here for the __javascript platform__ are:
```sass
j|Alert
@@ -98,10 +102,24 @@ j|Alert
IBeadView: ClassReference("org.apache.royale.jewel.beads.views.AlertView")
```
+Regarding the CSS selectors for Alert: The main `.as` file (in this case
`Alert.as`) will assign a css selector to the `typeNames` variable:
+
+```as3
+ typeNames = "jewel alert";
+```
+
+In the `sass` file you'll find the corresponding CSS selector
+
+```sass
+ .jewel.alert
+```
+
+and nested in that selector you'll find the corresponding tree of rules and
selectors for that component.
+
So __Alert__ is composed by four Actionscript files and one `.sass` files that
wire the component with its beads and setup a set of CSS rules to give a
concrete CSS structrure, but does not define colors, gradients, shapes or icons
for Alert. All of this will be found in the theme.
In __Jewel Theme library__ you can find:
-* `sass/components-primary/_alert.sass`: This is the main __Alert__ SASS theme
definition that holds all theme CSS rules. Here you can find colors, gradients,
line styles and other visual things that will affect how the __Alert__
component is presented to the user.
+* `sass/components-primary/_alert.sass`: This is the main __Alert__ SASS theme
definition that holds all theme CSS rules. Here you can find colors, gradients,
line styles and other visual things that will affect how the __Alert__
component is presented to the user. All those styles will be found inside a
`.jewel.alert` CSS selector.
-This component doesn't define any `secondary` or `emphasized` color.
\ No newline at end of file
+In this case, `Alert` component doesn't define any `secondary` or `emphasized`
color.
diff --git a/component-sets/jewel/jewel-themes.md
b/component-sets/jewel/jewel-themes.md
index 1aa4159..4199aec 100644
--- a/component-sets/jewel/jewel-themes.md
+++ b/component-sets/jewel/jewel-themes.md
@@ -20,17 +20,38 @@ title: Jewel Themes
# Jewel Themes
-The look and feel of the component set
+The look and feel of the jewel component set
-Jewel UI Set focus themes. Themes provides the capability of change the
appearance of _all_ components at once.
-A theme is a predefined CSS file (and optionally a other assets like images)
that holds the definitions of each Jewel component and its subcomponents a long
the default beads used to configure that components.
+Jewel component set focus on themes. Themes provides the capability of change
the appearance of _all_ components at once.
+A theme is a predefined CSS file (and optionally a other assets like images)
that holds the definitions of each Jewel component, its subcomponents and the
default [beads](welcome/features/strands-and-beads.html) used to configure that
components.
Royale use the theme to add the right css selectors to the final compilation
so when the user loads the application the required css and other files are
loaded and the application shows a concrete look and feel.
+## Colors
+
Jewel comes with predefined themes based on the 12 color wheel below:
+Current colors are:
+
+| Color | HEX |
+| --------- | --------- |
+| Red | #EC1C24 |
+| Topaz | #EF5A2A |
+| Orange | #F7941D |
+| Sunflower | #F8B13F |
+| Yellow | #E2D70B |
+| Emerald | #8CC63C |
+| Green | #3AB549 |
+| Turquoise | #29A89F |
+| Blue | #3CADF1 |
+| Sapphire | #2C74BE |
+| Violet | #662C90 |
+| Amethyst | #C92CC6 |
+
+## Light / Dark and Flat / No-Flat
+
Jewel has been designed to cover multiple visual needs and support Light/Dark
and Flat/No Flat themes:
{:height="80%"
width="80%"}
@@ -50,4 +71,57 @@ Light/Flat
Dark/Flat
<br><br>
-Jewel Themes are mostly a CSS with all needed CSS rules predefined. We create
this CSSs using the Jewel SASS Theme framework located in JewelTheme project.
So updating rules in this theme, we can recompile all themes to update it with
the latest changes.
\ No newline at end of file
+Jewel Themes are a CSS file in the end (`default.css`), with all needed CSS
rules predefined. We create this CSSs using the __Jewel SASS Theme framework__
located in __JewelTheme__ project. By udating the rules in this theme project,
we can recompile all predefined jewel themes in Apache Royale to update those
themes with the latest changes.
+
+## Predefined Jewel Themes
+
+Jewel library has a __master theme__ called JewelTheme and other 144 themes in
the `themes` folder that are generated from JewelTheme. You can know more about
how this is done in the [Jewel Theme
Creation](component-sets/jewel/jewel-theme-creation.html) section.
+
+Only to name a few examples, `themes/Jewel-Dark-NoFlat-Primary-Violet-Theme`
or `themes/Jewel-Light-NoFlat-Secondary-Emerald-Theme` are examples of concrete
jewel themes that are part of Apache Royale official distribution. There's 144
unique themes that are the combinations of the 12 colors, dark/light and
flat/no-flat options.
+
+## Using Jewel Themes
+
+Users will use one up to three of the predefined jewel themes in `themes`
folder in a normal Application project: one for primary color, one for
secondary color and one for emphasized color (i.e:
`themes/Jewel-Light-NoFlat-Primary-Blue-Theme`,
`themes/Jewel-Light-NoFlat-Secondary-Topaz-Theme` and finally
`themes/Jewel-Light-NoFlat-Secondary-Emerald-Theme`).
+
+Example for maven pom.xml configuration:
+
+```xml
+ <dependency>
+ <groupId>org.apache.royale.framework</groupId>
+ <artifactId>Jewel-Light-NoFlat-Primary-Blue-Theme</artifactId>
+ <version>0.9.6-SNAPSHOT</version>
+ <type>swc</type>
+ <scope>theme</scope>
+ <classifier>js</classifier>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.royale.framework</groupId>
+ <artifactId>Jewel-Light-NoFlat-Secondary-Topaz-Theme</artifactId>
+ <version>0.9.6-SNAPSHOT</version>
+ <type>swc</type>
+ <scope>theme</scope>
+ <classifier>js</classifier>
+ </dependency>
+ <dependency>
+ <groupId>org.apache.royale.framework</groupId>
+ <artifactId>Jewel-Light-NoFlat-Emphasized-Emerald-Theme</artifactId>
+ <version>0.9.6-SNAPSHOT</version>
+ <type>swc</type>
+ <scope>theme</scope>
+ </dependency>
+```
+
+Other option is to use the __Jewel Theme Library__ that provides all styles
for primary, secondary and emphasized colors and configure these colors in its
`_theme.sass file`.
+
+Example for maven pom.xml configuration:
+
+```xml
+ <dependency>
+ <groupId>org.apache.royale.framework</groupId>
+ <artifactId>JewelTheme</artifactId>
+ <version>0.9.6-SNAPSHOT</version>
+ <type>swc</type>
+ <scope>theme</scope>
+ <classifier>js</classifier>
+ </dependency>
+```
\ No newline at end of file
