Amazing. :-)
> On Jun 2, 2025, at 5:46 PM, Josh Tynjala <joshtynj...@bowlerhat.dev> wrote:
>
> I added the new [JSIncludeScript], [JSIncludeCSS], and [JSIncludeAsset]
> metadata to the docs. I also filled in several missing descriptions for
> existing metadata already mentioned on that page, and I added some
> other existing metadata that wasn't listed yet.
>
> --
> Josh Tynjala
> Bowler Hat LLC
> https://bowlerhat.dev/
>
>
> On Thu, May 29, 2025 at 4:47 AM Harbs <harbs.li...@gmail.com> wrote:
>
>> Amazing work!
>>
>> We should get this info added to the docs. I’m not sure where’s the best
>> location.
>>
>> Maybe here? https://apache.github.io/royale-docs/features/as3/metadata
>>
>>> On May 29, 2025, at 1:01 AM, Josh Tynjala <joshtynj...@bowlerhat.dev>
>> wrote:
>>>
>>> You may recall that I added some new options to Royale's compiler a
>> couple
>>> of months ago. They allow you to add .js, .css, and asset files to both
>>> SWCs and app projects, and the compiler will automatically add <script>
>> and
>>> <link> tags to your HTML file. Full details here in the archive:
>>>
>>> https://lists.apache.org/thread/5sws42w00jqdh0s5nhmb3ykdzs0nzj15
>>>
>>> These compiler options work best when the compiler should add the
>> <script>
>>> and <link> tags if any definition in the SWC gets referenced. For
>> example,
>>> if someone is making a SWC library that contains only AS3 externs for a
>>> particular JS library's types. All of the externs require the same
>> <script>
>>> and <link> tags, so these compiler options make it easy to add the
>>> necessary files without duplication.
>>>
>>> However, there's another use-case that wasn't covered yet. What if you
>> want
>>> to include <script>/<link> only when one specific class is referenced.
>> What
>>> if you don't want the hassle of creating a separate library for AS3
>>> externs? That's where the new metadata comes in.
>>>
>>> [JSIncludeScript(source="path/to/file.js")]
>>> [JSIncludeCSS(source="path/to/file.css")]
>>> [JSIncludeAsset(source="path/to/file.extension")]
>>> public class MyClass {}
>>>
>>> In the example above, the three files are copied, and <script> and <link>
>>> tags are added, only when MyClass is referenced in your project.
>>>
>>> It works similarly to the classic [Embed] tag provided by the SWF
>> compiler.
>>> You can specify a path to a file (relative to the .as file), and it will
>> be
>>> included at compilation-time. This metadata is available in both app
>>> projects,and SWC library projects. There are special directories in the
>> SWC
>>> to store the files, and mxmlc knows to check for the metadata, find the
>>> files in the SWC, and update the HTML template as needed.
>>>
>>> So, now there's two options for including scripts, styles, or arbitrary
>>> asset files. Which do you choose?
>>>
>>> - Does every definition in the library always require some additional
>>> files, use -js-include-script, -js-include-css, and -js-include-asset.
>>> - Does a single class or extern require any additional files, and if you
>>> don't use that class, skip them? Use [JSIncludeScript], [JSIncludeCSS],
>> or
>>> [JSIncludeAsset].
>>>
>>> We're using both methods in royale-asjs, depending on how those questions
>>> are answered.
>>>
>>> For instance, JewelTheme requires the Lato font. There isn't really a
>>> specific class to associate the Lato font with, and all Jewel components
>>> use the same font, so we use -js-include-css and -js-include-asset to
>>> include the necessary .css file and webfont files in the SWC.
>>>
>>> The Icons library includes both the Font Awesome and Material icons.
>>> Typically, you choose one set of icons or the other, and not both. So we
>>> use [JSIncludeCSS] and [JSIncludeAsset] on the specific classes where
>> those
>>> files are needed, and the compiler will use only what's referenced.
>>>
>>> The TabBarView class in Jewel needs the web-animations.min.js file.
>>> However, other Jewel components do not. It's a good place to choose
>>> [JSIncludeScript]. If a Jewel-based app doesn't use TabBar,
>>> web-animations.min.js won't be loaded at all, even if other Jewel
>>> components are used.
>>>
>>> Whether you are using the new compiler options or the new metadata, this
>>> should make it much easier to use external JS or CSS files in a Royale
>>> project. You can bundle the necessary files into your library SWCs, and
>> you
>>> don't need to create a custom html-template quite as often.
>>>
>>> --
>>> Josh Tynjala
>>> Bowler Hat LLC
>>> https://bowlerhat.dev/
>>
>>
