Fantom

 

22. JavaScript

Overview

Fantom provides support for compiling to JavaScript and running in JavaScript VMs such as web browsers. Most of the sys API is available, however not all pods and APIs are accessible due to limitations of the JavaScript VM environment.

Js Facet

You must explicitly mark types you intend to compile to JavaScript using the Js facet:

@Js
class GonnaBeJs
{
  Void sayHi() { Win.cur.alert("Hello!") }
}

Natives

To compile JavaScript natives, add the source directories to your build script using the jsDirs field. See Build Pod for an example.

TODO: flush out details

Deployment

The JavaScript compiler works by translating Fantom source code directly to JavaScript source code at compile time. This differs from the JVM/CLR, which work by using an intermediate format and translating to the target platform at runtime.

All Fantom source code in a pod marked as @Js will be compiled to a single JavaScript source file. This file will also include reflection information and other meta-data needed at runtime. The file is named <podname>.js and is packaged into the root directory of the pod file.

Running

You can run JavaScript compiled from Fantom by loading the pod's JavaScript source file into any JavaScript VM. There are no special requirements, other than loading the pods in the correct dependency order.

Testing

If you simply want to run your Tests from the command line, the Java runtime provides a built-in test framework using Rhino (requires Java 1.6+):

fan compilerJs::TestRunner

The test runner has the same semantics as the normal fant tool, but will load and execute your pod's source and tests in the Rhino scripting engine.

Browsers

Running Fantom JavaScript in the browser requires a bit more work. First you must expose the pods' JavaScript source files as URIs from your server. The simplest mechanism is to use FileWeblet:

file := `fan://$podName/${podName}.js`.get
if (!file.exists) { res.sendErr(404); return }
FileWeblet(file).onService

Then you must load the pods in the correct dependency order in your <head> tag. Finally, to "mount" the JavaScript runtime, invoke WebUtil.jsMain:

out.head
  out.title.w("My Page").titleEnd
  out.includeJs(`/pod/sys/sys.js`)
  out.includeJs(`/pod/concurrent/concurrent.js`)
  out.includeJs(`/pod/web/web.js`)
  out.includeJs(`/pod/gfx/gfx.js`)
  out.includeJs(`/pod/dom/dom.js`)
  out.includeJs(`/pod/fwt/fwt.js`)
  out.includeJs(`/pod/myPod/myPod.js`)
  WebUtil.jsMain(out, "myPod::Main")
  out.headEnd

A complete example is available in js-demo. Note that this example illustrates dynamically compiling code into the page. This is not required (or normal). The only requirement is to load your pods and invoke WebUtil.jsMain. There is also no requirement that fwt be used. You can simply run plain JavaScript, or interact with the DOM directly with the dom pod.

Running outside of Fantom

While running or serving Fantom JavaScript is easiest from a Fantom runtime, there is no requirement for that. You must first load the pods' JavaScript source into your VM (in order), or expose them from your web server using the pod zipfiles.

Once the pods have been loaded and interpreted by your VM or the browser's VM, you can launch any class using this syntax:

fan.<myPod>.<myType>.<method>

fan.myPod.MyType.staticMain();           // invoke a static method
fan.myPod.MyType.make().instanceMain();  // invoke method from instance