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

Reply via email to