ocaml-cordova-plugin-list

This repository contains the plugin list of bindings in OCaml to cordova plugins using js_of_ocaml and gen_js_api.

What's cordova, js_of_ocaml and gen_js_api ?

Cordova allows you to develop hybrid mobile application using web technologies such as HTML, CSS and Javascript. For more informations, 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. It's a way to develop Cordova application using ocaml. For more info, see the ocsigen project which contains js_of_ocaml.

Gen_js_api:

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
withthe same binding definitions (for instance, Bucklescript, or direct
embedding of a JS engine in a native OCaml application).

Source: gen_js_api repository

How to contribute.

The name of the binding repository needs to be: ocaml-name where name is the official cordova plugin name. For example, the binding to cordova-plugin-camera is in the ocaml-cordova-plugin-camera repository.

This convention is not respected for 'non-official' plugin such as Toast which is officially in the cordova-plugin-x-toast. The binding repository is cordova-plugin-toast. Same for the Touch ID plugin whose the official plugin is cordova-universal-touchid.

You can contribute by testing the plugins, especially on Windows Phone and ios devices.

Every plugins has an example application. Some are not done because we do not have time to do it (or we do not have any idea how to try it). Do not hesitate to develop them or test them. Those which don't have any example application were not tested but the code compiles.

How does it work ?

The majority of bindings has two branches: js_of_ocaml and gen_js_api (master).

The js_of_ocaml branch was the first done binding. It can be used on compiler <= 4.02.3. The weakness is the binding is low-level and depends on the js_of_ocaml library. You need to use Js type given by js_of_ocaml to use it. This binding is not provided for each plugin because we do not recommend to use this tag.
The gen_js_api branch (= master) is the second binding and uses only gen_js_api. It allows you to use any ocaml to javascript compiler and has high level binding: you use 'standard' ocaml type such as string instead of Js.string type. The weakness is gen_js_api needs compiler >= 4.03.0.

We recommend to use gen_js_api for simplicity and maintainability because we focus on the gen_js_api development.

For the gen_js_api binding, we only provide the mli file. You need to use gen_js_api to get the ml file and compile the mli and ml files as said in the gen_js_api use instruction.

How can I use a binding ?

It's not in release !!

Each binding has an opam repository you need to pin. For example, the binding to the camera is contained in the ocaml-cordova-plugin-camera repository. You need to pin it with:

opam pin add cordova-plugin-camera https://github.com/dannywillems/ocaml-cordova-plugin-camera

If the plugin needs the binding to the standard js library such as device-motion, you need to pin the ocaml-js-stdlib repository first. In each repository, you have the command you need to use.

Improvements/To-do (contribute !!)

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.
Javascript function has sometimes a lot of parameters. Do we add labels for the bindings ?
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 ?

If you have any idea, please contact us.