Terminology and Concepts

In Royale, we distinguish between "Application Developers" and "Framework Developers". Folks contributing to the Royale Framework are "Framework Developers" and have different things to understand and consider. Folks writing applications with Royale who are familiar with Flex should be able to think of the framework components like Flex components. All (or most) of the platform abstractions are encapsulated in the framework components.

This document is intended to define the terminology and concepts that Framework Developers should have in their heads when contributing to the framework.

Terminology

Component

A Component is a class that performs some task. Components are assembled in some fashion to perform a larger task. The word "component" is overused and when discussing framework development, it is helpful to determine what kind of component is being discussed since different components have different considerations.

Component Kinds

If you examine the various source files, you should find that they are divided into:

• Interfaces An Interface defines the contract (the set of APIs) that other component code can expect from a class implementing that interface. A "Marker Interface" is an interface without any properties or methods. It is used to strictly test for a certain category of classes.
• Base Classes A BaseClass is sort of like an Abstract Class in Java. It is rarely instantiated. Base Classes often implement one or more interfaces with code intended to be shared/reused by subclasses.
• Beads A bead is some functionality designed to be plugged-in or "composed" by adding to a Strand.
• Utility Functions and Classes These are bundles of functionality designed to be reused by other source files that don't need the overhead of a Strand and/or do not make sense in a class hierarchy
• Top-Level Components A Top-Level Component (TLC) is a strand with a useful set of default beads.

Beads, Base Classes and TLCs and even Utility Functions and Classes are all Components. They all consist of code that can be combined to create a higher-level component. TLCs can be composed in part by other TLCs.

Component Set

A component set is a set of TLCs and any source files needed to implement the TLC's that are not composited or inherited from other component sets. Component sets are typically distributed as SWCs.

Strand

A Strand is an array of beads. An individual bead can also provide a strand and thus have its own beads.

CSS Kinds

There are three kinds of CSS in Royale

• ClassReferences These define default beads required for operation. ClassReferences are not CSS compliant.
• Visual CSS This is compliant CSS that affects what the pixels are
• Positional CSS This is also compliant CSS that affects structure (display, position). IOW, where the pixels are.

Concepts

Primary Goals

First and foremost, we want to keep an eye on these primary goals when making framework decisions.

• Small Code Size
• Fast Performance

These two often have trade-offs against each other so one is not more important than the other. For example, inline code is faster, but means more code.

Execution Goals

How do we achieve small code size and good performance? By executing with the following in mind:

1. Pay-as-you-go (PAYG)
2. Re-use as much code as possible.
3. Choose Composition over inheritance in most cases
4. Use Inheritance and utility functions in other cases

There are no hard rules. If you take code reuse to an extreme, you would create a class for running for loops, but the performance overhead of that would outweigh the code reuse savings.

Organization Goals

We want to support multiple component sets. Users may mix-and-match TLCs from various component sets, but that should be relatively rare since, once you have used a more complex TLC, there are few code size savings to also using a simpler TLC. What is more likely is that users may mix and match beads from various component sets.

Beads should be organized into SWCs with other beads they have something in common with. So MaterialDesignLite, CreateJS, Basic, Jewel, Express all will contain beads specific to what they do. Basic does simple implementations. Express rolls up Basic beads into aggregates.

Other Goals

Backward compatibility will become more important after 1.0 but don't do too many name changes without getting agreement first.

Subclassing

Because TLCs are always compositions, there is less value to subclassing them. There is less code to re-use. TLCs are primarily reserved for Application Developers since the MXML component model must use subclassing. Thus, there should be no "final" TLCs. Subclassing TLCs can also be used within a component set if it helps code reuse or styling. TLCs are just examples and labels for popular compositions of beads.

On the other hand, subclassing is a good way to implement PAYG in beads (and always used in base classes). Simple beads can be subclassed and more complex things can be implemented in the subclass.

Exploded Component

Any Top-Level Component should be able to be approximated in MXML by using the base class and beads. This is known as the "exploded component". The code in the Top-Level Component should proxy model properties and hopefully do little else. The beads should not ever reference the Top-Level Component, only the Strand. That allows the exploded component to work and makes it easier to re-use the beads in other component sets or as base classes for beads in other component sets.

IOW, a Basic Button (which extends UIBase) should be represented by the MXML

<js:UIBase>
   <js:beads>
     <js:ButtonModel />
     <js:ButtonView />
     <js:ButtonController />
   </js:beads>
</js:UIBase>

CSS

• ClassReferences Missing ClassReferences are likely to cause major failures. Thus they should be specified in the containing SWC's defaults.css.
• Visual CSS should go in theme SWCs (located in frameworks/themes)
• Positional CSS can be hard-coded into layout classes or specified in class selectors and referenced by layout classes.