That is very clearly explained with those examples, and the feature sounds amazing Josh, thank you so much for this work. -Greg
On Thu, 29 May 2025, 12: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/ >
