| <!doctype html><html lang="en"><head><meta charset="utf-8"><meta http-equiv="CACHE-CONTROL" content="NO-CACHE"><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1,maximum-scale=1,user-scalable=no"><meta http-equiv="X-UA-Compatible" content="ie=edge"><title>Using external JavaScript libraries in Apache Royale</title><link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css"><link rel="stylesheet" href="/css/styles.css"><link rel="shortcut icon" href="/img/favicon.ico"></head><body class="page post" id="main"><header class="docs-header"><div class="container"><div class="topbar"><div class="topbar-left"><a href="/"><span class="site-title">Apache Royale</span></a></div><div class="topbar-center"></div><div class="topbar-right"><button class="topMenu-dropbtn"><i class="fa fa-bars"></i> Menu</button><ul class="topMenu"><li><a href="/features">Features</a></li><li><a href="https://apache.github.io/royale-docs/get-started">Get Started</a></li><li><a href="/download">Download</a></li><li><a href="/docs">Docs</a></li><li><a href="/blog">Blog</a></li><li><a href="https://github.com/apache/royale-asjs/wiki/Apache-Royale-Source-Code-Repositories"><i class="fa fa-github"></i> GitHub</a></li></ul></div></div><div class="post-header"><h1>Using external JavaScript libraries in Apache Royale</h1><div class="post-meta">by Carlos Rovira on June 03, 2019</div></div></div></header><div class="page-content"><div class="container"><article><p>This example shows how to use external JavaScript libraries in your Apache Royale application. You can add quick functionality to your application by including code that is not part of Apache Royale itself or is even not written in ActionScript.</p><p>In this way, <em>you get lots of libraries available for free in the Internet to strengthen and extend your Apache Royale Application.</em></p><p>It also allows an IDE to provide code completion, type checking, etc.</p><p>The example shows a <strong>Jewel Card</strong> with a code text zone that loads an ActionScript code example. Click the <em>"highlight block"</em> button to show the code in a beautifully colored way, thanks to processing by a highlight library which is an external JavaScript library.</p><blockquote><p>The JavaScript library used to show this feature is <a href="https://highlightjs.org/">highlightjs</a>. In JavaScript this library creates the hljs object our code references.</p></blockquote><h2>How to use JavaScript external libraries</h2><p>We have two solutions available for using external JavaScript libraries in Apache Royale. We'll focus first on the better and recommended way, which is using the <strong>@externs</strong> compiler directive.</p><p>This method gives you robust access to JavaScript methods though ActionScript with dot access syntax (and lets you use code hinting in your IDE). But if you need to prototype something quickly, you can use dynamic syntax with <em>bracket access</em> notation.</p><h2>Dot access</h2><p>This is the recommended way. You get all advantages of an object-oriented language like ActionScript 3: type checking, compiler errors and warnings, and code hinting and code completion in your favorite IDEs.</p><p><img src="/img/blog/Captura-de-pantalla-2019-06-03-a-las-18.20.46.png" alt=""></p><p>The code for this <a href="https://github.com/apache/royale-asjs/blob/develop/examples/blog/BE0012_Using_external_javascript_libraries_in_Apache_Royale/src/main/royale/hljs.as">hljs as3 stub code</a> is located in this blog example project and is the <strong>@externs</strong> class definition for <strong>hljs</strong>:</p><pre><code class="language-as3">//////////////////////////////////////////////////////////////////////////////// |
| // |
| // 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 |
| // |
| // //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. |
| // |
| //////////////////////////////////////////////////////////////////////////////// |
| package |
| { |
| /** |
| * @externs |
| */ |
| COMPILE::JS |
| public class hljs |
| { |
| /** |
| * <inject_script> |
| * var script = document.createElement("script"); |
| * script.setAttribute("src", "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"); |
| * document.head.appendChild(script); |
| * var link = document.createElement("link"); |
| * link.setAttribute("rel", "stylesheet"); |
| * link.setAttribute("type", "text/css"); |
| * link.setAttribute("href", "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"); |
| * document.head.appendChild(link); |
| * </inject_script> |
| */ |
| public function hljs(){} |
| |
| public static function highlightBlock(block:Element):void {} |
| } |
| } |
| </code></pre><p>You can see two main things in this code:</p><ol><li>An inject_html directive declared in the constructor adds the following lines to the html template, so you do not need to add the lines manually. If you use this library, Royale adds these references automatically, and if you remove all references, Royale removes the dependencies to the JavaScript library and nothing is output in the html file.</li><li>Use the highlightBlock static function, which you can access as a normal method in the AS3 hljs class.</li></ol><h2>Bracket access</h2><p>If you need to prototype something quickly you can use this method but remember we don't recommend that you use this in your main Apache Royale project.</p><p>First, reference the JavaScript library (and/or css if it exists) in your html template. For <strong>hljs</strong> you can copy the following lines:</p><pre><code class="language-html"><script src="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/highlight.min.js"></script> |
| <link rel="stylesheet" title="Atom One Dark" href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/atom-one-dark.min.css"> |
| </code></pre><p>Then you can start using the library in your code. An example with the highlightjs hljs object is:</p><pre><code class="language-as3">var hljs:Object = window["hljs"]; |
| hljs["highlightBlock"](block); |
| </code></pre><p>As you can see, this avoids using a more structured language like ActionScript 3. You lose type checking and the compiler will not help you if you write something wrong. Plus, if the API is changed, that code will not be able to warn you about the changes.</p><h2>The example</h2><p>The example uses <strong>HTTPService</strong> to retrieve sample code and display it in an <strong>html:Code</strong> component. When the application loads, it fires the <strong>initialize</strong> event. We use that to order HTTPService to load the text file. When the file finishes loading, HTTPService fires a complete event. We use that to add the text file content to the <strong>code_txt</strong> <em>String variable</em>.</p><blockquote><p>Note: Since the code_txt variable uses data binding (it's marked with the <strong>Bindable</strong> metadata and we prepared the application to handle data binding with the <strong>ApplicationDataBinding</strong> bead), the application fills the html:Code <strong>sourceCodeMXMLText</strong> with the loaded text.</p></blockquote><p>This is the code for this example:</p><pre><code class="language-mxml"><?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| |
| 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. |
| |
| --> |
| <j:Application xmlns:fx="http://ns.adobe.com/mxml/2009" |
| xmlns:j="library://ns.apache.org/royale/jewel" |
| xmlns:js="library://ns.apache.org/royale/basic" |
| xmlns:html="library://ns.apache.org/royale/html" |
| initialize="codeTextLoader.send();"> |
| |
| <fx:Script> |
| <![CDATA[ |
| [Bindable] |
| public var code_txt:String; |
| |
| public function highLightContent():void |
| { |
| COMPILE::JS |
| { |
| hljs.highlightBlock(sourceCodeMXMLText.element); |
| } |
| } |
| ]]> |
| </fx:Script> |
| |
| <j:beads> |
| <js:ApplicationDataBinding/> |
| <js:HTTPService id="codeTextLoader" url="as3code.txt" complete="code_txt = codeTextLoader.data;"/> |
| </j:beads> |
| |
| <j:initialView> |
| <j:View> |
| <j:beads> |
| <j:HorizontalCenteredLayout/> |
| </j:beads> |
| |
| <j:Card width="90%"> |
| <html:H3 text="Using external JavaScript Libraries"/> |
| |
| <j:Label html="This example uses hljs library to highligh a piece of code"/> |
| |
| <html:Pre height="300" width="100%" style="background-color: white"> |
| <html:beads> |
| <j:ScrollingViewport/> |
| </html:beads> |
| <html:Code id="sourceCodeMXMLText" text="{code_txt}"/> |
| </html:Pre> |
| |
| <j:Button text="highlight Block" emphasis="primary" click="highLightContent()"/> |
| </j:Card> |
| </j:View> |
| </j:initialView> |
| </j:Application> |
| </code></pre><p>In the example code you can see how we call the <em>hljs.highlightBlock</em> method with the recommended dot syntax as with any other ActionScript code, creating a seamless integration between your project code and the external JavaScript code.</p><h2>Conclusion</h2><p>You can see how simple and elegant it can be to use external JS code, while not compromising the safe syntax you have when using the MXML and AS3 languages, to give you more dynamic options for your application at no cost.</p><h2>Where to go from here</h2><ul><li><a href="https://github.com/apache/royale-asjs/blob/eaf2dbde05a3823e0c148ba806c025eb56388a7a/frameworks/projects/Jewel/src/main/royale/org/apache/royale/jewel/Alert.as#L225">Other use of @externs in a Jewel Alert component</a></li><li><a href="https://royale.apache.org/loading-external-data-through-httpservice/">Loading external data through HTTPService</a></li><li><a href="https://royale.apache.org/binding-the-text-property-of-a-jewel-textinput-to-update-a-text-label/">Binding the text property of a Jewel TextInput to update a text Label</a></li></ul><p>The result of this code snippet is the following:</p><iframe width="100%" height="600" src="/blog-examples/BE0012_Using_external_javascript_libraries_in_Apache_Royale/index.html"></iframe><p>(We're using an iframe to host the actual results of this example compilation. To see the example in a separate window click <a href="/blog-examples/BE0012_Using_external_javascript_libraries_in_Apache_Royale/index.html" target="_blank">this link</a>.)</p><p>Full project with source code can be found <a href="https://github.com/apache/royale-asjs/tree/develop/examples/blog/BE0012_Using_external_javascript_libraries_in_Apache_Royale">here</a>:</p><p><a class="btn btn-download" href="https://github.com/apache/royale-asjs/tree/develop/examples/blog/BE0012_Using_external_javascript_libraries_in_Apache_Royale"><i class="fa fa-download"></i> Project Source Code</a></p></article></div></div><footer class="footer"><div class="footer-row"><div class="footer-column"><ul class="footer-list"><li class="apacheroyale"><a href="/">Apache Royale</a></li><li><a href="/">Home</a></li><li><a href="/features">Features</a></li><li><a href="/download">Download</a></li><li><a href="/ides">IDEs and Editors</a></li><li><a href="/showcase">Showcase</a></li><li><a href="/blog">Blog</a></li><li><a href="/team">Team</a></li><li><a href="/thanks-to">Thanks To</a></li><li><a href="https://apache.org/logos/#royale"><i class="fa fa-external-link-square"></i> Logos</a></li><li><a href="https://www.apache.org/licenses/"><i class="fa fa-external-link-square"></i> Apache License v2.0</a></li></ul></div><div class="footer-column"><ul class="footer-list"><li class="documentation"><a href="/docs">Documentation</a></li><li><a href="https://apache.github.io/royale-docs/get-started">Get Started</a></li><li><a href="/docs">Docs</a></li><li><a href="/asdoc">API Reference</a></li><li><a href="https://github.com/apache/royale-asjs/wiki"><i class="fa fa-github"></i>Wiki</a></li><li><a href="https://stackoverflow.com/questions/tagged/apache-royale"><i class="fa fa-stack-overflow"></i> StackOverFlow Tag</a></li></ul><ul class="footer-list"><li class="community"><a href="/get-involved">Community</a></li><li><a href="/get-involved">Get Involved</a></li><li><a href="/mailing-lists">Mailing Lists</a></li><li><a href="/faq">FAQ</a></li></ul><ul class="footer-list"><li class="development"><a href="/source-code">Development</a></li><li><a href="https://github.com/apache/royale-asjs/wiki/Apache-Royale-Source-Code-Repositories"><i class="fa fa-github"></i> Github</a></li><li><a href="https://github.com/apache/royale-asjs/issues"><i class="fa fa-github"></i> Issues</a></li><li><a href="/source-code"><i class="fa fa-code"></i> Source Code</a></li></ul></div><div class="footer-column"><ul class="footer-list"><li class="social_t">Social</li><li><a href="https://twitter.com/apacheroyale"><i class="fa fa-twitter"></i> Twitter</a></li><li><a href="https://facebook.com/ApacheRoyaleSDK/"><i class="fa fa-facebook"></i> Facebook</a></li><li><a href="https://www.linkedin.com/groups/12118437"><i class="fa fa-linkedin"></i> LinkedIn</a></li><li><a href="/feed/index.xml"><i class="fa fa-rss"></i> RSS</a></li></ul><ul class="footer-list"><li class="apache"><a href="https://www.apache.org/">Apache</a></li><li><a href="https://www.apache.org/"><i class="fa fa-external-link-square"></i> Apache</a></li><li><a href="https://www.apache.org/foundation/contributing.html"><i class="fa fa-external-link-square"></i> Donations</a></li><li><a href="https://www.apache.org/events/current-event"><i class="fa fa-external-link-square"></i> Events</a></li><li><a href="https://www.apache.org/foundation/sponsorship.html"><i class="fa fa-external-link-square"></i> Sponsorship</a></li><li><a href="https://www.apache.org/foundation/thanks.html"><i class="fa fa-external-link-square"></i> Thanks</a></li><li><a href="https://www.apache.org/security/"><i class="fa fa-external-link-square"></i>Security</a></li></ul></div><div class="aboutusdiv"><p class="aboutus">About Us</p><p class="aboutus_p"><img class="aboutus-logo" src="/img/apache-royale-logo-footer-circle-grey.svg"><a href="/" class="aboutus_a">Apache Royale™</a> is a highly productive open source application technology for building expressive frontend applications that outputs to different formats and deploy consistently on all major browsers, desktops and devices.</p><p><img class="aboutus-apache-logo" src="/img/Apache_PoweredBy.svg"> <a href="/" class="aboutus_a">Apache Royale™</a>, <a href="https://www.apache.org" class="aboutus_a">Apache™</a> and the <a href="https://www.apache.org/foundation/press/kit/" class="aboutus_a">Apache feather logo™</a> are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners. Read more about our privacy policy on our <a href="/privacy-policy">Privacy Policy page</a>.</p></div></div><div class="asf">Copyright © 2017-2022 <a href="https://www.apache.org">The Apache Software Foundation</a>, Licensed under the <a href="https://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a></div></footer></body></html> |
