Answers/Opinions inline
On 12/28/18, 5:07 AM, "Andrew Wetmore" <cottag...@gmail.com> wrote:
Hi, all:
I am working on the user doc page for strands and beads [1]. This is
intended for application developers using Royale; there is unfinished
material available for developers working on Royale itself in the wiki [2],
[3].
From the app developer point of view, I want to answer these questions:
1. There are three ways of adding beads to a component: baked in using
<js:beads>, through CSS, and dynamically using addBead(). Which method is
best to use for what purposes?
CSS sets up loosely-coupled defaults. Almost all (probably all) Royale
components that are strands pick up default beads from CSS. CSS allows setting
default beads for one or more instances of a component in a single CSS
Selector, just like CSS lets you set values on one or more HTMLElements. But
if our SWCs specify a certain bead as a default, and the app dev's CSS
specifies a different one, it should be possible for certain CSS tools to
optimize away the original default bead so it isn't linked into the output.
<js:beads> is the MXML way of calling addBead(). It allows the developer to
override the defaults bead from CSS for a single instance. But now that bead
is not loosely coupled, so if someone later subclasses the class that used
js:beads or addBead, and specify a different bead, both the original and the
new bead will be in the output. It isn't that much different from specifying
the "style" property on an HTMLElement in HTML. Js:Beads and addBead overrides
the underlying CSS.
1a. I can see from the wiki clear examples for two methods of adding beads.
Can someone point to an example using CSS to add a bead to a component?
Almost every SWC has a defaults.css file in src/main/resources that specify the
default beads. Several examples have MXML files that override the defaults in
CSS. Search the mxml files for "ClassReference"
2. Is the order of beads on a strand significant?
Yes. That’s one reason I proposed "strands and beads" instead of "peas and
porridge" or some other analogy. In real life the physical beads you put on a
strand totally change the look of the necklace or bracelet. That can be the
case here as well. I don't think there are any examples where order causes a
significant difference that doesn't result in a thrown exception from a null
pointer, but if you don't specify order, you can get indeterminate results
which we definitely don't want. Others have pointed out the common issues
(model first, then view, or making sure event listeners fire in the right
order. Sadly, I just looked and noted that getBeadByType is probably written
incorrectly. It should probably return the last bead added so you can override
other beads if needed. Right now, first-in-wins. I'm not sure we want that.
But in theory, nobody should ever add more than one bead of the same type to
the strand. The ways of overriding the defaults should prevent the need for
late overriding of beads.
3. How much should I worry about bead cleanup when a bead is no longer
actively used? I presume this would relate to dynamically-added beads, not
the <js:beads> or CSS ones.
I've been tempted to delete the removeBead API. Beads should never be removed.
We are compositing beads to form a component instead of subclassing base
classes. Both build up functionality and should never "delete" it. It might
mask or block "base-class" functionality, but you can't remove code from a base
class, and theoretically, beads should never be removed either.
4. Where do I find the existing beads? Is there a curated list for each
release of Royale? How do I know which ones would be useful for a text
entry field, a list, a button?
I added a few ASDoc tags like @toplevel and @viewbead to some of the ASDoc and
there is a cheap checkbox filter for it. More asdoc tags need to be added and
you are encouraged to come up with other ASDoc tags and references to other
components. That's one reason why ASDoc is a Royale app, so we can add
client-side logic to provide more sophisticated filtering someday that makes
use of ASDoc tags.
Thanks for working on it,
-Alex
Thanks!
a
[1]
https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fapache.github.io%2Froyale-docs%2FWelcome%2FFeatures%2FStrands%2520and%2520Beads.html&data=02%7C01%7Caharui%40adobe.com%7Ca37e020467d645bd3c7908d66cc56537%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636815992401552214&sdata=WFGjvg63MiYqXlEyTGEuv1qZmcL4QtzK2kLpUAb9dKo%3D&reserved=0
[2]
https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcwiki.apache.org%2Fconfluence%2Fpages%2Fviewpage.action%3FpageId%3D71013028&data=02%7C01%7Caharui%40adobe.com%7Ca37e020467d645bd3c7908d66cc56537%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636815992401552214&sdata=Hk2HnbcNNP9c4QcB4hrzcrB%2B2cfkGAqonMmUU2ZT94c%3D&reserved=0
[3]
https://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fcwiki.apache.org%2Fconfluence%2Fdisplay%2FFLEX%2FCreating%2BComponents&data=02%7C01%7Caharui%40adobe.com%7Ca37e020467d645bd3c7908d66cc56537%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636815992401552214&sdata=xzE80YHfuAwsCtLu7vDajGevY8clorB4tGs7TH0MPm8%3D&reserved=0
--
Andrew Wetmore
https://na01.safelinks.protection.outlook.com/?url=http%3A%2F%2Fcottage14.blogspot.com%2F&data=02%7C01%7Caharui%40adobe.com%7Ca37e020467d645bd3c7908d66cc56537%7Cfa7b1b5a7b34438794aed2c178decee1%7C0%7C0%7C636815992401552214&sdata=5cw5KLEvWoyN427Sa8pZ0WgQW36P17P0RH%2BT2bl230k%3D&reserved=0
