{0 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/page-index}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
{{!page-"clientserver-services"}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/page-index}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/page-index}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/page-index}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/page-index}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).
