You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by an...@apache.org on 2019/08/24 19:33:07 UTC
[royale-docs] branch master updated: Update strands-and-beads.md
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 <an...@cottage14.com>
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_