[royale-docs] branch master updated: strand and beads docs: filling the gaps

[ca...@apache.org]

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 7a68d6e  strand and beads docs: filling the gaps
7a68d6e is described below

commit 7a68d6ea3c23804adacd13e35ed19a9971405282
Author: Carlos Rovira <ca...@apache.org>
AuthorDate: Sat Aug 24 12:53:46 2019 +0200

    strand and beads docs: filling the gaps
---
 welcome/features/strands-and-beads.md | 113 +++++++++++++++++++++++++++++++---
 1 file changed, 104 insertions(+), 9 deletions(-)

diff --git a/welcome/features/strands-and-beads.md b/welcome/features/strands-and-beads.md
index d5748a2..65188ff 100644
--- a/welcome/features/strands-and-beads.md
+++ b/welcome/features/strands-and-beads.md
@@ -20,34 +20,129 @@ title: Strands and Beads
 
 # Strands and Beads
 
-__This material is not yet complete.__
+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 som [...]
+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.
 
-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. 
+> 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.
+
+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. 
 
 ## Finding the beads you need
 
-_How to know what beads are available, and where they are_
+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:
+
+* __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.
 
 ## Adding a bead
 
-There are three ways of adding beads to a component: baked into the code using <js:beads>, through CSS, and dynamically using addBead().
+There are three ways of adding beads to a component: baked into the code using `<j:beads>`, through CSS, and dynamically using `addBead()`.
 
 ### Adding a bead directly in the code
-_Steps for adding a bead_
+
+Each _strand_ support 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 [...]
+
+```mxml
+<j:TextInput text="Disabled with text...">
+    <j:beads>
+        <j:TextPrompt prompt="Disabled TextInput..."/>
+        <j:Disabled/>
+    </j:beads>
+</j:TextInput>
+```
 
 ### Adding a bead through CSS
-_Steps for adding a bead_
+
+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.
+
+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.
+
+The following example shows a bead declaration:
+
+```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__). 
+
+```sass
+j|List
+    IBeadView:  ClassReference("org.apache.royale.jewel.beads.views.ListView")
+    IBeadController: ClassReference("org.apache.royale.jewel.beads.controllers.ListSingleSelectionMouseController")
+    IBeadLayout: ClassReference("org.apache.royale.jewel.beads.layouts.VerticalLayout")
+    IItemRendererClassFactory: ClassReference("org.apache.royale.core.ItemRendererClassFactory")
+    IItemRenderer: ClassReference("org.apache.royale.jewel.itemRenderers.ListItemRenderer")
+    IViewport: ClassReference("org.apache.royale.jewel.supportClasses.scrollbar.ScrollingViewport")
+    IViewportModel: ClassReference("org.apache.royale.html.beads.models.ViewportModel")
+    IBeadModel: ClassReference("org.apache.royale.jewel.beads.models.ArrayListSelectionModel")
+    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.
 
 ### Adding a bead dynamically using addBead()
-_Steps for adding a bead_
 
+Other way to add a bead is though __ActionScript__ using the `addBead` API method.
+
+Lets see an example code:
+
+```as3
+// for Jewel Alert component, retrieve the AlertView (IBeadView) 
+var alertView:AlertView = alert.getBeadByType(IBeadView) as AlertView;
+
+// create a VerticalLayout (IBeadLayout)
+var verticalLayout:VerticalLayout = new VerticalLayout();
+verticalLayout.gap = 9;
 
+// add the bead layout to the content part of the view layout
+alertView.content.addBead(verticalLayout);
+```
+See a full example of the code above in the [Customization through the Royale API](https://royale.apache.org/customization-through-the-royale-api/){:target='_blank'} example.
 
 ## Creating a bead
 
-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. Information on the bead lifecycle is available at [Creating Components](https://cwiki.apache.org/confluence/display/FLEX/Creating+Components).
+The following piece of code reveals the most basic bead structure to use when coding a bead:
+
+```as3
+package beads
+{	
+	import org.apache.royale.core.IBead;
+	import org.apache.royale.core.IStrand;
+	import org.apache.royale.core.UIBase;
+	
+	/**
+	 *  sample code for a bead class
+	 */
+	public class SomeBead implements IBead
+	{
+		protected var _strand:IStrand;
+		
+		/**
+		 *  @copy org.apache.royale.core.IBead#strand
+		 *  
+		 *  @royaleignorecoercion org.apache.royale.core.UIBase;
+		 */
+		public function set strand(value:IStrand):void
+		{
+			_strand = value;
+
+			// do something
+		}
+	}
+}
+```
+
+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.
+
+Beads use to be tiny pieces of code so in this way we get a great encapsulation of functionality with 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).
 
 ## Strand management