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

Introduction

Ocsigen Start is an application template written with Eliom, Js_of_ocaml, Ocsigen Toolkit, etc. It contains many standard features like user management, notifications, and many code examples.

Use it to learn Ocsigen or to quickly create your own Minimum Viable Product. It is probably the fastest way to get started with Ocsigen.

The application is cross-platform: it works as a Web app or as a mobile app for iOS or Android (via Cordova)..

Demo

If you want to test the demo application before installing Ocsigen Start, a working version is running here. You can also download the mobile app on Google Play store (for Android) or download the APK for Android or the iOS version (to be installed using XCode).

Ocsigen Start is composed by two main parts:

  • The generated code which gives a default behaviour to your application. Adapt it to your needs and remove the parts you don't need. Feel free to redistribute it as you wish.
    It includes a demo of many features from Eliom, Js_of_ocaml, Tyxml, Ocsigen Toolkit. Use it to learn quickly the main principles of multi-tier programming.
  • A library with:
    • User management: authentication, registration of new users with activation links sent by email, recover lost password, page to update settings, etc.
    • Tips for new users
    • Push notifications to send information to other users
    • ...

Implementation overview

Template

The library portion of Ocsigen Start contains core functionality that is common across Ocsigen Start applications, while the template can be customized for the specific application at hand.

The template additionally contains a demonstration of relevant Ocsigen Toolkit widgets. The demo portion can easily be removed.

Database

For implementing users, a database is needed. Specifically, we use PostgreSQL via the PGOCaml library. The template and the library make common assumptions about the database schema. The database thus needs to be instantiated in a certain way; this is automatically done by appropriate targets in the template's build system.

The same database can used for the specific needs of the application at hand. For that, new tables can be added. The original ones should remain in place for Ocsigen Start to work correctly.

Internationalization (i18n)

The template is available in multiple languages (English and French) using ocsigen-i18n. All translations used in the template are defined in the file {{assets/PROJECT_NAME_i18n.tsv}}. The Makefile rule {{i18n-udpate}} generates the i18n module. You need to use it every time the TSV file is updated.

See {{Makefile.i18n}} for rules about i18n and {{Makefile.options}} to personalize the internalization of your application (for example add new languages, change default language, change TSV filename).

Managing e-mails

The template application keeps track of users' e-mails and implements e-mail validation. For that, sendmail (or another mail transfer agent compatible with it) needs to be installed on the host.

Style

The application provides a standard style matching contemporary aesthetics. For this, we use SASS. The style can be customized by modifying the SASS files that are part of the template.

Installation

Ocsigen Start can be installed via OPAM. The package name is ocsigen-start. The template application can be instantiated via eliom-distillery:

eliom-distillery -name $APP_NAME -template os.pgocaml

(Replace $APP_NAME by the name of your application).

For details on launching the application, refer to the template's README.

Library overview

We provide a tour of the Ocsigen Start library. All modules have server- and client-side versions. (In the API documentation, there are links near the top of each module page for selecting the side.)

The template uses all these modules, and can thus act as a good starting guide. Look around!

User interface

Various modules for producing icons, messages, custom pages, tips, connection forms, etc.

  • Os_icons: manage CSS icons.
  • Os_msg: write messages in the browser console.
  • Os_page: utilities for building HTML pages that follow the standard Ocsigen Start layout.
  • Os_tips: display tips to the user.
  • Os_user_view: functions for creating password forms and other common UI elements appearing in applications and for managing the user connection box.
  • Os_uploader: ImageMagick-based tools for manipulating avatars.

Users and groups

  • Os_db: directly access the database. In many cases, it is a better idea to use higher-level modules (e.g., Os_user).
  • Os_types: core types shared by Os_db and the higher-level modules.

Communication

  • Os_notif: send notifications to connected users.
  • Os_comet: manage the bi-directional communication channel between client and server. This is a low-level module that you probably don't need.

Services, handlers, sessions

  • Os_session: manage user sessions, e.g., execute actions when users connect or disconnect.

Other utilities

  • Os_date: utilities for manipulating date and time values.
  • Os_platform: obtain information about the platform we are on (Android, iOS, ...).