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)..
If you want to test the demo application before installing Ocsigen Start, a live version is running here.
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
Read this page to learn how to build your first Ocsigen Start app in 5 minutes.
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.
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.
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).
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.
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.
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.
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!
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_notif: send notifications to connected users.
- Os_email: send e-mails.
- Os_fcm_notif: send push notifications to mobile devices.
- 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_services: Eliom services pre-defined by Ocsigen Start. These produce the default user interface of the template. See the Eliom manual page on services for a general introduction to Eliom services.
- Os_handlers: The handlers (functions) that implement the services in Os_services. The Eliom manual page on service handlers explains how to implement handlers.
- Os_session: manage user sessions, e.g., execute actions when users connect or disconnect.
- Os_date: utilities for manipulating date and time values.
- Os_platform: obtain information about the platform we are on (Android, iOS, ...).
- : Ppx syntax extension to implement RPC.