1
0
mirror of https://github.com/vlang/v.git synced 2023-08-10 21:13:21 +03:00
v/vlib/vweb/README.md

142 lines
3.7 KiB
Markdown
Raw Normal View History

2021-05-15 05:53:25 +03:00
# vweb - the V Web Server #
2019-07-29 20:46:26 +03:00
2021-05-15 05:53:25 +03:00
A simple yet powerful web server with built-in routing, parameter handling,
templating, and other features.
2021-05-15 05:53:25 +03:00
## Alpha level software ##
2019-07-29 20:46:26 +03:00
2021-05-15 05:53:25 +03:00
Some features may not be complete, and there may still be bugs. However, it is
still a very useful tool. The [gitly](https://gitly.org/) site is based on vweb.
2019-07-29 19:50:25 +03:00
2021-05-15 05:53:25 +03:00
## Features ##
2019-07-30 22:15:17 +03:00
2021-05-15 05:53:25 +03:00
- **Very fast** performance of C on the web.
- **Small binary** hello world website is <100 KB.
- **Easy to deploy** just one binary file that also includes all templates.
No need to install any dependencies.
- **Templates are precompiled** all errors are visible at compilation time,
not at runtime.
There is no formal documentation yet - here is a simple
[example](https://github.com/vlang/v/tree/master/examples/vweb/vweb_example.v)
There's also the V forum, [vorum](https://github.com/vlang/vorum)
2019-07-30 22:15:17 +03:00
`vorum.v` contains all GET and POST actions.
2019-07-29 19:50:25 +03:00
```v ignore
2019-07-29 19:50:25 +03:00
pub fn (app mut App) index() {
posts := app.find_all_posts()
$vweb.html()
}
// TODO ['/post/:id/:title']
// TODO `fn (app App) post(id int)`
2019-07-29 19:50:25 +03:00
pub fn (app App) post() {
id := app.get_post_id()
2019-07-29 19:50:25 +03:00
post := app.retrieve_post(id) or {
2020-12-31 19:47:20 +03:00
app.redirect('/')
return
2019-07-29 19:50:25 +03:00
}
comments := app.find_comments(id)
show_form := true
2019-07-29 19:50:25 +03:00
$vweb.html()
}
```
`index.html` is an example of the V template language:
2019-07-29 20:46:26 +03:00
```html
@for post in posts
2019-07-29 19:50:25 +03:00
<div class=post>
<a class=topic href="@post.url">@post.title</a>
<img class=comment-img>
<span class=nr-comments>@post.nr_comments</span>
2019-07-29 19:50:25 +03:00
<span class=time>@post.time</span>
</div>
@end
```
2020-12-31 19:47:20 +03:00
`$vweb.html()` compiles an HTML template into V during compilation,
2021-05-15 05:53:25 +03:00
and embeds the resulting code into the current action.
2019-07-29 19:50:25 +03:00
2019-09-14 23:54:14 +03:00
That means that the template automatically has access to that action's entire environment.
2019-07-29 20:46:26 +03:00
2021-05-15 05:53:25 +03:00
## Deploying vweb apps ##
2019-07-29 20:46:26 +03:00
Everything, including HTML templates, is in one binary file. That's all you need to deploy.
2021-05-15 05:53:25 +03:00
## Getting Started ##
To start with vweb, you have to import the module `vweb`. After the import,
define a struct to hold vweb.Context (and any other variables your program will
need).
2021-05-17 08:51:49 +03:00
The web server can be started by calling `vweb.run(&App{}, port)`.
**Example:**
2021-05-15 05:53:25 +03:00
```v ignore
import vweb
struct App {
vweb.Context
}
fn main() {
2021-05-17 08:51:49 +03:00
vweb.run(&App{}, 8080)
}
```
2021-05-15 05:53:25 +03:00
### Defining endpoints ###
To add endpoints to your web server, you have to extend the `App` struct.
For routing you can either use auto-mapping of function names or specify the path as an attribute.
The function expects a response of the type `vweb.Result`.
**Example:**
2021-05-15 05:53:25 +03:00
```v ignore
// This endpoint can be accessed via http://localhost:port/hello
fn (mut app App) hello() vweb.Result {
return app.text('Hello')
}
// This endpoint can be accessed via http://localhost:port/foo
["/foo"]
fn (mut app App) world() vweb.Result {
return app.text('World')
}
```
To create an HTTP POST endpoint, you simply add a `[post]` attribute before the function definition.
**Example:**
2021-05-15 05:53:25 +03:00
```v ignore
[post]
fn (mut app App) world() vweb.Result {
return app.text('World')
}
```
To pass a parameter to an endpoint, you simply define it inside
an attribute, e. g. `['/hello/:user]`.
After it is defined in the attribute, you have to add it as a function parameter.
**Example:**
2021-05-15 05:53:25 +03:00
```v ignore
['/hello/:user']
fn (mut app App) hello_user(user string) vweb.Result {
return app.text('Hello $user')
}
```
You have access to the raw request data such as headers
or the request body by accessing `app` (which is `vweb.Context`).
If you want to read the request body, you can do that by calling `app.req.data`.
2021-05-15 05:53:25 +03:00
To read the request headers, you just call `app.req.header` and access the
header you want, e.g. `app.req.header.get(.content_type)`. See `struct Header`
for all available methods (`v doc net.http Header`).