Yes, I have committed this change already. For reference, here's a link to my commit in royale-asjs where I switched some projects from using -js-include-* options to using [JSInclude*] metadata instead.
https://github.com/apache/royale-asjs/commit/5b52c04df635873f7ced84af0424eb6a5183d377 -- Josh Tynjala Bowler Hat LLC https://bowlerhat.dev/ On Thu, May 29, 2025 at 1:50 AM Maria José Esteve <mjest...@iest.com> wrote: > [en] > @Josh, have you committed this change? > > [es] > @Josh, ¿has subido esta modificación? > > Hiedra > > -----Mensaje original----- > De: Josh Tynjala <joshtynj...@bowlerhat.dev> > Enviado el: jueves, 29 de mayo de 2025 0:01 > Para: Apache Royale Development <dev@royale.apache.org> > Asunto: [JSIncludeScript], [JSIncludeCSS], and [JSIncludeAsset] compiler > metadata > > 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/ >
