sihl
  1. Overview
  2. Docs

This module allows you to build RESTful web pages quickly.

type action = [
  1. | `Index
  2. | `Create
  3. | `New
  4. | `Edit
  5. | `Show
  6. | `Update
  7. | `Destroy
]
type query = {
  1. filter : string option;
  2. limit : int option;
  3. offset : int option;
  4. sort : [ `Desc | `Asc ] option;
}

A query describes the search terms of an `Index action and it represents a partial view on a collection that is sorted and filtered.

val of_request : Request.t -> query

of_request request returns the query by parsing the query string of the request.

val to_query_string : query -> string

to_query_string query returns the query string representation of a query that can be used safely in URIs. Note that the question mark ? is also part of it.

val next_page : query -> int -> query option

next_page query total returns a query that represents the result of the next page given the query of the current page.

total is the total number of items in the collection.

None is returned if the current page is already the last page and there is no next page.

val previous_page : query -> query option

previous_page query returns a query that represents the previous page given the query of the current page.

None is returned if the current page is the first page and there is no previous page.

val last_page : query -> int -> query option

last_page query total returns a query that represents the result of the last page given the query of the current page.

total is the total number of items in the collection.

None is returned if the current page is already the last page.

val first_page : query -> query option

first_page query total returns a query that represents the result of the first page given the query of the current page.

None is returned if the current page is already the first page.

val query_filter : query -> string option

query_filter query returns the string representation of the filter keyword if it exists.

val query_sort : query -> string option

query_sort query returns the string representation of the sort keyword if it exists.

val query_limit : query -> string option

query_limit query returns the string representation of the limit if it exists.

val query_offset : query -> string option

query_offset query returns the string representation of the offset if it exists.

type form = (string * string option * string option) list

form represents a validated and decoded form. One element consists of (name, input, error).

name is the schema field name and the HTML input name.

input is the input of the form that was submitted, it might not be present. Use it to restore form values after it was submitted and validation or decoding failed.

error is the error message of the validation or decoding.

val find_form : string -> form -> string option * string option

find_form name form returns the (value, error) of a form input element with the name.

The value is the submitted value of the input element. The value is set even if the submitted form failed to decode or validate. Use the submitted values to populate the form that can be fixed and re-submitted by the user.

The error message comes from either the decoding, validation or CRUD service. It can be shown to the user.

module type SERVICE = sig ... end

The SERVICE interface has to be implemented by a CRUD service that drives the resource with its business logic.

module type VIEW = sig ... end

The VIEW interface needs to be implemented by a module that renders HTML.

module type CONTROLLER = sig ... end

A module of type CONTROLLER can be used to create a resource with resource_of_controller. Use a controller instead of a service and a view if you need low level control.

val resource_of_service : ?only:action list -> string -> ('meta, 'ctor, 'resource) Conformist.t -> view:(module VIEW with type t = 'resource) -> (module SERVICE with type t = 'resource) -> router list

resource_of_service ?only name schema ~view service returns a list of routers that can be combined with choose that represent a resource.

A resource pizzas creates following 7 routers:

        GET       /pizzas          `Index  Display a list of all pizzas
        GET       /pizzas/new      `New    Return an HTML form for creating a new pizza
        POST      /pizzas          `Create Create a new pizza
        GET       /pizzas/:id      `Show   Display a specific pizza
        GET       /pizzas/:id/edit `Edit   Return an HTML form for editing a pizza
        PATCH/PUT /pizzas/:id      `Update Update a specific pizza
        DELETE    /pizzas/:id      `Delete Delete a specific pizza

only is an optional list of actions. If only is set, routers are created only for the actions listed.

name is the name of the resource. It is good practice to use plural as the name is used to build the resource path of the URL.

schema is the conformist schema of the resource.

view is the view service of type VIEW of the resource. The view renders HTML.

service is the underlying CRUD service of type SERVICE of the resource.

val resource_of_controller : ?only:action list -> string -> ('meta, 'ctor, 'resource) Conformist.t -> (module CONTROLLER with type t = 'resource) -> router list

resource_of_controller ?only name schema controller returns the same list of routers as resource_of_service. resource_of_controller takes one module of type CONTROLLER instead of a view and a service.

If you implement your own controller you have to do all the wiring yourself, but you gain more control.