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

37
site/index.toml
View File

@ -61,8 +61,7 @@ code = '''
'''
text = '''
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
see:
expect. If you were to visit **/hello/John/58**, you’d see:
<span class="callout">Hello, 58 year old named John!</span>
@ -76,27 +75,26 @@ title = "Forms? Check!"
code = '''
#[derive(FromForm)]
struct Task<'r> {
#[field(validate = len(1..))]
description: &'r str,
completed: bool
}
#[post("/", data = "<task>")]
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 = '''
Handling forms **is simple and easy**. Simply derive `FromForm` for your
structure and let Rocket know which parameter to use. Rocket **parses and
validates** the form request, creates the structure, and calls your function.
Form handling **is simple, declarative, and complete**: derive
[`FromForm`](@api/rocket/derive.FromForm.html) for your structure and set the
`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
if the form was bad? Simple! Change the type of `task` to `Option` or
`Result`!
Bad form request? Rocket doesn’t call your function! Need to know what went
wrong? Use a `data` parameter of `Result`! Want to rerender the form with user
input and errors? Use [`Context`](guide/requests/#context)! File uploads? A
breeze with [`TempFile`](@api/rocket/fs/enum.TempFile.html).
'''
[[sections]]
@ -108,7 +106,7 @@ code = '''
}
#[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) {
db.insert(id, msg.contents);
json!({ "status": "ok" })
@ -121,11 +119,12 @@ text = '''
Rocket has first-class support for JSON, right out of the box. Simply derive
`Deserialize` or `Serialize` to receive or return JSON, respectively.
Like other important features, JSON works through Rocket’s `FromData` trait,
Rocket’s approach to deriving types from body data. It works like this:
specify a `data` route parameter of any type that implements `FromData`. A
value of that type will then be created automatically from the incoming
request body. Best of all, you can implement `FromData` for your types!
Look familiar? Forms, JSON, and all kinds of body data types work through
Rocket’s [`FromData`](@api/rocket/data/trait.FromData.html) trait, Rocket’s
approach to deriving types from body data. A `data` route parameter can be
_any_ type that implements `FromData`. A value of that type will be
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
the `/` path, the index. The request handler returns a string. Rocket will use
the string as the body of a fully formed HTTP response.
This `index` route matches any incoming HTTP `GET` request to `/`, the index.
The handler returns a `String`. Rocket automatically converts the string into a
well-formed HTTP response that includes the appropriate `Content-Type` and body
encoding metadata.
'''
[[panels]]
name = "Dynamic Params"
content = '''
Rocket allows you to interpret segments of a request path dynamically. To
illustrate, let's use the following route:
Rocket automatically parses dynamic data in path segments into any desired type.
To illustrate, let's use the following route:
```rust
#[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)
}
```
The `hello` route above matches two dynamic path segments declared inside
brackets in the path: `<name>` and `<age>`. _Dynamic_ means that the segment can
be _any_ value the end-user desires.
This `hello` route has two dynamic parameters, identified with angle brackets,
declared in the route URI: `<name>` and `<age>`. Rocket maps each parameter to
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
`u8`, respectively. Rocket will attempt to parse the string in the parameter's
position in the path into that type. The route will only be called if parsing
succeeds. To parse the string, Rocket uses the
[FromParam](@api/rocket/request/trait.FromParam.html) trait,
which you can implement for your own types!
Parsing is directed by the
[`FromParam`](@api/rocket/request/trait.FromParam.html) trait. Rocket implements
`FromParam` for many standard types, including both `&str` and `u8`. You can
implement it for your own types, too!
'''
[[panels]]
name = "Handling Data"
content = '''
Request body data is handled in a special way in Rocket: via the
[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:
Rocket can automatically parse body data, too!
```rust
#[post("/login", data = "<user_form>")]
fn login(user_form: Form<UserLogin>) -> String {
format!("Hello, {}!", user_form.name)
#[post("/login", data = "<login>")]
fn login(login: Form<UserLogin>) -> String {
format!("Hello, {}!", login.name)
}
```
The `login` route above says that it expects `data` of type `Form<UserLogin>` in
the `user_form` parameter. The [Form](@api/rocket/form/struct.Form.html) type
is a built-in Rocket type that knows how to parse web forms into structures.
Rocket will automatically attempt to parse the request body into the `Form` and
call the `login` handler if parsing succeeds. Other built-in `FromData` types
include [`Data`](@api/rocket/struct.Data.html),
The dynamic parameter declared in the `data` route attribute parameter again
maps to a function argument. Here, `login` maps to `login: Form<UserLogin>`.
Parsing is again trait-directed, this time by the
[`FromData`](@api/rocket/data/trait.FromData.html) trait.
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
[`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]]
@ -107,7 +108,7 @@ invariants through types.
name = "Responders"
content = '''
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
#[get("/")]
@ -117,9 +118,9 @@ fn route() -> T { ... }
Above, T must implement `Responder`. Rocket implements `Responder` for many of
the standard library types including `&str`, `String`, `File`, `Option`, and
`Result`. Rocket also implements custom responders such as
[Redirect](@api/rocket/response/struct.Redirect.html),
[Flash](@api/rocket/response/struct.Flash.html), and
[Template](@api/rocket_dyn_templates/struct.Template.html).
[`Redirect`](@api/rocket/response/struct.Redirect.html),
[`Flash`](@api/rocket/response/struct.Flash.html), and
[`Template`](@api/rocket_dyn_templates/struct.Template.html).
The task of a `Responder` is to generate a
[`Response`](@api/rocket/response/struct.Response.html), if possible.
@ -135,10 +136,9 @@ fn not_found() -> T { ... }
[[panels]]
name = "Launching"
content = '''
Launching a Rocket application is the funnest part! For Rocket to begin
dispatching requests to routes, routes need to be _mounted_. After mounting, the
application needs to be _launched_. These two steps, usually done in a `rocket`
function, look like:
Finally, we get to launch our application! Rocket begins dispatching requests to
routes after they've been _mounted_ and the application has been _launched_.
These two steps, usually wrtten in a `rocket` function, look like:
```rust
#[launch]
@ -147,15 +147,14 @@ fn rocket() -> _ {
}
```
The `mount` call takes a base path and a set of routes via the `routes!` macro.
The base path (`/base` above) is prepended to the path of every route in the
list. This namespaces the routes, allowing for composition. The `#[launch]`
attribute creates a `main` function that starts the server. In development,
Rocket prints useful information to the console to let you know everything is
okay.
The `mount` call takes a _base_ and a set of routes via the `routes!` macro. The
base path (`/base` above) is prepended to the path of every route in the list,
effectively namespacing the routes. `#[launch]` creates a `main` function that
starts the server. In development, Rocket prints useful information to the
console to let you know everything is okay.
```sh
🚀 Rocket has launched from http://localhost:8000
🚀 Rocket has launched from http://127.0.0.1:8000
```
'''