1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272
// This module is only a chapter of the documentation. #![allow(non_snake_case)] //! Apart from handling templates for dynamic content, ructe also //! helps with constants for static content. //! //! Most sites that need HTML templates also needs some static resources. //! Maybe one or several CSS files, some javascript, and / or pictures. //! A good way to reduce network round-trips is to use a far expires //! header to tell the browser it can cache those files and don't need //! to check if they have changed. //! But what if the files do change? //! Then pretty much the only way to make sure the browser gets the //! updated file is to change the URL to the file as well. //! //! Ructe can create content-dependent file names for static files. //! If you have an `image.png`, ructe may call it `image-SomeHash.png` //! where `SomeHash` is 8 url-safe base64 characters encoding 48 bits //! of a md5 sum of the file. //! //! Actually serving the file is a job for a web framework like //! [iron](https://github.com/iron/iron), //! [nickel](https://github.com/nickel-org/nickel.rs) or //! [rocket](https://rocket.rs/), but ructe helps by packing the file //! contents into a constant struct that you can access from rust //! code. pub mod a_Overview { //! This section describes how to set up your project to serve //! static content using ructe. //! //! To do this, the first step is to add a line in `build.rs` telling //! ructe to find and transpile your static files: //! //! ```no_run //! # use ructe::{compile_static_files, compile_templates}; //! # use std::env; //! # use std::path::PathBuf; //! let out_dir = PathBuf::from(env::var("OUT_DIR").unwrap()); //! let in_dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").unwrap()); //! compile_static_files(&in_dir.join("static"), &out_dir).unwrap(); //! compile_templates(&in_dir.join("templates"), &out_dir).unwrap(); //! ``` //! //! Then you need to link to the encoded file. //! For an image, you probably want to link it from an `<img>` tag in //! a template. That can be done like this: //! //! ```html //! @use templates::statics::image_png; //! @() //! <img alt="Something" src="/static/@image_png.name"> //! ``` //! //! So, what has happened here? //! First, assuming the `static` directory in your //! `$CARGO_MANIFEST_DIR` contained a file name `image.png`, your //! `templates::statics` module will contain a //! `pub static image_png: StaticFile` which can be imported and used //! in both templates and rust code. //! A `StaticFile` has a field named `name` which is a `&'static str` //! containing the name with the generated hash, `image-SomeHash.png`. //! //! The next step is that a browser actually sends a request for //! `/static/image-SomeHash.png` and your server needs to deliver it. //! Here, things depend on your web framework, so we start with some //! pseudo code, and then goes on to working examples for iron and //! nickel. //! //! ```ignore //! /// A hypothetical web framework calls this each /static/ request, //! /// with the name component of the URL as the name argument. //! fn serve_static(name: &str) -> HttpResult { //! if let Some(data) = StaticFile::get(name) { //! HttpResult::Ok(data.content) //! } else { //! HttpResult::NotFound //! } //! } //! ``` //! //! The `StaticFile::get` function returns the `&'static StaticFile` //! for a given file name if the file exists. //! This is a reference to the same struct that we used by the name //! `image_png` in the template. //! Besides the `name` field (which will be equal to the argument, or //! `get` would not have returned this `StaticFile`), there is a //! `content: &'static [u8]` field which contains the actual file //! data. } pub mod b_Content_types { //! How to get the content type of static files. //! //! Ructe has support for making the content-type of each static //! file availiable using the //! [mime](https://crates.io/crates/mime) crate. //! Since mime version 0.3.0 was a breaking change of how the //! `mime::Mime` type was implemented, and both Nickel and Iron //! currently require the old version (0.2.x), ructe provides //! support for both mime 0.2.x and mime 0.3.x with separate //! feature flags. //! //! # Mime 0.2.x //! //! To use the mime 0.2.x support, enable the `mime02` feature and //! add mime 0.2.x as a dependency: //! //! ```toml //! [build-dependencies] //! ructe = { version = "^0.3.2", features = ["mime02"] } //! //! [dependencies] //! mime = "~0.2" //! ``` //! //! A `Mime` as implemented in `mime` version 0.2.x cannot be //! created statically, so instead a `StaticFile` provides //! `pub fn mime(&self) -> Mime`. //! //! ``` //! # // Test and doc even without the feature, so mock functionality. //! # pub mod templates { pub mod statics { //! # pub struct FakeFile; //! # impl FakeFile { pub fn mime(&self) -> &'static str { "image/png" } } //! # pub static image_png: FakeFile = FakeFile; //! # }} //! use templates::statics::image_png; //! //! # fn main() { //! assert_eq!(format!("Type is {}", image_png.mime()), //! "Type is image/png"); //! # } //! ``` //! //! # Mime 0.3.x //! //! To use the mime 0.3.x support, enable the `mime3` feature and //! add mime 0.3.x as a dependency: //! //! ```toml //! [build-dependencies] //! ructe = { version = "^0.3.2", features = ["mime03"] } //! //! [dependencies] //! mime = "~0.3" //! ``` //! //! From version 0.3, the `mime` crates supports creating const //! static `Mime` objects, so with this feature, a `StaticFile` //! simply has a `pub mime: &'static Mime` field. //! //! ``` //! # // Test and doc even without the feature, so mock functionality. //! # pub mod templates { pub mod statics { //! # pub struct FakeFile { pub mime: &'static str } //! # pub static image_png: FakeFile = FakeFile { mime: "image/png", }; //! # }} //! use templates::statics::image_png; //! //! # fn main() { //! assert_eq!(format!("Type is {}", image_png.mime), //! "Type is image/png"); //! # } //! ``` } pub mod c_Iron { //! How to serve static files with the Iron web framework. //! //! Somewhere (maybe in `main`), you probably create a router. //! To add a static handler could look something like this: //! //! ```ignore //! // Somewhere (maybe in main) you create a router //! let mut router = Router::new(); //! // Among the routes, you add this: //! router.get("/static/:name", static_file, "static_file"); //! // Go on to start an Iron server with the router //! ``` //! //! Then the actual handler needs to be implemented. //! Here's one implementation. //! //! ```ignore //! fn static_file(req: &mut Request) -> IronResult<Response> { //! // Extract the requested file name from the router //! let router = req.extensions.get::<Router>().expect("router"); //! let name = router.find("name").expect("name"); //! // If the static files exists, serve it //! if let Some(data) = statics::StaticFile::get(name) { //! Ok(Response::with((status::Ok, data.mime(), data.content))) //! } else { //! debug!("Static file {} not found", name); //! Ok(Response::with(( //! status::NotFound, //! mime!(Text / Plain), //! "not found", //! ))) //! } //! } //! ``` //! //! This implementation uses the `mime02` feature of ructe. //! Relevant parts of `Cargo.toml` might look like this: //! //! ```toml //! [build-dependencies] //! ructe = { version = "^0.3.2", features = ["sass", "mime02"] } //! //! [dependencies] //! iron = "^0.5.1" //! router = "^0.5.1" //! mime = "0.2.6" //! ``` //! //! There is a full example as `examples/iron` in //! [the ructe repository](https://github.com/kaj/ructe/). } pub mod d_Nickel { //! How to serve static files with the Nickel framework. //! //! Somewhere (maybe in `main`), you probably create a Nickel server. //! To add a static handler could look something like this: //! //! ```ignore //! // Somewhere (maybe in main) you create a Nickel server //! let mut server = Nickel::new(); //! // Among the routes, you add this: //! server.get("/static/:name.:ext", static_file); //! // Then you add more routes and start the server as usual //! ``` //! //! Then the actual handler needs to be implemented. //! Here's one implementation. //! //! ```ignore //! fn static_file<'mw>(req: &mut Request, //! mut res: Response<'mw>) //! -> MiddlewareResult<'mw> { //! //! if let (Some(name), Some(ext)) = //! (req.param("name"), req.param("ext")) //! { //! use templates::statics::StaticFile; //! if let Some(s) = StaticFile::get(&format!("{}.{}", name, ext)) { //! res.set(ContentType(s.mime())); //! res.set(Expires(HttpDate(now() + Duration::days(300)))); //! return res.send(s.content); //! } //! } //! res.error(StatusCode::NotFound, "Not found") //! } //! ``` //! //! This implementation uses the `mime02` feature of ructe. //! Relevant parts of `Cargo.toml` might look like this: //! //! ```toml //! [build-dependencies] //! ructe = { version = "^0.3.2", features = ["mime02"] } //! //! [dependencies] //! nickel = "~0.10" //! hyper = "~0.10" //! time = "*" //! mime = "~0.2" //! ``` //! //! There is a full example as `examples/nickel` in //! [the ructe repository](https://github.com/kaj/ructe/). }