Ocsigen

Eliom

Home

Doc

Eliom

Js_of_ocaml

Server

Lwt

Tyxml

Start

Warning: Reason support is experimental. We are looking for beta-tester and contributors.

Writing multi-platform apps with Eliom (Web and mobile)

Starting with Eliom 6.0, you can write HTML5 mobile apps with Eliom. It is also possible to have one single code base for your Web and mobile apps (Android, iOS, Windows ...).

The best way to start with this feature is to install Ocsigen Start. It contains all the instructions and a template with code samples that you can adapt to your needs.

Here are the main principle for writing multi-platform apps with Eliom:

  • Use responsive Web design to make your app work with any screen size.
  • Register all your services in shared sections. The mobile app will use the client-side implementation. The Web app will generate the pages server-side during the first request, and by default, subsequent pages will be generated client-side. For more info, see the client-side services chapter of this manual.
  • Be careful with the order of evaluation, which is different when pages are generated client-side. Client sections sent by the server will be executed when the page is ready and already diplayed. But if the page is generated client-side, client sections will be executed straight-away. You may sometimes want to delay their execution until the element is inserted in the page (try Ot_nodeready.nodeready).
  • Use Apache Cordova or Phonegap to access the mobile device APIs.
  • The main difference between the Web and mobile version is that the mobile app starts client-side, whereas the Web app is sent by the server. This means that the server won't be able to send global injections (~%v where v is a global server-side value) to the client. To solve this problem, Ocsigen Start provides a module Eliom_loader which will get the global data from the server when starting the app.
  • Define JavaScript variables __eliom_server and __eliom_app_name in the index.html of your mobile app, to set the main server and the name of the app. See Eliom_client.init_client_app and the default eliom.html file generated by Ocsigen Start.
  • Use function Eliom_client.is_client_app to test whether you are running a mobile app (an app that was started client-side). Ocsigen Start also has a class os-client-app on the html tag.
  • The JavaScript file generated by Js_of_ocaml will be included in your mobile app. But it must match exactly the version of the app that is running on the server. To ensure that, we recommend:
    • To do an automatic update of the client-side app when the server is updated (for example with Cordova Hot-code-push, as in Ocsigen Start)
    • And possibly to keep several versions of your server app, if you can, with a load balancer to reach the server that corresponds to the client-side version.
  • By default, all URLs generated by the client app are absolute. Use absolute:false for the URLs of all the local assets (css, js...)

Some caveats:

  • iOS does not handle cookies properly with HTML5 apps. Eliom implements a workaround, that you can activate by setting the JavaScript variable __eliom_use_cookie_substitutes to true in the main HTML page of your iOS app (see the file eliom.html generated by Ocsigen Start).
  • iOS support of HTML5 Web technologies is lagging behind other platforms and Apple does ot allow the use of another Web view. This may cause some troubles on iOS (slowness, display problems ...)

Suggestions:

  • Crosswalk can help you to have a modern Web view on old Android platforms. On iOS, use WkWebview.
  • Use Eliom_cscache to cache the values in your app.
  • Set JavaScript variable __eliom_debug_mode to true in your HTML file to set debug mode on client side. It corresponds to the option <debugmode/> in Ocsigen Server's configuration file (server-side).