Mike, too bad our different time zones slow down communication so much...
Ah yes, this is about the [Native] annotation we discussed in this other
thread.
Jangaroo needs the ActionScript API of all the built-in classes (JavaScript
globals), so when using String, it actually parses String.as and finds the
[Native] annotation. It then uses a different AMD module name, using the
"native" plugin that, instead of loading a script, just retrieves the
global JavaScript object.
In the meantime, [Native] can do even more:
- Using [Native(amd="path/library")] on a class com.acme.Foo, you tell
the compiler to not generate any code for this class, but whenever it is
used, load the AMD module "path/library". This allows to implement an
ActionScript API "natively" in JavaScript. The corresponding "native!"
notation would be "native!com.acme.Foo@path/library". If you just write
[Native(amd)], the module name is derived from the class name as usual, in
this case the generated code would require "classes/com/acme/Foo" (*no*
native! plugin!).
- Using [Native(global="Ext.Panel")] on a class ext.Panel allows to
define a mapping from ActionScript identifier (ext.Panel) to JavaScript
global name (upper-case "package" Ext.Panel). If no "global" is given, the
ActionScript name must be exactly the same as the JavaScript name.
- You can even combine "amd" and "global", to integrate with non-AMD
libraries and to define a fine-grained API for a library that ships as one
big script. For example, the ActionScript class ext.Panel which represents
Ext JS's Ext.Panel would be annotated as [Native(amd="ext-js/ext-all",
global="Ext.Panel")] (notation: "native!Ext.Panel@ext-js/ext-all"), and
Ext.form.TextField would be defined as class ext.form.TextField and
annotated as [Native(amd="ext-js/ext-all", global="Ext.form.TextField")]
(notation: "native!Ext.form.TextField@ext-js/ext-all"). The script is
only loaded once, but the "native!" plugin retrieves different global
objects.
What all [Native] classes have in common is that there is no "_" property,
i.e. no indirection to allow for static code in the compilation unit. If we
stumble across a native JavaScript library that needs lazy initialization,
we can still add another annotation like [Lazy(init="<init-method-name>")].
We really should optimize the special case you asked for, where a
non-aliased, non-namespaced global like "String" or "parseInt" is assigned
to a parameter via the "native!" plugin. While it does speed up access to
"String" and "parseInt" a tiny bit, it produces unnecessary code overhead.
I am going to change that in Jangaroo and in the as-js-runtime-prototype
accordingly.
Oh, I did it again, concise question, lengthy response, so here comes...
*tl;dr*: if a referenced class is [Native] and top-level, access it as a
global JavaScript object. If it is [Native] but not top-level, use
define(["native!<qualified-name>"], function(<short-name>) { ... }) similar
to non-native classes. There are some advanced usages ("amd", "global") we
can care about later. For reference, you can use the ActionScript standard
classes defined in branch "jangaroo-3" of the
jangaroo-runtime<https://github.com/CoreMedia/jangaroo-tools/tree/jangaroo-3/jangaroo/jangaroo-runtime/src/main/joo>
.
Greetings
-Frank-
