A complete tutorial with an example
This repository contains the list of bindings in OCaml to Cordova plugins using gen_js_api.
- ocaml-cordova-plugin-list
-
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).
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.
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.
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.
- ActivityIndicator:
- Background mode:
- Barcode Scanner:
- Battery:
- Binding to cordova object:
- Camera:
- Clipboard:
- Contacts:
- Source files: https://github.com/dannywillems/ocaml-cordova-plugin-contacts Partial, not released
- Date Picker:
- Device:
- Device-motion:
- Device-orientation:
- Dialogs:
- Email composer:
- FCM:
- Source files: https://github.com/dannywillems/ocaml-cordova-plugin-fcm
- Example (with Ocsigen): https://github.com/dannywillems/ocsigen-mobile-push-notification-example/tree/fcm
- File:
- File opener:
- File-transfer:
- Geolocation:
- Globalization:
- Hot code push
- Keyboard:
- Image Picker:
- Inappbrowser:
- Insomnia:
- Loading Spinner:
Deprecated: working on Cordova < 4
- Local notifications:
- Source files: https://github.com/dannywillems/ocaml-cordova-plugin-local-notifications Partial
- Media:
- Media-capture:
- Network-information:
- Progress: Only iOS!!!
- Push notifications:
- Source files: https://github.com/dannywillems/ocaml-cordova-plugin-push-notifications Tested
- QRScanner: Only iOS!!!
- Screen orientation:
- SIM Card:
- SMS:
- Social Sharing
- Source files: https://github.com/dannywillems/ocaml-cordova-plugin-social-sharing Partial
- SplashScreen:
- StatusBar:
- Toast:
- Touch ID: Only iOS!!
- Vibration:
- Videoplayer: Android only
- Calendar
- [Facebook] (https://github.com/jeduan/cordova-plugin-facebook4)
- Google Maps
- PayPal
- NFC
- Firebase
- Badge
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_readyThe 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
Simply make a pull request and add it in the TO-DO section. Other people could be also interested.
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.
- 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.
-
Danny Willems (most bindings)
- Twitter: @dwillems42
- GitHub: https://github.com/dannywillems
- Email: contact@danny-willems.be
- Website: danny-willems.be
-
Omar Chebib (local-notifications, background-mode, contact without object)
- GitHub: https://github.com/o-marshmallow
- Email: omarchebib@gmail.com
- Danny Willems
- Twitter: @dwillems42
- GitHub: https://github.com/dannywillems
- Email: contact@danny-willems.be
- Website: danny-willems.be