You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@royale.apache.org by ca...@apache.org on 2019/08/24 12:39:44 UTC
[royale-docs] branch master updated: incorporate externs to menu
and consolidate though rest of docs
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 <ca...@apache.org>
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