This is an automated email from the ASF dual-hosted git repository.
andreww 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 cbb8acd Update strands-and-beads.md
cbb8acd is described below
commit cbb8acd6e2c4aa7dc98c8e54c96cec4415d0e70d
Author: Andrew Wetmore <[email protected]>
AuthorDate: Sat Aug 24 16:33:02 2019 -0300
Update strands-and-beads.md
Edited for clarity
---
welcome/features/strands-and-beads.md | 48 +++++++++++++++++------------------
1 file changed, 23 insertions(+), 25 deletions(-)
diff --git a/welcome/features/strands-and-beads.md
b/welcome/features/strands-and-beads.md
index 1381dec..e32fcab 100644
--- a/welcome/features/strands-and-beads.md
+++ b/welcome/features/strands-and-beads.md
@@ -25,26 +25,26 @@ Adding functionality to a component through composition
Strands and beads are key concepts in Royale, related to the
[PAYG](welcome/features/payg.html) (pay as you go) concept. The idea is to
keep component code as lightweight as possible, and to add functionality and
complexity only to the components that need it.
-> For example, you may use a lot of text input fields in your application, but
only one or two need to be able to protect passwords by converting the display
of text the user provides into dots. You may want to disable or enable some
components, but not all of them, while an end user is working with your
application. There is no reason to have that extra functionality (and added
weight of code) available everywhere _"just in case"_, as was the rule in
Apache Flex.
+> For example, you may use a lot of text input fields in your application, but
only one or two need to be able to protect passwords by converting the display
of text the user provides into dots. You may want to disable or enable some
instances of the text input component, but not all of them, while an end user
is working with your application. There is no reason to have that extra
functionality (and added weight of code) available everywhere _"just in case"_,
as was the rule in Apache Flex.
-Every component contains the minimum code necessary to perform its basic
functions, and has _"strands"_ onto which you can string _"beads"_ of
functionality that let the component do what you want it to do in a particular
place in your application.
+Every Royale component contains the minimum code necessary to perform its
basic functions, and has _"strands"_ onto which you can string _"beads"_ of
functionality that let an instance of the component do what you want it to do
in a particular place in your application.
## Finding the beads you need
-Finding the beads we provide per component or know what beads are available
(at least in the official Apache Royale SDK) can be a daunting task, since can
be hundreds of this little pieces of code distributed all over the framework
code. For this reason this documentation is trying to help in that task
providing a list of beads in each component page, so users can refer to a
concrete _"strand"_ (the component) and see a list of recommended _"beads"_.
Normally you can have:
+Finding the beads that will provide what you want for a given component, or
even knowing what beads are available in the official Apache Royale SDK can be
a daunting task. There are hundreds of these little pieces of code distributed
all over the framework code. For this reason we are gradually assembling a list
of beads on each component page, so users can refer to a concrete _strand_ (the
component) and see a list of _beads_ that work with it. Normally you can have:
-* __Specific Component Beads__. (beads only usable for a concrete component
like the [Jewel
PasswordInput](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls.textinput/PasswordInput){:target='_blank'}
for a [Jewel TextInput](component-sets/jewel/jewel-textinput.html))
-* __Common Shared Beads__. Beads that can be used by more than one strand like
[Jewel Disabled
bead](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls/Disabled){:target='_blank'}
can be used by [Jewel Button](component-sets/jewel/jewel-button.html), [Jewel
TextInput](component-sets/jewel/jewel-textinput.html) or [Jewel
CheckBox](component-sets/jewel/jewel-checkbox.html) controls for example.
+* __Specific Component Beads__. (beads only usable for a specific component,
like [Jewel
PasswordInput](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls.textinput/PasswordInput){:target='_blank'}
for an instance of [Jewel
TextInput](component-sets/jewel/jewel-textinput.html))
+* __Common Shared Beads__. Beads that can be used with more than one
component, like [Jewel Disabled
bead](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls/Disabled){:target='_blank'},
which can be used by [Jewel Button](component-sets/jewel/jewel-button.html),
[Jewel TextInput](component-sets/jewel/jewel-textinput.html) or [Jewel
CheckBox](component-sets/jewel/jewel-checkbox.html).
## Adding a bead
-There are three ways of adding beads to a component: baked into the code using
`<j:beads>`, through CSS, and dynamically using `addBead()`.
+There are three ways to add beads to a component: bake it into the code using
`<j:beads>`, declare it through CSS, or add it dynamically using `addBead()`.
### Adding a bead directly in the code
-Each _strand_ support a `beads` array and users can add beads in MXML.
+Each _strand_ supports a `beads` array and users can add beads in MXML.
-In the following example we are using the [Jewel
TextInput](component-sets/jewel/jewel-textinput.html) strand to add a [Jewel
TextPrompt](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls.textinput/TextPrompt){:target='_blank'}
and [Jewel
Disabled](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls/Disabled){:target='_blank'}
beads to the strand. Notice that while `TextPrompt` is specific to TextInput,
`Disabled` can be use [...]
+In the following example we are using the [Jewel
TextInput](component-sets/jewel/jewel-textinput.html) strand to add [Jewel
TextPrompt](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls.textinput/TextPrompt){:target='_blank'}
and [Jewel
Disabled](https://royale.apache.org/asdoc/index.html#!org.apache.royale.jewel.beads.controls/Disabled){:target='_blank'}
beads to the strand. Note that while `TextPrompt` is specific to TextInput,
you can use `Disabled` wi [...]
```mxml
<j:TextInput text="Disabled with text...">
@@ -57,20 +57,18 @@ In the following example we are using the [Jewel
TextInput](component-sets/jewel
### Adding a bead through CSS
-Adding beads through [Cascading Style Sheets
(CSS)](https://en.wikipedia.org/wiki/Cascading_Style_Sheets){:target='_blank'}
is easy. You declare __CSS__ rules where the the _selector_ is the strand and
the declaration block is composed by one or more delarations. Declarations can
be _bead declarations_ or _standard CSS declarations_ separated by semicolons.
+Adding beads through [Cascading Style Sheets
(CSS)](https://en.wikipedia.org/wiki/Cascading_Style_Sheets){:target='_blank'}
is easy. You declare CSS rules where the the _selector_ is the strand and the
declaration block has one or more delarations. Declarations can be _bead
declarations_ or _standard CSS declarations_ separated by semicolons.
-A bead declaration is composed of the bead type as the __property__ part (i.e,
[IBead](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBead){:target='_blank'},
[IBeadModel](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadModel){:target='_blank'},
[IBeadView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadView){:target='_blank'},
...) and a a `ClassReference` of the bead we want to assign as the __value__
part.
+A bead declaration has the bead type as the __property__ part (for instance,
[IBead](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBead){:target='_blank'},
[IBeadModel](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadModel){:target='_blank'},
and
[IBeadView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadView){:target='_blank'})
and a `ClassReference` to the bead we want to assign as the __value__ part.
-The following example shows a bead declaration:
+Here is an example of a CSS bead declaration. We assign
`org.apache.royale.jewel.beads.views.ListView` as the bead view (`IBeadView`)
of the component strand:
```css
IBeadView: ClassReference("org.apache.royale.jewel.beads.views.ListView");
```
-In the example we want to assign a
`org.apache.royale.jewel.beads.views.ListView` as the bead view (`IBeadView`)
of the component strand.
-
-Notice that Royale use __CSS__ to configure components with defaults beads.
The following
-code snippet is the default initial bead configuration for a [Jewel
List](component-sets/jewel/jewel-list.html) and is declared though
[SASS](https://sass-lang.com){:target='_blank'} (that will be compiled to
__CSS__).
+Royale uses __CSS__ to configure components with defaults beads. The following
+code snippet is the default initial bead configuration for a [Jewel
List](component-sets/jewel/jewel-list.html) and is declared though
[SASS](https://sass-lang.com){:target='_blank'} (that gets compiled to
__CSS__).
```sass
j|List
@@ -85,16 +83,16 @@ j|List
IDataProviderItemRendererMapper:
ClassReference("org.apache.royale.jewel.beads.itemRenderers.DataItemRendererFactoryForCollectionView")
```
-Thanks to __CSS__, Royale developers can override default beads through its
own coded __CSS__ files, that will take priority over framework __CSS__ rules,
or through AS3 and/or MXML code.
+Royale developers can override default beads through their own coded CSS files
that will take priority over framework CSS rules, or through AS3 and/or MXML
code.
-### Adding a bead dynamically using addBead()
+### Adding a bead dynamically with addBead()
-Other way to add a bead is though __ActionScript__ using the `addBead` API
method.
+The third way to add a bead is though __ActionScript__ using the `addBead()`
API method.
-Lets see an example code:
+Here is example code:
```as3
-// for Jewel Alert component, retrieve the AlertView (IBeadView)
+// for the Jewel Alert component, retrieve the AlertView (IBeadView)
var alertView:AlertView = alert.getBeadByType(IBeadView) as AlertView;
// create a VerticalLayout (IBeadLayout)
@@ -108,7 +106,7 @@ See a full example of the code above in the [Customization
through the Royale AP
## Creating a bead
-The following piece of code reveals the most basic bead structure to use when
coding a bead:
+The following piece of code shows the most basic bead structure to use when
you create a bead:
```as3
package beads
@@ -139,12 +137,12 @@ package beads
}
```
-All beads implement
[IBead](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBead){:target='_blank'}
interface (or a subclass like
[IBeadModel](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadModel){:target='_blank'}
or
[IBeadView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadView){:target='_blank'})
and can refer to the strand component using the `strand` method implementation
of the IBead interface.
+All beads implement the
[IBead](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBead){:target='_blank'}
interface (or a subclass like
[IBeadModel](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadModel){:target='_blank'}
or
[IBeadView](https://royale.apache.org/asdoc/index.html#!org.apache.royale.core/IBeadView){:target='_blank'})
and can refer to the strand component using the `strand` method implementation
of the IBead interface.
-Beads use to be tiny pieces of code so in this way we get a great
encapsulation of functionality with few lines of code.
+Beads can be tiny pieces of code so in this way we get great encapsulation of
functionality with a few lines of code.
-If you see a need for a bead that does not yet exist, you can create your own
and [contribute it to the Royale
project](https://royale.apache.org/get-involved/){:target='_blank'}.
Information on the bead lifecycle is available at [Creating
Components](https://cwiki.apache.org/confluence/display/FLEX/Creating+Components).
+If you see the need for a bead that does not yet exist, you can create your
own and [contribute it to the Royale
project](https://royale.apache.org/get-involved/){:target='_blank'}.
Information on the bead lifecycle is available at [Creating
Components](https://cwiki.apache.org/confluence/display/FLEX/Creating+Components).
## Strand management
-_Adding and removing beads; the significance of bead order_
+_This section will include information on adding and removing beads and the
significance of bead order_
