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 f8d4125 Jewel Theme creation docs
f8d4125 is described below
commit f8d41257be22eff960069d99d8d334d3913b9298
Author: Carlos Rovira <[email protected]>
AuthorDate: Sat Aug 10 13:09:09 2019 +0200
Jewel Theme creation docs
---
_data/toc.json | 3 +
component-sets/jewel/jewel-theme-creation.md | 107 +++++++++++++++++++++++++++
2 files changed, 110 insertions(+)
diff --git a/_data/toc.json b/_data/toc.json
index 56acfa3..957d70c 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -152,6 +152,9 @@
},
{
"path": "component-sets/jewel/jewel-themes.md"
+ },
+ {
+ "path":
"component-sets/jewel/jewel-theme-creation.md"
}
]
}
diff --git a/component-sets/jewel/jewel-theme-creation.md
b/component-sets/jewel/jewel-theme-creation.md
new file mode 100644
index 0000000..60e4857
--- /dev/null
+++ b/component-sets/jewel/jewel-theme-creation.md
@@ -0,0 +1,107 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Jewel Theme Creation
+---
+
+# Jewel Theme Creation
+
+How to make a new Theme for Jewel
+
+Jewel is a component set designed with change of appearance in mind. Jewel
comes with a series of pre designed themes so it can be used directly without
the need for the user to create their own appearance. You can know more about
those themes [here](component-sets/jewel/jewel-themes.html). The Jewel Themes
that comes with Apache Royale define 12 colors, dark and light, flat / no-flat
visuals. However, on many occasions users will want a personalized look, either
adapting one of the them [...]
+
+## Theme Basics
+
+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
+
+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.
+
+## 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.
+
+> 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.
+
+### 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_.
+
+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,...)
+
+### Jewel Theme Library
+
+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.
+
+### Primary, Secondary and Emphasized colors
+
+Since Jewel Themes support 3 diferent colors __Primary__, __Secondary__ and
__Emphasized__, then the __Jewel Theme Library__ folder structure is the
following:
+
+* For __Primary__ color: `sass/components-primary`
+* For __Secondary__ color: `sass/components-secondary`
+* For __Emphasized__ color: `sass/components-empahsized`
+
+`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).
+
+### Theme SASS file
+
+`_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.
+
+This is essentialy what each of the jewel themes that comes with Apache Royale
defines in a different way.
+
+For example, by default, we can find:
+
+```sass
+//Theme variables (Flat/No Flat - Dark/Light - Primary/Secondary/Emphasized
Color
+$flat: false
+$dark: false
+$primary-color: $blue
+$secondary-color: $topaz
+$emphasized-color: $emerald
+```
+
+## 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.
+
+> A user should just need to duplicate Jewel Theme library to start modify
each style per jewel component.
+
+## Looking to a concrete jewel component as an example
+
+Lets take [Jewel Alert](component-sets/jewel/jewel-alert.html) component as an
example to help us to visualize the different files that compose this concrete
component:
+
+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
+j|Alert
+ IBeadLayout:
ClassReference("org.apache.royale.jewel.beads.layouts.NullLayout")
+ IBeadModel:
ClassReference("org.apache.royale.jewel.beads.models.AlertModel")
+ IBeadController:
ClassReference("org.apache.royale.jewel.beads.controllers.AlertController")
+ IBeadView: ClassReference("org.apache.royale.jewel.beads.views.AlertView")
+```
+
+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.
+
+This component doesn't define any `secondary` or `emphasized` color.
\ No newline at end of file
