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 026ec01 incorporate externs to menu and consolidate though rest of
docs
026ec01 is described below
commit 026ec013afe15ad311e32e105fd4572b6e17310e
Author: Carlos Rovira <[email protected]>
AuthorDate: Sat Aug 24 14:39:36 2019 +0200
incorporate externs to menu and consolidate though rest of docs
---
_data/toc.json | 5 ++++-
component-sets/jewel/jewel-alert.md | 2 +-
user-interface/components.md | 1 +
welcome/features-and-concepts.md | 7 +++++--
welcome/features/external-interface.md | 22 ++++++++++++----------
{user-interface => welcome/features}/externs.md | 11 ++++++++---
welcome/features/strands-and-beads.md | 1 +
7 files changed, 32 insertions(+), 17 deletions(-)
diff --git a/_data/toc.json b/_data/toc.json
index 0bbafec..5be704e 100644
--- a/_data/toc.json
+++ b/_data/toc.json
@@ -20,7 +20,10 @@
"path": "welcome/features/payg.md"
},
{
- "path": "welcome/features/strands-and-beads.md"
+ "path": "welcome/features/external-interface.md"
+ },
+ {
+ "path": "welcome/features/externs.md"
}
]
},
diff --git a/component-sets/jewel/jewel-alert.md
b/component-sets/jewel/jewel-alert.md
index 9b0e3e5..fb180ca 100644
--- a/component-sets/jewel/jewel-alert.md
+++ b/component-sets/jewel/jewel-alert.md
@@ -37,7 +37,7 @@ Available since version __0.9.4__
The `Alert` component displays a message and one or more buttons in a window
that pops up over all other controls and views.
It uses the `AlertView` bead to display a [modal
dialog](https://en.wikipedia.org/wiki/Modal_window){:target='_blank'} with a
title and a variety of buttons configured through the flag property of its
`show` static function.
-> `Alert` uses the HTML dialog element, which currently has very limited
cross-browser support. To ensure support across all modern browsers, we use the
dialogPolyfill externs.
+> `Alert` uses the HTML dialog element, which currently has very limited
cross-browser support. To ensure support across all modern browsers, we use the
dialogPolyfill [externs](welcome/features/externs.html).
## Example of use
diff --git a/user-interface/components.md b/user-interface/components.md
index 78f0599..a2bad5b 100644
--- a/user-interface/components.md
+++ b/user-interface/components.md
@@ -16,6 +16,7 @@
layout: docpage
title: Components
+description: Meet the UI building blocks.
---
# Components
diff --git a/welcome/features-and-concepts.md b/welcome/features-and-concepts.md
index 4d2f897..eb449ca 100644
--- a/welcome/features-and-concepts.md
+++ b/welcome/features-and-concepts.md
@@ -16,6 +16,7 @@
layout: docpage
title: Features and Concepts
+description: Features and Concepts
---
# Features and Concepts
@@ -36,7 +37,9 @@ Royale provides a variety of [component
sets](./user-interface/components.html),
The underlying component patterns in most Royale components rely on a plug-in
model. Instead of making large component classes with lots of code baked in,
each individual feature of a component is designed as its own class with an
interface marking it as a "Bead", and then the component itself is called a
"Strand" and Beads are placed on the Strand to compose a Royale component. You
can [read more about Strands and Beads
here](welcome/features/strands-and-beads.html).
-## Calling to/from external JavaScript code
+## ExternalInterface and Externs
-Sometimes you may want your Royale application to call an external piece of
JavaScript that is also hosted in your web page, or even for some extenal
JavaScript from your page to call into the Royale application. In the Flex (and
Flash) world, there was the possibility to use the "ExternalInterface" class to
achieve this functionality. If you want this in Royale, there are some options
available that you can [read about
here](welcome/features/external-interface.html).
+Sometimes you may want your Royale application to call an external piece of
JavaScript that is also hosted in your web page, or even for some extenal
JavaScript from your page to call into the Royale application. In the Flex (and
Flash) world, there was the possibility to use the `ExternalInterface` class to
achieve this functionality. If you want this in Royale, there are some options
available that you can [read about
here](welcome/features/external-interface.html).
+
+Another option are externs, wich is uses [Google Closure Compiler
(GCC)](https://developers.google.com/closure/compiler/){:target='_blank'} to
declare that a name for a class, property or function is defined in external
code and so should not be renamed when application code is compiled. Apache
Royale can use the properties of the external library, and you can even see
them as options if you are using an __IDE__, with _code intelligence_ enabled.
[read about here](welcome/features/extern [...]
diff --git a/welcome/features/external-interface.md
b/welcome/features/external-interface.md
index d7babe4..4c03334 100644
--- a/welcome/features/external-interface.md
+++ b/welcome/features/external-interface.md
@@ -15,20 +15,20 @@
# limitations under the License.
layout: docpage
-title: Calling to/from External JavaScript
+title: ExternalInterface
+description: Calling to/from External JavaScript
---
-# Calling to/from External JavaScript
+# ExternalInterface
-
+Calling to/from External JavaScript
In Flash, there is a class,
[ExternalInterface](https://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/external/ExternalInterface.html){:target='_blank'},
that lets your Flex (or Flash) application call other JavaScript code that has
been embedded on the hosting web page,
and lets external JavaScript code call a function within the Flex application.
When you port a Flex application to Royale,
you may need to replicate this functionality.
-To make this easier, there is an implementation of the same API available as
[mx.external.ExternalInterface](https://github.com/apache/royale-asjs/blob/developframeworks/projects/MXRoyale/src/main/royale/mx/external/ExternalInterface.as){:target='_blank'}.
-You should be able to just rename your imports from
`flash.external.ExternalInterface` to `mx.external.ExternalInterface`.
+> To make this easier, there is an implementation of the same API available as
[mx.external.ExternalInterface](https://github.com/apache/royale-asjs/blob/develop/frameworks/projects/MXRoyale/src/main/royale/mx/external/ExternalInterface.as){:target='_blank'}.
You should be able to just rename your imports from
`flash.external.ExternalInterface` to `mx.external.ExternalInterface`.
For new code, it would be preferable to create an ActionScript wrapper API
into the required JavaScript.
This allows you to define a typed interface and the compiler would then pick
up any issues around incompatible types
@@ -57,8 +57,7 @@ public static function MyFunction(param : String, val : uint)
: void
It should be possible to make the call to `myFunction` directly, but we may
need asdoc decoration to avoid the 'unknown function' error.
-For JavaScript to call into a Royale application, we need a listener or
callback of some kind to be set up from the Royale application
-(particularly if we want to have some context retained). This can be an
extension of our existing class, `MyJSInterface`, where we register the
callback:
+For JavaScript to call into a Royale application, we need a listener or
callback of some kind to be set up from the Royale application (particularly if
we want to have some context retained). This can be an extension of our
existing class, `MyJSInterface`, where we register the callback:
```as3
public static function RegisterCallback(fncName : String, fncClosure :
Function) : void
@@ -66,12 +65,15 @@ public static function RegisterCallback(fncName : String,
fncClosure : Function)
MyJSInterface[fncName] = fncClosure;
}
```
-When we add our callback (e.g. `MyJSInterface.RegisterCallback("testFunction",
TestFunc);`)
-the Royale compiler creates a method closure that contains the context from
where this registration call is made. This lets you access variables -
particularly the "this" variable - within the TestFunc method during the
callback.
-The JavaScript code then can access this via the Royale-generated JavaScript
for MyJSInterface:
+When we add our callback (e.g. `MyJSInterface.RegisterCallback("testFunction",
TestFunc);`) the Royale compiler creates a method closure that contains the
context from where this registration call is made. This lets you access
variables - particularly the `this` variable - within the `TestFunc` method
during the callback.
+
+The JavaScript code then can access this via the Royale-generated JavaScript
for `MyJSInterface`:
```as3
MyJSInterface.testFunction("This will be passed to TestFunc");
```
+## Externs
+
+Finally a better and recommended way is to use
[Externs](welcome/features/externs.html) to know another way to communicate
to/from External JavaScript that brings many benefits like _code completion_
and _code intelligence_ since externs code is considered standard
__ActionScript__ code.
\ No newline at end of file
diff --git a/user-interface/externs.md b/welcome/features/externs.md
similarity index 88%
rename from user-interface/externs.md
rename to welcome/features/externs.md
index 9415ac1..e55fe06 100644
--- a/user-interface/externs.md
+++ b/welcome/features/externs.md
@@ -15,7 +15,8 @@
# limitations under the License.
layout: docpage
-title: externs
+title: Externs
+description: Use external javascript libraries in ActiopnScript
---
# Externs
@@ -24,11 +25,11 @@ Use external javascript libraries in ActiopnScript
Some Apache Royale elements at the moment have limited cross-browser support.
To get reliable display and performance in those cases, Royale makes use of
existing external JavaScript libraries. For example, [Jewel
Alert](https://apache.github.io/royale-docs/component-sets/jewel/jewel-alert.html)
uses the HTML dialog element, which is not reliable across all browsers. So
Jewel Alert references the _dialogPolyfill_ external library to make sure the
display is as intended in whichever brows [...]
-[Google Closure Compiler
(GCC)](https://developers.google.com/closure/compiler/){:target='_blank'}
provides a mechanism called _@externs_ that Apache Royale uses to declare that
a name for a property or function is defined in external code and so should not
be renamed when application code is compiled.
+[Google Closure Compiler
(GCC)](https://developers.google.com/closure/compiler/){:target='_blank'}
provides a mechanism called _@externs_ that Apache Royale uses to declare that
a name for a class, property or function is defined in external code and so
should not be renamed when application code is compiled.
The compiler assumes that externs will exist in the environment in which the
compiled JavaScript will be interpreted.
-Jewel Alert invokes _dialogPolyfill_, which is an AS3 class with _@externs_ in
its comments. That informs GCC that this class has the same name as the
external JavaScript library it references, and is not to be renamed in the
compile process. Apache Royale can use the properties of the external library,
and you can even see them as options if you are using an IDE, with code
intelligence enabled.
+Jewel Alert invokes _dialogPolyfill_, which is an AS3 class with _@externs_ in
its comments. That informs GCC that this class has the same name as the
external JavaScript library it references, and is not to be renamed in the
compile process. Apache Royale can use the properties of the external library,
and you can even see them as options if you are using an IDE, with _code
completion_ and _code intelligence_ enabled.
This is the code of the AS3 dialogPolyfill.as class file:
@@ -88,3 +89,7 @@ Then you will be able to call `registerDialog` method in the
following way:
```
To learn more about using the huge range of external JavaScript libraries that
is available, see [Using external JavaScript libraries in Apache
Royale](https://royale.apache.org/using-external-javascript-libraries-in-apache-royale/){:target='_blank'}.
+
+## ExternalInterface
+
+Check [ExternalInterface](welcome/features/external-interface.html) to know
another way to communicate to/from External JavaScript.
\ No newline at end of file
diff --git a/welcome/features/strands-and-beads.md
b/welcome/features/strands-and-beads.md
index 65188ff..1381dec 100644
--- a/welcome/features/strands-and-beads.md
+++ b/welcome/features/strands-and-beads.md
@@ -16,6 +16,7 @@
layout: docpage
title: Strands and Beads
+description: Adding functionality to a component through composition
---
# Strands and Beads
