[GitHub] cottage14 closed pull request #12: External interface documentation

[GitBox <gi...@apache.org>]

cottage14 closed pull request #12: External interface documentation
URL: https://github.com/apache/royale-docs/pull/12
 
 
   

This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:

As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):

diff --git a/Welcome/Features And Concepts.md b/Welcome/Features And Concepts.md
index c359163..feba029 100644
--- a/Welcome/Features And Concepts.md	
+++ b/Welcome/Features And Concepts.md	
@@ -36,5 +36,7 @@ Royale also provides a Basic component set that is the opposite of Express.  The
 
 It turns out that the Express components are really just Basic components with lots of Beads packed into them by default.  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%20and%20Beads.html).
 
+## Calling to/from external JavaScript code
 
+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).
 
diff --git a/Welcome/Features/external-interface.md b/Welcome/Features/external-interface.md
new file mode 100644
index 0000000..47c5d26
--- /dev/null
+++ b/Welcome/Features/external-interface.md
@@ -0,0 +1,70 @@
+---
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements.  See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License.  You may obtain a copy of the License at
+# 
+# http://www.apache.org/licenses/LICENSE-2.0
+# 
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+layout: docpage
+title: Calling to/from External JavaScript
+---
+
+# Calling to/from External JavaScript
+
+In Flash, there is a class
+<A HREF="https://help.adobe.com/en_US/FlashPlatform/reference/actionscript/3/flash/external/ExternalInterface.html" target="_blank">ExternalInterface</A>
+that allows your Flex (or Flash) application to call other JavaScript code that has been embedded on the hosting web page,
+or to allow the external JavaScript code to call a function within the Flex application. When porting a Flex application to Royale,
+it may be that you need to replicate this functionality.
+
+To make this easier, there is an implementation of the same API that's now available as
+<A HREF="https://github.com/apache/royale-asjs/blob/develop/frameworks/projects/MXRoyale/src/main/royale/mx/external/ExternalInterface.as" target="_blank">mx.external.ExternalInterface</A>.
+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
+or incorrectly spelt function names. This could allow a line such as:
+```
+ExternalInterface.call("MyFunction", "value", 123);
+```
+to be replaced by
+```
+MyJSInterface.MyFunction("value", 123);
+```
+hence ensuring that you haven't misspelt "MyFunction" and that the function is being passed the correct number and types of arguments.
+
+The implementation of your API wrapper class is where you would call the JavaScript functionality directly, which could be simply via reflection:
+```
+public static function MyFunction(param : String, val : uint) : void
+{
+  window["myFunction"](param, val);
+}
+```
+TBC: 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 still 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:
+```
+public static function RegisterCallback(fncName : String, fncClosure : Function) : void
+{
+  MyJSInterface[fncName] = fncClosure;
+}
+```
+The advantage of this is that when we add our callback (e.g. `MyJSInterface.RegisterCallback("testFunction", TestFunc);`)
+the Royale compiler will create a method closure that contains the context from where this registration call is made. This allows you
+to 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:
+```
+MyJSInterface.testFunction("This will be passed to TestFunc");
+```
+


 

----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
 
For queries about this service, please contact Infrastructure at:
users@infra.apache.org


With regards,
Apache Git Services