v/vlib/vweb
Lukas Neubert 0f8f8bd90d
fmt: force empty lines after struct declarations and most functions (#9096)
2021-03-03 23:56:40 +01:00
..
assets all: bring back `panic(err.msg)` -> `panic(err)` (#9022) 2021-03-01 00:18:14 +01:00
sse all: add strings.Builder.write_string and use write_string instead of write (#8892) 2021-02-22 13:18:11 +02:00
tests ci: reduce chances of false positives from vweb_test.v on macos 2021-03-03 10:04:12 +02:00
tmpl tmpl: fix doubling templates folder path and enhancements (#9029) 2021-03-01 11:15:59 +02:00
README.md docs: add a basic vweb getting started example (#9073) 2021-03-03 14:39:04 +02:00
request.v vweb: fix timeouting after 30 seconds, when a request with `Content-Length: 0` was processed 2021-03-02 21:02:44 +02:00
request_test.v vweb: refactor HTTP request parsing (#8874) 2021-02-27 23:18:25 +01:00
route_test.v fmt: force empty lines after struct declarations and most functions (#9096) 2021-03-03 23:56:40 +01:00
vweb.v vweb: add .mount_static_folder_at/2 , use it instead of app.handle_static in the server_sent_events example 2021-03-02 21:30:18 +02:00

README.md

This is pre-alpha software.

Features

  • 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.

Lots of things are broken and not implemented yet in V and vweb.

There's no documentation yet, have a look at a simple example:

https://github.com/vlang/v/tree/master/examples/vweb/vweb_example.v

There's also the V forum: https://github.com/vlang/vorum

vorum.v contains all GET and POST actions.

pub fn (app mut App) index() {
	posts := app.find_all_posts()
	$vweb.html()
}

// TODO ['/post/:id/:title']
// TODO `fn (app App) post(id int)`
pub fn (app App) post() {
	id := app.get_post_id()
	post := app.retrieve_post(id) or {
		app.redirect('/')
		return
	}
	comments := app.find_comments(id)
	show_form := true
	$vweb.html()
}

index.html is an example of the V template language:

@for post in posts
	<div class=post>
		<a class=topic href="@post.url">@post.title</a>
		<img class=comment-img>
		<span class=nr-comments>@post.nr_comments</span>
		<span class=time>@post.time</span>
	</div>
@end

$vweb.html() compiles an HTML template into V during compilation, and embeds the resulting code in current action.

That means that the template automatically has access to that action's entire environment.

Deploying vweb apps

Everything, including HTML templates, is in one binary file. That's all you need to deploy.

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). The web server can be started by calling vweb.run<App>(port).

Example:

import vweb

struct App {
    vweb.Context
}

fn main() {
	vweb.run<App>(8080)
}

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:

// 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:

[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:

['/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. To read the request headers, you just call app.req.headers and access the header you want, e.g. app.req.headers['Content-Type']