rwf2
/
Rocket
mirror of https://github.com/rwf2/Rocket.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Document contrib modules.

This commit is contained in:
Sergio Benitez 2018-10-12 18:52:38 -07:00
parent 085a143075
commit 8741e678f8
4 changed files with 124 additions and 53 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
contrib/lib/src/json.rs
View File

@ -1,3 +1,6 @@
//! Automatic JSON (de)serialization support.
//!
//! See the [`Json`](json::Json) type for further details.
extern crate serde; extern crate serde;
extern crate serde_json; extern crate serde_json;

3
contrib/lib/src/msgpack.rs
View File

@ -1,3 +1,6 @@
//! Automatic MessagePack (de)serialization support.
//!
//! See the [`MsgPack`](msgpack::MessagePack) type for further details.
extern crate serde; extern crate serde;
extern crate rmp_serde; extern crate rmp_serde;

166
contrib/lib/src/templates/mod.rs
View File

@ -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;
extern crate serde_json; extern crate serde_json;
extern crate glob; extern crate glob;
@ -35,56 +148,7 @@ use rocket::http::{ContentType, Status};
const DEFAULT_TEMPLATE_DIR: &str = "templates"; const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// The Template type implements generic support for template rendering in /// Responder that renders a dynamic template.
/// 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.
/// ///
/// # Usage /// # Usage
/// ///
@ -134,7 +198,7 @@ const DEFAULT_TEMPLATE_DIR: &str = "templates";
/// ///
/// # Helpers, Filters, and Customization /// # 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 /// customized templating engines. Among other things, this method allows you to
/// register template helpers and register templates from strings. /// register template helpers and register templates from strings.
#[derive(Debug)] #[derive(Debug)]

5
contrib/lib/src/uuid.rs
View File

@ -1,3 +1,5 @@
//! UUID parameter and form value parsing support.
pub extern crate uuid as uuid_crate; pub extern crate uuid as uuid_crate;
use std::fmt; use std::fmt;
@ -9,8 +11,7 @@ use rocket::http::RawStr;
pub use self::uuid_crate::parser::ParseError; pub use self::uuid_crate::parser::ParseError;
/// Implements [`FromParam`] and [`FromFormValue`] for accepting UUID values /// Implements [`FromParam`] and [`FromFormValue`] for accepting UUID values.
/// from the [`uuid`] crate.
/// ///
/// # Usage /// # Usage
/// ///