mirror of https://github.com/rwf2/Rocket.git
Document contrib modules.
This commit is contained in:
parent
085a143075
commit
8741e678f8
|
@ -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;
|
||||
|
||||
|
|
|
@ -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;
|
||||
|
||||
|
|
|
@ -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)]
|
||||
|
|
|
@ -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
|
||||
///
|
||||
|
|
Loading…
Reference in New Issue