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/ > >
