List of bindings in OCaml to cordova plugins.
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
res
README.md

README.md

ocaml-cordova-plugin-list

Join the chat at https://gitter.im/dannywillems/ocaml-cordova-plugin-list

A complete tutorial with an example

This repository contains the list of bindings in OCaml to Cordova plugins using gen_js_api.

What are Cordova, js_of_ocaml and gen_js_api?

  • Cordova allows you to develop hybrid mobile applications using web technologies such as HTML, CSS and JavaScript. For more information, see the official website. Through Cordova plugins, you can access to the native components. To learn how to make Cordova plugins, see the official tutorial. You can find the official Cordova plugin list here.

  • js_of_ocaml provides a compiler from OCaml to JavaScript. Since Cordova applications use JavaScript, js_of_ocaml provides a way to develop mobile application using OCaml. For more info, see the Ocsigen project which contains js_of_ocaml.

  • gen_js_api aims at simplifying the creation of OCaml bindings for JavaScript libraries. It must currently be used with the js_of_ocaml compiler, although other ways to run OCaml code "against" JavaScript might be supported later with the same binding definitions (for instance, Bucklescript, or direct embedding of a JS engine in a native OCaml application).

How does it work?

Some bindings has two branches: gen_js_api (master) and js_of_ocaml.

  • The gen_js_api branch (= master) uses only gen_js_api. It will allow you to use any OCaml to javascript compiler and has high level binding: you use «standard» OCaml types such as string instead of Js.js_string type. The weakness is gen_js_api needs compiler >= 4.03.0.

  • DEPRECATED. The js_of_ocaml branch was the first done binding. It can be used on compiler >= 4.00.0. The weakness is the binding is low-level and depends on the js_of_ocaml library. You need to use Js types given by js_of_ocaml to use it. Bindings are not provided for each plugin.

Use gen_js_api for simplicity and maintainability because js_of_ocaml branch is no longer supported.

How can I use a binding?

Needs compiler >= 4.03.0

Each binding has one repository for some reasons: maintainability, update easier, add to list easier and often we only need one binding, not all).

For each bindings listed here, the corresponding opam repository begins with cordova-plugin- and ends with the plugin name. For example, the binding to the camera plugin is cordova-plugin-camera. So, if you want to install the camera binding, you need to use

opam install cordova-plugin-camera

The appropriate opam package is given in the appropriate GitHub repository (list is given below).

If the plugin needs the binding to the standard js library such as device-motion, you need to pin the ocaml-js-stdlib first. If the plugin needs it, it is mentioned in the GitHub repository.

What about documentation for each bindings?

Bindings interface are very close to initial plugins JavaScript interface. For example, for cordova-plugin-camera which allows you to take a picture through navigator.camera.getPicture JavaScript function, you use Cordova_camera.get_picture OCaml function. The equivalent OCaml code to

var success_callback = function(success) {
	console.log(success);
}

var error_callback = function(error) {
	console.log(error);
}

var options = {quality: 25, destinationType: Camera.DestinationType.DATA_URL}

navigator.camera.getPicture(success_callback, error_callback, options)

is

let success_callback success = Jsoo_lib.console_log success in

let error_callback error = Jsoo_lib.console_log error in

let options =
	Cordova_camera.create_options
		~quality:25
		~destination_type:Cordova_camera.Data_url
		()
	in

Cordova_camera.get_picture success_callback error_callback ~opt:options ()

(supposing Jsoo_lib.console_log is the binding to console.log function, see jsoo_lib). Most functions are implemented with optional arguments and these arguments are at the end of the arguments list, so unit is often mandatory.

As the OCaml interface is very close to JavaScript interface, no OCaml documentation is done yet. Feel free to contribute

Bindings which don't have example application are not tested. Please give a feedback about it and open issues if it's the case.

Bindings list

In development

Not planned

MISC

Be careful!

Most of bindings create new objects which are only available when the deviceready event fires. You need to have as first lines:

let on_device_ready () =
	(* Your code using plugins here *)

let _ = Cordova.Event.device_ready on_device_ready

The module Cordova comes from the binding to the cordova object so you need to add it for each project. This module can be installed with

opam install cordova

Help me! I need a binding but it is not listed!

Simply make a pull request and add it in the TO-DO section. Other people could be also interested.

I did a binding to a Cordova plugin which are not listed or not yet done.

It will be a pleasure to add your binding to the list. Don't forget to add a license to your repository: LGPL or less restrictive (MIT, Apache, etc) is recommended. GPL will not be accepted because is too much restrictive.

Here some plugin market for inspiration

  • Telerik market: Cordova and NativeScript plugin market. Can be a source of inspiration.
  • PlugReg: list of Cordova plugins.

Improvements and To-do

  • Create a bindings plugin market like Cordova plugins have here.
  • For the moment, there are no OCaml documentations: we redirect you in the original plugin documentation and/or write comments in ml and mli files. We would like to have a full documentation for OCaml users.
  • We could improve some plugins by using the cordova object. For example, some files destination are only available on ios devices and for the moment, the file plugin allows you to use them on android devices which gives null.
  • For the moment, you also need to add manually the original Cordova plugin with
cordova plugin add [plugin_name]

It could be interesting to analyse the source code of the Cordova application (written in OCaml), detect used plugins and automatically run the cordova plugin add command. Use merlin method to analyse the code?

  • A binary like cordova to create new Cordova project in OCaml and simplify when the user wants to add a plugin.

Contributors

Maintainer

Related projects