Rocket

Unnamed repository; edit this file 'description' to name the repository.
Log | Files | Refs | README

commit 8741e678f8238238d58be0f8e8c6c5c7fa39a4b1
parent 085a1430750e3c52c06ead2547ff29d473899c56
Author: Sergio Benitez <sb@sergio.bz>
Date:   Fri, 12 Oct 2018 18:52:38 -0700

Document contrib modules.

Diffstat:
Mcontrib/lib/src/json.rs | 3+++
Mcontrib/lib/src/msgpack.rs | 3+++
Mcontrib/lib/src/templates/mod.rs | 166+++++++++++++++++++++++++++++++++++++++++++++++++++++++------------------------
Mcontrib/lib/src/uuid.rs | 5+++--
4 files changed, 124 insertions(+), 53 deletions(-)

diff --git a/contrib/lib/src/json.rs b/contrib/lib/src/json.rs @@ -1,3 +1,6 @@ +//! Automatic JSON (de)serialization support. +//! +//! See the [`Json`](json::Json) type for further details. extern crate serde; extern crate serde_json; diff --git a/contrib/lib/src/msgpack.rs b/contrib/lib/src/msgpack.rs @@ -1,3 +1,6 @@ +//! Automatic MessagePack (de)serialization support. +//! +//! See the [`MsgPack`](msgpack::MessagePack) type for further details. extern crate serde; extern crate rmp_serde; diff --git a/contrib/lib/src/templates/mod.rs b/contrib/lib/src/templates/mod.rs @@ -1,3 +1,116 @@ +//! Dynamic template engine support for handlebars and tera. +//! +//! # Overview +//! +//! The general outline for using templates in Rocket is: +//! +//! 0. Enable the `rocket_contrib` feature corresponding to your templating +//! engine(s) of choice: +//! +//! ```toml +//! [dependencies.rocket_contrib] +//! version = 0.4.0-dev +//! default-features = false +//! features = ["handlebars_templates", "tera_templates"] +//! ``` +//! +//! 1. Write your template files in Handlebars (extension: `.hbs`) or tera +//! (extensions: `.tera`) in the templates directory (default: +//! `{rocket_root}/templates`). +//! +//! 2. Attach the template fairing, [`Template::fairing()`]: +//! +//! ```rust +//! # extern crate rocket; +//! # extern crate rocket_contrib; +//! use rocket_contrib::templates::Template; +//! +//! fn main() { +//! rocket::ignite() +//! .attach(Template::fairing()) +//! // ... +//! # ; +//! } +//! ``` +//! +//! 3. Return a [`Template`] using [`Template::render()`], supplying the name +//! of the template file minus the last two extensions, from a handler. +//! +//! ```rust +//! # #![feature(proc_macro_hygiene, decl_macro)] +//! # #[macro_use] extern crate rocket; +//! # #[macro_use] extern crate rocket_contrib; +//! # fn context() { } +//! use rocket_contrib::templates::Template; +//! +//! #[get("/")] +//! fn index() -> Template { +//! let context = context(); +//! Template::render("template-name", &context) +//! } +//! ``` +//! +//! ## Discovery +//! +//! Template names passed in to [`Template::render()`] must correspond to a +//! previously discovered template in the configured template directory. The +//! template directory is configured via the `template_dir` configuration +//! parameter and defaults to `templates/`. The path set in `template_dir` is +//! relative to the Rocket configuration file. See the [configuration +//! chapter](https://rocket.rs/guide/configuration/#extras) of the guide for +//! more information on configuration. +//! +//! The corresponding templating engine used for a given template is based on a +//! template's extension. At present, this library supports the following +//! engines and extensions: +//! +//! * **Tera**: `.tera` +//! * **Handlebars**: `.hbs` +//! +//! Any file that ends with one of these extension will be discovered and +//! rendered with the corresponding templating engine. The _name_ of the +//! template will be the path to the template file relative to `template_dir` +//! minus at most two extensions. The following table illustrates this mapping: +//! +//! | path | name | +//! |-----------------------------------------------|-----------------------| +//! | {template_dir}/index.html.hbs | index | +//! | {template_dir}/index.tera | index | +//! | {template_dir}/index.hbs | index | +//! | {template_dir}/dir/index.hbs | dir/index | +//! | {template_dir}/dir/index.html.tera | dir/index | +//! | {template_dir}/index.template.html.hbs | index.template | +//! | {template_dir}/subdir/index.template.html.hbs | subdir/index.template | +//! +//! The recommended naming scheme is to use two extensions: one for the file +//! type, and one for the template extension. This means that template +//! extensions should look like: `.html.hbs`, `.html.tera`, `.xml.hbs`, etc. +//! +//! ## Template Fairing +//! +//! Template discovery is actualized by the template fairing, which itself is +//! created via [`Template::fairing()`] or [`Template::custom()`], the latter of +//! which allows for customizations to the templating engine. In order for _any_ +//! templates to be rendered, the template fairing _must_ be +//! [attached](rocket::Rocket::attach()) to the running Rocket instance. Failure +//! to do so will result in a run-time error. +//! +//! Templates are rendered with the `render` method. The method takes in the +//! name of a template and a context to render the template with. The context +//! can be any type that implements [`Serialize`] from [`serde`] and would +//! serialize to an `Object` value. +//! +//! In debug mode (without the `--release` flag passed to `cargo`), templates +//! will be automatically reloaded from disk if any changes have been made to +//! the templates directory since the previous request. In release builds, +//! template reloading is disabled to improve performance and cannot be enabled. +//! +//! [`Serialize`]: serde::Serialize +//! [`Template`]: templates::Template +//! [`Template::fairing()`]: templates::Template::fairing() +//! [`Template::custom()`]: templates::Template::custom() +//! [`Template::render()`]: templates::Template::render() + extern crate serde; extern crate serde_json; extern crate glob; @@ -35,56 +148,7 @@ use rocket::http::{ContentType, Status}; const DEFAULT_TEMPLATE_DIR: &str = "templates"; -/// The Template type implements generic support for template rendering in -/// Rocket. -/// -/// Templating in Rocket works by first discovering all of the templates inside -/// the template directory. The template directory is configurable via the -/// `template_dir` configuration parameter and defaults to `templates/`. The -/// path set in `template_dir` should be relative to the Rocket configuration -/// file. See the [configuration -/// chapter](https://rocket.rs/guide/configuration/#extras) of the guide for -/// more information on configuration. -/// -/// Templates are discovered according to their extension. At present, this -/// library supports the following templates and extensions: -/// -/// * **Tera**: `.tera` -/// * **Handlebars**: `.hbs` -/// -/// Any file that ends with one of these extension will be discovered and -/// rendered with the corresponding templating engine. The name of the template -/// will be the path to the template file relative to `template_dir` minus at -/// most two extensions. The following are examples of template names (on the -/// right) given that the template is at the path on the left. -/// -/// * `{template_dir}/index.html.hbs` => index -/// * `{template_dir}/index.tera` => index -/// * `{template_dir}/index.hbs` => index -/// * `{template_dir}/dir/index.hbs` => dir/index -/// * `{template_dir}/dir/index.html.tera` => dir/index -/// * `{template_dir}/index.template.html.hbs` => index.template -/// * `{template_dir}/subdir/index.template.html.hbs` => subdir/index.template -/// -/// The recommended naming scheme is to use two extensions: one for the file -/// type, and one for the template extension. This means that template -/// extensions should look like: `.html.hbs`, `.html.tera`, `.xml.hbs`, etc. -/// -/// Template discovery is actualized by the template fairing, which itself is -/// created via the [`Template::fairing()`] or [`Template::custom()`] method. In -/// order for _any_ templates to be rendered, the template fairing _must_ be -/// [attached](rocket::Rocket::attach()) to the running Rocket instance. Failure -/// to do so will result in an error. -/// -/// Templates are rendered with the `render` method. The method takes in the -/// name of a template and a context to render the template with. The context -/// can be any type that implements [`Serialize`] from [`serde`] and would -/// serialize to an `Object` value. -/// -/// In debug mode (without the `--release` flag passed to `cargo`), templates -/// will be automatically reloaded from disk if any changes have been made to -/// the templates directory since the previous request. In release builds, -/// template reloading is disabled to improve performance and cannot be enabled. +/// Responder that renders a dynamic template. /// /// # Usage /// @@ -134,7 +198,7 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates"; /// /// # Helpers, Filters, and Customization /// -/// You can use the [`Template::custom()`] method to construct a fairing with +/// You may use the [`Template::custom()`] method to construct a fairing with /// customized templating engines. Among other things, this method allows you to /// register template helpers and register templates from strings. #[derive(Debug)] diff --git a/contrib/lib/src/uuid.rs b/contrib/lib/src/uuid.rs @@ -1,3 +1,5 @@ +//! UUID parameter and form value parsing support. + pub extern crate uuid as uuid_crate; use std::fmt; @@ -9,8 +11,7 @@ use rocket::http::RawStr; pub use self::uuid_crate::parser::ParseError; -/// Implements [`FromParam`] and [`FromFormValue`] for accepting UUID values -/// from the [`uuid`] crate. +/// Implements [`FromParam`] and [`FromFormValue`] for accepting UUID values. /// /// # Usage ///