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

Improve text on site index page.

This commit is contained in:
Sergio Benitez 2021-06-26 17:10:57 -07:00
parent 00e56c9822
commit ca9e3da5b6
2 changed files with 62 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

35
site/index.toml
View File

@ -61,8 +61,7 @@ code = '''
''' '''
text = ''' text = '''
This is a **complete Rocket application**. It does exactly what you would This is a **complete Rocket application**. It does exactly what you would
expect. If you were to visit **http://localhost:8000/hello/John/58**, you’d expect. If you were to visit **/hello/John/58**, you’d see:
see:
<span class="callout">Hello, 58 year old named John!</span> <span class="callout">Hello, 58 year old named John!</span>
@ -76,27 +75,26 @@ title = "Forms? Check!"
code = ''' code = '''
#[derive(FromForm)] #[derive(FromForm)]
struct Task<'r> { struct Task<'r> {
#[field(validate = len(1..))]
description: &'r str, description: &'r str,
completed: bool completed: bool
} }
#[post("/", data = "<task>")] #[post("/", data = "<task>")]
fn new(task: Form<Task<'_>>) -> Flash<Redirect> { fn new(task: Form<Task<'_>>) -> Flash<Redirect> {
if task.description.is_empty() {
Flash::error(Redirect::to(uri!(home)), "Cannot be empty.")
} else {
Flash::success(Redirect::to(uri!(home)), "Task added.") Flash::success(Redirect::to(uri!(home)), "Task added.")
} }
}
''' '''
text = ''' text = '''
Handling forms **is simple and easy**. Simply derive `FromForm` for your Form handling **is simple, declarative, and complete**: derive
structure and let Rocket know which parameter to use. Rocket **parses and [`FromForm`](@api/rocket/derive.FromForm.html) for your structure and set the
validates** the form request, creates the structure, and calls your function. `data` parameter to a `Form` type. Rocket automatically **parses and
validates** the form data into your structure and calls your function.
Bad form request? Rocket doesn’t call your function! What if you want to know Bad form request? Rocket doesn’t call your function! Need to know what went
if the form was bad? Simple! Change the type of `task` to `Option` or wrong? Use a `data` parameter of `Result`! Want to rerender the form with user
`Result`! input and errors? Use [`Context`](guide/requests/#context)! File uploads? A
breeze with [`TempFile`](@api/rocket/fs/enum.TempFile.html).
''' '''
[[sections]] [[sections]]
@ -108,7 +106,7 @@ code = '''
} }
#[put("/<id>", data = "<msg>")] #[put("/<id>", data = "<msg>")]
fn update(db: &Db, id: Id, msg: Json<Message<'_>>) -> JsonValue { fn update(db: &Db, id: Id, msg: Json<Message<'_>>) -> Value {
if db.contains_key(&id) { if db.contains_key(&id) {
db.insert(id, msg.contents); db.insert(id, msg.contents);
json!({ "status": "ok" }) json!({ "status": "ok" })
@ -121,11 +119,12 @@ text = '''
Rocket has first-class support for JSON, right out of the box. Simply derive Rocket has first-class support for JSON, right out of the box. Simply derive
`Deserialize` or `Serialize` to receive or return JSON, respectively. `Deserialize` or `Serialize` to receive or return JSON, respectively.
Like other important features, JSON works through Rocket’s `FromData` trait, Look familiar? Forms, JSON, and all kinds of body data types work through
Rocket’s approach to deriving types from body data. It works like this: Rocket’s [`FromData`](@api/rocket/data/trait.FromData.html) trait, Rocket’s
specify a `data` route parameter of any type that implements `FromData`. A approach to deriving types from body data. A `data` route parameter can be
value of that type will then be created automatically from the incoming _any_ type that implements `FromData`. A value of that type will be
request body. Best of all, you can implement `FromData` for your types! deserialized automatically from the incoming request body. You can even
implement `FromData` for your own types!
''' '''
############################################################################### ###############################################################################

89
site/overview.toml
View File

@ -21,60 +21,61 @@ fn index() -> &'static str {
} }
``` ```
This route, named `index`, will match against incoming HTTP `GET` requests to This `index` route matches any incoming HTTP `GET` request to `/`, the index.
the `/` path, the index. The request handler returns a string. Rocket will use The handler returns a `String`. Rocket automatically converts the string into a
the string as the body of a fully formed HTTP response. well-formed HTTP response that includes the appropriate `Content-Type` and body
encoding metadata.
''' '''
[[panels]] [[panels]]
name = "Dynamic Params" name = "Dynamic Params"
content = ''' content = '''
Rocket allows you to interpret segments of a request path dynamically. To Rocket automatically parses dynamic data in path segments into any desired type.
illustrate, let's use the following route: To illustrate, let's use the following route:
```rust ```rust
#[get("/hello/<name>/<age>")] #[get("/hello/<name>/<age>")]
fn hello(name: String, age: u8) -> String { fn hello(name: &str, age: u8) -> String {
format!("Hello, {} year old named {}!", age, name) format!("Hello, {} year old named {}!", age, name)
} }
``` ```
The `hello` route above matches two dynamic path segments declared inside This `hello` route has two dynamic parameters, identified with angle brackets,
brackets in the path: `<name>` and `<age>`. _Dynamic_ means that the segment can declared in the route URI: `<name>` and `<age>`. Rocket maps each parameter to
be _any_ value the end-user desires. an identically named function argument: `name: &str` and `age: u8`. The dynamic
data in the incoming request is parsed automatically into a value of the
argument's type. The route is called only when parsing succeeds.
Each dynamic parameter (`name` and `age`) must have a type, here `&str` and Parsing is directed by the
`u8`, respectively. Rocket will attempt to parse the string in the parameter's [`FromParam`](@api/rocket/request/trait.FromParam.html) trait. Rocket implements
position in the path into that type. The route will only be called if parsing `FromParam` for many standard types, including both `&str` and `u8`. You can
succeeds. To parse the string, Rocket uses the implement it for your own types, too!
[FromParam](@api/rocket/request/trait.FromParam.html) trait,
which you can implement for your own types!
''' '''
[[panels]] [[panels]]
name = "Handling Data" name = "Handling Data"
content = ''' content = '''
Request body data is handled in a special way in Rocket: via the Rocket can automatically parse body data, too!
[FromData](@api/rocket/data/trait.FromData.html) trait. Any type that implements
`FromData` can be derived from incoming body data. To tell Rocket that you're
expecting request body data, the `data` route argument is used with the name of
the parameter in the request handler:
```rust ```rust
#[post("/login", data = "<user_form>")] #[post("/login", data = "<login>")]
fn login(user_form: Form<UserLogin>) -> String { fn login(login: Form<UserLogin>) -> String {
format!("Hello, {}!", user_form.name) format!("Hello, {}!", login.name)
} }
``` ```
The `login` route above says that it expects `data` of type `Form<UserLogin>` in The dynamic parameter declared in the `data` route attribute parameter again
the `user_form` parameter. The [Form](@api/rocket/form/struct.Form.html) type maps to a function argument. Here, `login` maps to `login: Form<UserLogin>`.
is a built-in Rocket type that knows how to parse web forms into structures. Parsing is again trait-directed, this time by the
Rocket will automatically attempt to parse the request body into the `Form` and [`FromData`](@api/rocket/data/trait.FromData.html) trait.
call the `login` handler if parsing succeeds. Other built-in `FromData` types
include [`Data`](@api/rocket/struct.Data.html), The [`Form`](@api/rocket/form/struct.Form.html) type is Rocket's [robust form
data parser](@guide/requests/#forms). It automatically parses the request body into the internal type,
here `UserLogin`. Other built-in `FromData` types include
[`Data`](@api/rocket/struct.Data.html),
[`Json`](@api/rocket/serde/json/struct.Json.html), and [`Json`](@api/rocket/serde/json/struct.Json.html), and
[`Flash`](@api/rocket/response/struct.Flash.html). [`MsgPack`](@api/rocket/serde/msgpack/struct.MsgPack.html). As always, you can
implement `FromData` for your own types, too!
''' '''
[[panels]] [[panels]]
@ -107,7 +108,7 @@ invariants through types.
name = "Responders" name = "Responders"
content = ''' content = '''
The return type of a request handler can be any type that implements The return type of a request handler can be any type that implements
[Responder](@api/rocket/response/trait.Responder.html): [`Responder`](@api/rocket/response/trait.Responder.html):
```rust ```rust
#[get("/")] #[get("/")]
@ -117,9 +118,9 @@ fn route() -> T { ... }
Above, T must implement `Responder`. Rocket implements `Responder` for many of Above, T must implement `Responder`. Rocket implements `Responder` for many of
the standard library types including `&str`, `String`, `File`, `Option`, and the standard library types including `&str`, `String`, `File`, `Option`, and
`Result`. Rocket also implements custom responders such as `Result`. Rocket also implements custom responders such as
[Redirect](@api/rocket/response/struct.Redirect.html), [`Redirect`](@api/rocket/response/struct.Redirect.html),
[Flash](@api/rocket/response/struct.Flash.html), and [`Flash`](@api/rocket/response/struct.Flash.html), and
[Template](@api/rocket_dyn_templates/struct.Template.html). [`Template`](@api/rocket_dyn_templates/struct.Template.html).
The task of a `Responder` is to generate a The task of a `Responder` is to generate a
[`Response`](@api/rocket/response/struct.Response.html), if possible. [`Response`](@api/rocket/response/struct.Response.html), if possible.
@ -135,10 +136,9 @@ fn not_found() -> T { ... }
[[panels]] [[panels]]
name = "Launching" name = "Launching"
content = ''' content = '''
Launching a Rocket application is the funnest part! For Rocket to begin Finally, we get to launch our application! Rocket begins dispatching requests to
dispatching requests to routes, routes need to be _mounted_. After mounting, the routes after they've been _mounted_ and the application has been _launched_.
application needs to be _launched_. These two steps, usually done in a `rocket` These two steps, usually wrtten in a `rocket` function, look like:
function, look like:
```rust ```rust
#[launch] #[launch]
@ -147,15 +147,14 @@ fn rocket() -> _ {
} }
``` ```
The `mount` call takes a base path and a set of routes via the `routes!` macro. The `mount` call takes a _base_ and a set of routes via the `routes!` macro. The
The base path (`/base` above) is prepended to the path of every route in the base path (`/base` above) is prepended to the path of every route in the list,
list. This namespaces the routes, allowing for composition. The `#[launch]` effectively namespacing the routes. `#[launch]` creates a `main` function that
attribute creates a `main` function that starts the server. In development, starts the server. In development, Rocket prints useful information to the
Rocket prints useful information to the console to let you know everything is console to let you know everything is okay.
okay.
```sh ```sh
🚀 Rocket has launched from http://localhost:8000 🚀 Rocket has launched from http://127.0.0.1:8000
``` ```
''' '''