This is an automated email from the ASF dual-hosted git repository. joshtynjala pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/royale-docs.git
commit 1e03e261fe20b7b587448fa60f836bf547027076 Author: Josh Tynjala <[email protected]> AuthorDate: Thu May 29 16:10:04 2025 -0700 document js-include compiler options and JSInclude metadata --- compiler/compiler-options.md | 57 ++++++++++++++++++++++++++++++++++++++++++++ features/as3/metadata.md | 43 +++++++++++++++++++++++++++++++++ 2 files changed, 100 insertions(+) diff --git a/compiler/compiler-options.md b/compiler/compiler-options.md index 7462e05..13fcb0c 100644 --- a/compiler/compiler-options.md +++ b/compiler/compiler-options.md @@ -192,6 +192,9 @@ The [**mxmlc** and **compc** compilers](compiler/command-line-compiler-usage) bu - [`-js-default-initializers`](compiler/compiler-options#js-default-initializers) -- With JavaScript targets, determines if uninitialized variables are automatically initialized with default values. - [`-js-dynamic-access-unknown-members`](compiler/compiler-options#js-dynamic-access-unknown-members) - With JavaScript targets, replaces `.memberName` member access with `["memberName"]` dynamic access, if the member is unrecognized to prevent Google Closure Compiler from renaming the member. - `-js-getter-prefix` `<string>` -- Sets the string used as a prefix for getter functions in the generated _.js_ files. +- [`-js-include-asset` `<string>`](compiler/compiler-options/#js-include-asset) -- Copies an asset file to the output directory. +- [`-js-include-css` `<string>`](compiler/compiler-options/#js-include-css) -- Copies a _.css_ file to the output directory and adds a `<link rel="stylesheet">` element to the HTML. +- [`-js-include-script` `<string>`](compiler/compiler-options/#js-include-script) -- Copies a _.js_ file to the output directory and adds a `<script>` element to the HTML. - [`-js-load-config` `<filename>`](compiler/compiler-options#js-load-config) -- Overrides `-load-config` for JavaScript targets. - [`-js-output` `<filename>`](compiler/compiler-options#js-output) -- Sets the output directory path of the generated _.js_ files. - `-js-output-optimization` `[optimization]` `[...]` @@ -467,6 +470,60 @@ If the definition of a member cannot be resolved at compile time, emit dynamic a <additionalCompilerOptions>-js-dynamic-access-unknown-members=true;</additionalCompilerOptions> ``` +### js-include-asset {#js-include-asset} + +_Available since Royale 0.9.13_ + +Copies a custom asset file to the the output directory. Typically combined with `-js-include-css` or `-js-include-script`. + +```sh +-js-include-asset+=path/to/asset-file.png +``` + +In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and asset files will be copied into an _assets_ sub-directory. + +#### Maven configuration: + +```xml +<additionalCompilerOptions>-js-include-asset+=path/to/asset-file.png;</additionalCompilerOptions> +``` + +### js-include-css {#js-include-css} + +_Available since Royale 0.9.13_ + +Copies a _.css_ file to the output directory and adds a `<link rel="stylesheet">` element to the HTML. If the _.css_ file references any external asset files, this option may be combined with `-js-include-asset`. + +```sh +-js-include-css+=path/to/file.css +``` + +In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and _.css_ files will be copied into a _css_ sub-directory. + +#### Maven configuration: + +```xml +<additionalCompilerOptions>-js-include-css+=path/to/file.css;</additionalCompilerOptions> +``` + +### js-include-script {#js-include-script} + +_Available since Royale 0.9.13_ + +Copies a _.js_ file to the output directory and adds a `<script>` element to the HTML. If the _.js_ file references any external asset files, this option may be combined with `-js-include-asset`. + +```sh +-js-include-script+=path/to/file.js +``` + +In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and _.js_ files will be copied into a _scripts_ sub-directory. + +#### Maven configuration: + +```xml +<additionalCompilerOptions>-js-include-script+=path/to/file.js;</additionalCompilerOptions> +``` + ### js-load-config {#js-load-config} Specifies the locations of XML configuration files that define extra compiler options for JavaScript output. diff --git a/features/as3/metadata.md b/features/as3/metadata.md index 618e98c..73cd248 100644 --- a/features/as3/metadata.md +++ b/features/as3/metadata.md @@ -455,6 +455,49 @@ public function get data():Object; InstanceType +## JSIncludeAsset + +_Available since Royale 0.9.13_ + +Royale applications that target JavaScript may sometimes rely on third-party libraries and stylesheets. The Royale compiler provides a way to copy any additional asset files required by these _.js_ and _.css_ files to the output directory relative to the generated _index.html_ file. For example, a third-party library might require PNG or JPEG image files, or `@font-face` CSS may reference [web font](https://developer.mozilla.org/en-US/docs/Learn_web_development/Core/Text_styling/Web_font [...] + +```as3 +[JSIncludeAsset(source="myimage.png")] +public class MyClass +``` + +In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and asset files will be copied into an _assets_ sub-directory. + +## JSIncludeCSS + +_Available since Royale 0.9.13_ + +Royale applications that target JavaScript may sometimes rely on third-party stylesheets that don't need to be processed for use in MXML. The Royale compiler provides a way to copy additional _.css_ files to the output directory relative to the generated _index.html_ file, and it will automatically generate `<link rel="stylesheet">` elements in the HTML `<head>` section. + +Add `[JSIncludeCSS]` metadata to an ActionScript class, and set the `source` field to the path of a _.css_ file. Relative paths are resolved in relation to the file that contains the metadata. + +```as3 +[JSIncludeCSS(source="mystyles.css")] +public class MyClass +``` + +In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and _.css_ files will be copied into a _css_ sub-directory. + +## JSIncludeScript + +_Available since Royale 0.9.13_ + +Royale applications that target JavaScript may sometimes rely on third-party libraries or scripts that are not written in ActionScript. The Royale compiler provides a way to copy additional _.js_ files to the output directory relative to the generated _index.html_ file, and it will automatically generate `<script>` elements in the HTML `<head>` section. + +Add `[JSIncludeScript]` metadata to an ActionScript class, and set the `source` field to the path of a _.js_ file.Relative paths are resolved in relation to the file that contains the metadata. + +```as3 +[JSIncludeScript(source="myscript.js")] +public class MyClass +``` + +In the output directory, typically _bin/js-debug_ or _bin/js-release_, the _index.html_ file will be generated in the root, and _.js_ files will be copied into a _scripts_ sub-directory. + ### Managed Managed
