Extensions and Extension Points
Extension points are a mechanism where bundles can contribute code, UI, or practically anything to the main application. Extension points are also the mechanism to create custom metadata tags. Extensions points are created by declaring an [ExtensionPoint] tag on top of a class.
Extensions are instances of a given extension point. Extensions are also created by declaring a metadata tag using the id of the extension point. For example, an extension point [ExtensionPoint(id=”MyExtPt”)] would be extended with a metadata tag like [MyExtPt]. Extensions can be declared on classes, methods, or variables but specific extension points can restrict where the extension can be declared.
When creating extension points there are a few special attributes that Potomac parses and uses to manage the extension point. Any other attribute declared in the [ExtensionPoint] tag creates a new custom property.
| Special Attributes | |
|---|---|
| id | The extension point id becomes the tag used by extensions. |
| type | Type is a fully qualified interface or class name. When type is specified, extensions may only be declared on classes of the specified type. |
| declaredOn | Any combination of “classes”,’methods, “variables”, or “constructors” in a comma separated string. If declaredOn isn’t specified, the extension may be declared anywhere. If declaredOn is specified, the extension may only be declared on the specified elements. |
| access | Any combination of public”, “protected”, or “private” in a comma separated string. If specified, extensions may only be declared on elements with given access. |
| variableType | Similar to type. A fully qualified interface or class name. When specified, extensions may only be declared on variables of the given type. |
| idRequired | True or false. When true, all extension declarations must include an id attribute. |
| rslRequired | True or false. When true, bundles that contains extensions of this extension point must be loaded as RSLs. This ensures that extensions are accessible without requiring a bundle to be download and installed. This is intended for use primarily by Potomac itself. |
| argumentsAsAttributes | True or false. When true, if an extension is declared on a method or a constructor, the extension may specify attributes that match argument names. This allows extension points to annotate method parameters. When an extension is declared on variables, this attribute allows extension attributes that match the variable name as well. |
Any other attribute than those specified above (and a few other reserved attributes) creates a custom attribute. The datatype of the custom attribute should be specified in the attribute’s value.
| Valid Datatypes | |
|---|---|
| string | a string |
| integer | an integer |
| boolean | a Boolean |
| choice: | Only one of the given choice values. Ex “choice:yes,no,maybe,sometimes” allows any one of the 4 stated values. |
| asset | A valid file found in the bundle’s extensionAssets folder. May specify a list of valid file extensions. Ex “asset:png,gif” states only files that end in png or gif may be provided. |
| type | A valid fully qualified class or interface that optionally extends the given type. Ex “type:package.IInterface” requires a class or interface name that extends IInterface. |
| class | Similar to type except only class names may be provided. |
| interface | Similar to type and class except only interface names may be provided. |
Additionally, specifying an asterisk at the beginning of the datatype declaration makes the attribute a required attribute.
Examples:
[ExtensionPoint(id=”CoolStuff_MyPoint”,idRequired=”true”,declaredOn=”classes”, type=”flash.events.IEventDispatcher”,name=”*string”, favoriteFood=”choice:tacos,pizza”,icon=”asset:png,jpg,gif”)]
[ExtensionPoint(id=”CoolStuff_Point2”,declaredOn=”methods”,access=”public”, callThisMethod=”*boolean”,timesToCall=”integer”)]
[CoolStuff_MyPoint(id=”myExtension”,name=”MyName”,icon=”myIcon.gif”)]
[CoolStuff_Point2(callThisMethod=”true”,timesToCall=”6”)]
Parsing and reading declared extensions is done via IBundleService#getExtensions. This method returns an Array of Extension objects. The Extension object is a dynamic object and will contain dynamic properties for the declared custom attributes. For the last example above, the Extension object would contain a boolean attribute named “callThisMethod” and an integer attribute called “timesToCall”. For optional attributes, the Extension object will only contain the property if it is was declared in the extension. Otherwise it will be undefined. For asset attributes, the type of the property will be Class. Potomac embeds the asset file automatically. Therefore, the property can be easily used as the source of an image on a control.
With some extensions, it will be necessary to create an instance of the extension’s class. Since an extension will be available before a bundle is loaded, developers should not use getDefinitionByName as the class may not be in the ApplicationDomain. Instead, developers should call Injector#getInstanceOfExtension. This method runs asynchronously as it loads any required bundles before returning an instance of the given extension.
The Extension class also contains a reflection API to describe the class, method, or field where the extension tag was declared.