Have 'Template::show()' take an '&Rocket'.

This completes the effort started in #431, allowing for direct
customization of the underlying templating engines of 'Template'.

Resolves #64. Closes #234. Closes #431. Closes #500.

contrib/src/templates/mod.rs

@@ -14,9 +14,9 @@ use self::serde_json::{Value, to_value};
 use self::glob::glob;
 
 use std::borrow::Cow;
-use std::path::{Path, PathBuf};
+use std::path::PathBuf;
 
-use rocket::State;
+use rocket::{Rocket, State};
 use rocket::request::Request;
 use rocket::fairing::{Fairing, AdHoc};
 use rocket::response::{self, Content, Responder};
@@ -187,7 +187,6 @@ impl Template {
     pub fn custom<F>(f: F) -> impl Fairing where F: Fn(&mut Engines) + Send + Sync + 'static {
         AdHoc::on_attach(move |rocket| {
             let mut template_root = rocket.config().root_relative(DEFAULT_TEMPLATE_DIR);
-
             match rocket.config().get_str("template_dir") {
                 Ok(dir) => template_root = rocket.config().root_relative(dir),
                 Err(ConfigError::NotFound) => { /* ignore missing configs */ }
@@ -230,40 +229,55 @@ impl Template {
         Template { name: name.into(), value: to_value(context).ok() }
     }
 
-    /// Render the template named `name` located at the path `root` with the
+    /// Render the template named `name` with the context `context` into a
-    /// context `context` into a `String`. This method is _very slow_ and should
+    /// `String`. This method should **not** be used in any running Rocket
-    /// **not** be used in any running Rocket application. This method should
+    /// application. This method should only be used during testing to
-    /// only be used during testing to validate `Template` responses. For other
+    /// validate `Template` responses. For other uses, use
-    /// uses, use [`render`](#method.render) instead.
+    /// [`render`](#method.render) instead.
     ///
     /// The `context` can be of any type that implements `Serialize`. This is
-    /// typically a `HashMap` or a custom `struct`. The path `root` can be
+    /// typically a `HashMap` or a custom `struct`.
-    /// relative, in which case it is relative to the current working directory,
-    /// or absolute.
     ///
     /// Returns `Some` if the template could be rendered. Otherwise, returns
     /// `None`. If rendering fails, error output is printed to the console.
+    /// `None` is also returned if a `Template` fairing has not been attached.
     ///
     /// # Example
     ///
     /// ```rust
+    /// # extern crate rocket;
+    /// # extern crate rocket_contrib;
     /// use std::collections::HashMap;
+    ///
     /// use rocket_contrib::Template;
+    /// use rocket::local::Client;
+    ///
+    /// fn main() {
+    ///     let rocket = rocket::ignite().attach(Template::fairing());
+    ///     let client = Client::new(rocket).expect("valid rocket");
     ///
     ///     // Create a `context`. Here, just an empty `HashMap`.
     ///     let mut context = HashMap::new();
     ///
     ///     # context.insert("test", "test");
     ///     # #[allow(unused_variables)]
-    /// let template = Template::show("templates/", "index", context);
+    ///     let template = Template::show(client.rocket(), "index", context);
+    /// }
+    /// ```
     #[inline]
-    pub fn show<P, S, C>(root: P, name: S, context: C) -> Option<String>
+    pub fn show<S, C>(rocket: &Rocket, name: S, context: C) -> Option<String>
-        where P: AsRef<Path>, S: Into<Cow<'static, str>>, C: Serialize
+        where S: Into<Cow<'static, str>>, C: Serialize
     {
-        let root = root.as_ref().to_path_buf();
+        let ctxt = match rocket.state::<Context>() {
-        Context::initialize(root).and_then(|ctxt| {
+            Some(ctxt) => ctxt,
+            None => {
+                warn!("Uninitialized template context: missing fairing.");
+                info!("To use templates, you must attach `Template::fairing()`.");
+                info!("See the `Template` documentation for more information.");
+                return None;
+            }
+        };
         Template::render(name, context).finalize(&ctxt).ok().map(|v| v.0)
-        })
     }
 
     #[inline(always)]

contrib/tests/templates.rs

@@ -1,17 +1,29 @@
+extern crate rocket;
 extern crate rocket_contrib;
 
 use std::env;
 use std::path::PathBuf;
 
+use rocket::Rocket;
+use rocket::config::{Config, Environment};
+use rocket_contrib::Template;
+
 fn template_root() -> PathBuf {
     let cwd = env::current_dir().expect("current working directory");
     cwd.join("tests").join("templates")
 }
 
+fn rocket() -> Rocket {
+    let config = Config::build(Environment::Development)
+        .extra("template_dir", template_root().to_str().expect("template directory"))
+        .expect("valid configuration");
+
+    rocket::custom(config, true).attach(Template::fairing())
+}
+
 #[cfg(feature = "tera_templates")]
 mod tera_tests {
     use super::*;
-    use rocket_contrib::Template;
     use std::collections::HashMap;
 
     const UNESCAPED_EXPECTED: &'static str
@@ -21,16 +33,17 @@ mod tera_tests {
 
     #[test]
     fn test_tera_templates() {
+        let rocket = rocket();
         let mut map = HashMap::new();
         map.insert("title", "_test_");
         map.insert("content", "<script />");
 
         // Test with a txt file, which shouldn't escape.
-        let template = Template::show(template_root(), "tera/txt_test", &map);
+        let template = Template::show(&rocket, "tera/txt_test", &map);
         assert_eq!(template, Some(UNESCAPED_EXPECTED.into()));
 
         // Now with an HTML file, which should.
-        let template = Template::show(template_root(), "tera/html_test", &map);
+        let template = Template::show(&rocket, "tera/html_test", &map);
         assert_eq!(template, Some(ESCAPED_EXPECTED.into()));
     }
 }
@@ -38,7 +51,6 @@ mod tera_tests {
 #[cfg(feature = "handlebars_templates")]
 mod handlebars_tests {
     use super::*;
-    use rocket_contrib::Template;
     use std::collections::HashMap;
 
     const EXPECTED: &'static str
@@ -46,12 +58,13 @@ mod handlebars_tests {
 
     #[test]
     fn test_handlebars_templates() {
+        let rocket = rocket();
         let mut map = HashMap::new();
         map.insert("title", "_test_");
         map.insert("content", "<script /> hi");
 
         // Test with a txt file, which shouldn't escape.
-        let template = Template::show(template_root(), "hbs/test", &map);
+        let template = Template::show(&rocket, "hbs/test", &map);
         assert_eq!(template, Some(EXPECTED.into()));
     }
 }

examples/cookies/src/tests.rs

@@ -5,8 +5,6 @@ use rocket::local::Client;
 use rocket::http::*;
 use rocket_contrib::Template;
 
-const TEMPLATE_ROOT: &'static str = "templates/";
-
 #[test]
 fn test_submit() {
     let client = Client::new(rocket()).unwrap();
@@ -37,13 +35,15 @@ fn test_body(optional_cookie: Option<Cookie<'static>>, expected_body: String) {
 
 #[test]
 fn test_index() {
+    let client = Client::new(rocket()).unwrap();
+
     // Render the template with an empty context.
     let mut context: HashMap<&str, &str> = HashMap::new();
-    let template = Template::show(TEMPLATE_ROOT, "index", &context).unwrap();
+    let template = Template::show(client.rocket(), "index", &context).unwrap();
     test_body(None, template);
 
     // Render the template with a context that contains the message.
     context.insert("message", "Hello from Rocket!");
-    let template = Template::show(TEMPLATE_ROOT, "index", &context).unwrap();
+    let template = Template::show(client.rocket(), "index", &context).unwrap();
     test_body(Some(Cookie::new("message", "Hello from Rocket!")), template);
 }

examples/handlebars_templates/src/main.rs

@@ -40,23 +40,18 @@ fn not_found(req: &Request) -> Template {
     Template::render("error/404", &map)
 }
 
+fn echo_helper(h: &Helper, _: &Handlebars, rc: &mut RenderContext) -> Result<(), RenderError> {
+    if let Some(p0) = h.param(0) {
+        rc.writer.write(p0.value().render().into_bytes().as_ref())?;
+    };
+    Ok(())
+}
+
 fn rocket() -> rocket::Rocket {
     rocket::ignite()
         .mount("/", routes![index, get])
         .attach(Template::custom(|engines| {
-            engines.handlebars.register_helper(
+            engines.handlebars.register_helper("echo", Box::new(echo_helper));
-                "echo", Box::new(|h: &Helper,
-                                  _: &Handlebars,
-                                  rc: &mut RenderContext| -> Result<(), RenderError> {
-                                      if let Some(p0) = h.param(0) {
-                                          rc.writer.write(p0.value()
-                                                          .render()
-                                                          .into_bytes()
-                                                          .as_ref())?;
-                                      }
-                                      Ok(())
-                                  }));
-
         }))
         .catch(catchers![not_found])
 }

examples/handlebars_templates/src/tests.rs

@@ -4,12 +4,10 @@ use rocket::http::Method::*;
 use rocket::http::Status;
 use rocket_contrib::Template;
 
-const TEMPLATE_ROOT: &'static str = "templates/";
-
 macro_rules! dispatch {
     ($method:expr, $path:expr, $test_fn:expr) => ({
         let client = Client::new(rocket()).unwrap();
-        $test_fn(client.req($method, $path).dispatch());
+        $test_fn(&client, client.req($method, $path).dispatch());
     })
 }
 
@@ -17,7 +15,7 @@ macro_rules! dispatch {
 fn test_root() {
     // Check that the redirect works.
     for method in &[Get, Head] {
-        dispatch!(*method, "/", |mut response: LocalResponse| {
+        dispatch!(*method, "/", |_: &Client, mut response: LocalResponse| {
             assert_eq!(response.status(), Status::SeeOther);
             assert!(response.body().is_none());
 
@@ -28,10 +26,10 @@ fn test_root() {
 
     // Check that other request methods are not accepted (and instead caught).
     for method in &[Post, Put, Delete, Options, Trace, Connect, Patch] {
-        dispatch!(*method, "/", |mut response: LocalResponse| {
+        dispatch!(*method, "/", |client: &Client, mut response: LocalResponse| {
             let mut map = ::std::collections::HashMap::new();
             map.insert("path", "/");
-            let expected = Template::show(TEMPLATE_ROOT, "error/404", &map).unwrap();
+            let expected = Template::show(client.rocket(), "error/404", &map).unwrap();
 
             assert_eq!(response.status(), Status::NotFound);
             assert_eq!(response.body_string(), Some(expected));
@@ -42,13 +40,13 @@ fn test_root() {
 #[test]
 fn test_name() {
     // Check that the /hello/<name> route works.
-    dispatch!(Get, "/hello/Jack", |mut response: LocalResponse| {
+    dispatch!(Get, "/hello/Jack", |client: &Client, mut response: LocalResponse| {
         let context = super::TemplateContext {
             name: "Jack".into(),
             items: vec!["One".into(), "Two".into(), "Three".into()]
         };
 
-        let expected = Template::show(TEMPLATE_ROOT, "index", &context).unwrap();
+        let expected = Template::show(client.rocket(), "index", &context).unwrap();
         assert_eq!(response.status(), Status::Ok);
         assert_eq!(response.body_string(), Some(expected));
     });
@@ -57,11 +55,11 @@ fn test_name() {
 #[test]
 fn test_404() {
     // Check that the error catcher works.
-    dispatch!(Get, "/hello/", |mut response: LocalResponse| {
+    dispatch!(Get, "/hello/", |client: &Client, mut response: LocalResponse| {
         let mut map = ::std::collections::HashMap::new();
         map.insert("path", "/hello/");
 
-        let expected = Template::show(TEMPLATE_ROOT, "error/404", &map).unwrap();
+        let expected = Template::show(client.rocket(), "error/404", &map).unwrap();
         assert_eq!(response.status(), Status::NotFound);
         assert_eq!(response.body_string(), Some(expected));
     });

examples/tera_templates/src/tests.rs

@@ -4,12 +4,10 @@ use rocket::http::Method::*;
 use rocket::http::Status;
 use rocket_contrib::Template;
 
-const TEMPLATE_ROOT: &'static str = "templates/";
-
 macro_rules! dispatch {
     ($method:expr, $path:expr, $test_fn:expr) => ({
         let client = Client::new(rocket()).unwrap();
-        $test_fn(client.req($method, $path).dispatch());
+        $test_fn(&client, client.req($method, $path).dispatch());
     })
 }
 
@@ -17,7 +15,7 @@ macro_rules! dispatch {
 fn test_root() {
     // Check that the redirect works.
     for method in &[Get, Head] {
-        dispatch!(*method, "/", |mut response: LocalResponse| {
+        dispatch!(*method, "/", |_: &Client, mut response: LocalResponse| {
             assert_eq!(response.status(), Status::SeeOther);
             assert!(response.body().is_none());
 
@@ -28,10 +26,10 @@ fn test_root() {
 
     // Check that other request methods are not accepted (and instead caught).
     for method in &[Post, Put, Delete, Options, Trace, Connect, Patch] {
-        dispatch!(*method, "/", |mut response: LocalResponse| {
+        dispatch!(*method, "/", |client: &Client, mut response: LocalResponse| {
             let mut map = ::std::collections::HashMap::new();
             map.insert("path", "/");
-            let expected = Template::show(TEMPLATE_ROOT, "error/404", &map).unwrap();
+            let expected = Template::show(client.rocket(), "error/404", &map).unwrap();
 
             assert_eq!(response.status(), Status::NotFound);
             assert_eq!(response.body_string(), Some(expected));
@@ -42,13 +40,13 @@ fn test_root() {
 #[test]
 fn test_name() {
     // Check that the /hello/<name> route works.
-    dispatch!(Get, "/hello/Jack", |mut response: LocalResponse| {
+    dispatch!(Get, "/hello/Jack", |client: &Client, mut response: LocalResponse| {
         let context = super::TemplateContext {
             name: "Jack".into(),
             items: vec!["One", "Two", "Three"]
         };
 
-        let expected = Template::show(TEMPLATE_ROOT, "index", &context).unwrap();
+        let expected = Template::show(client.rocket(), "index", &context).unwrap();
         assert_eq!(response.status(), Status::Ok);
         assert_eq!(response.body_string(), Some(expected));
     });
@@ -57,11 +55,11 @@ fn test_name() {
 #[test]
 fn test_404() {
     // Check that the error catcher works.
-    dispatch!(Get, "/hello/", |mut response: LocalResponse| {
+    dispatch!(Get, "/hello/", |client: &Client, mut response: LocalResponse| {
         let mut map = ::std::collections::HashMap::new();
         map.insert("path", "/hello/");
 
-        let expected = Template::show(TEMPLATE_ROOT, "error/404", &map).unwrap();
+        let expected = Template::show(client.rocket(), "error/404", &map).unwrap();
         assert_eq!(response.status(), Status::NotFound);
         assert_eq!(response.body_string(), Some(expected));
     });