package fmlib_js

Type of a javascript exception.

of_exception exn returns Some js_error if the exception exn is an exception raised by javascript code and None if exn is an exception raised by ocaml code.

Raise the javascript exception js_error

raise_js error Raise a javascript exception.

log_string str Log the string str via console.log.

log_value v Log the javascript value v via console.log.

Type of the implementation function of the node module.

The implementation function has the form

let node (state: 'state) (callback: Value.t -> unit): 'msg -> unit =
    ... (* initialisation code *)
    ...
    fun msg ->
        ... (* receive a message from the javascript side *)
        ...

node_module state_decode msg_decode node_function

An ocaml program my_app.ml with an ocaml statement of the form

let _ =
    node_module state_decode msg_decode node_function

compiles to my_app.js which can be loaded as a module in a nodejs script via

           var my_app = require('./my_app.js')

The javascript value my_app is a javascript object of the form

           {init: (initial_state, callback) => { ... }}

which can be used in the following way:

            function callback (msg) {
                ...     // actions on receiving a message from 'my_app'
            }
            var state =
                     ... // initial state which can be decoded
                         // by 'state_decode'

            var post_to_my_app = my_app.init(state, callback)

            post_to_my_app (msg)    // send message to 'my_app',
                                    // must be decodable via 'msg_decode'

Type of the implementation function of the browser application with javascript interop.

browser_application state_decode msg_decode browser_function

An ocaml program my_app.ml with an ocaml statement of the form

let _ =
    browser_application
        "my_app"            (* Unique name in the browser *)
        state_decode
        msg_decode
        browser_function

can be compiled to a javascript file my_app.js. This file my_app.js can be included within a html page in a script tag

            <script type="text/javascript" src="my_app.js"></script>

In the html file we need some javascript code to interact with the browser application.

 <script>
            var state = ...         // javascript value which can be decoded
                                    // by 'state_decode'

            var postMessage         // variable representing a function to
                                    // post messages to 'my_app'

            var callback (msg) {
                ...                 // actions on receiving messages from
                ...                 // 'my_app'
                ...
                postMessage (...)   // send a message to 'my_app'
            }
            </script>

At the end of the body the application my_app can be started by

            <script>
                postMessage = my_app.init (state, 'element_id', callback)
            </script>

Warning: The ocaml browser application shall not be initialized before the body and in particular the element is available. Therefore it is best to initialize the application at the end of the html body.

It is convenient to initialize the browser application with an element id below which the browser application should install itself in the dom tree. This can be used to avoid conflicting dom accesses between the javascript side and the ocaml browser application.

make_global name value Make the javascript value value accessible from javascript code via the global name name.

Caution:

If the global name name already exists, it will be overwritten. This has fatal consequences if you overwrite e.g. setTimeout or document or other other used global variables or global functions.

It is recommended to use some prefix like my_app_... in name in order to not pollute the global namespace.

get_global name Check, if name exists in the global enviroment and if yes, return the corresponding javascript value. Use Decode to check, if the global is a function, an object, a number etc.

new_global constructor args

Construct a new javascript object using the constructor constructor feeding it with the arguments args.

Precondition: The constructor must exist and it has to accept the arguments. If not, an exception is thrown.

export [| name1, val1; name2, val2; ... |]

Export the javascript object consisting of the fields name1, name2, ... to the surrounding javascript code.

This function is used if you want to write a module to be used in a node application. In the javascript code you write

var my_app = require('./my_app.js')

and then the javascript variable my_app is an object containing all the exported fields.