Introduction

What is Vex

Vex is an easy-to-use, modular web framework written on V. It's design is inspired from the KISS (Keep It Simple, Stupid) principle and is composed of the following submodules:

• server - The server submodule. It is used for running an HTTP server.
• router - The router submodule. It handles the creation of routes and listening incoming requests for matching the right handlers.
• ctx - The context submodule. It contains the type declarations for the request (Req) and response (Resp) structs as well as its related methods.
• mime - The MIME submodule. It is used for identifying appropriate MIME data types based on the file format given. A fork of v-mime.
• html The HTML submodule. It is used for declarative building of HTML views/user interface.
• utils - The utilities submodule. Helper methods that are shared by the above submodules but can be used in your own project as well.

Not all of the submodules are needed for a typical Vex web project. The ctx and server submodules are sufficient enough for you to get started.

Getting Started

This tutorial assumes that you have decent knowledge of the V language and have Vex module installed. If you haven't installed it yet, please proceed first to the installation page then go back here once you're done.

Simple greeter web site

We are gonna be doing a simple web site which greets the person based on the name provided. At the root of your project directory, create a file named greeter.v. Afterwards, copy the following contents:

module main

import vex.server
import vex.ctx

fn main() {
   // Code goes here!
}

TIP: If you installed Vex as a global module, just replace vex. with nedpals.vex. instead.

Initializing the server

We cannot be able to access the greeter without initiating a new instance of the HTTP server. Below of the commented code inside the main function, type the following code.

// fn main() {
//      // Code goes here!
        mut s := server.new()
// }

The new function found on the server submodule allows us to create a new instance of the server struct and access its methods like creating routes.

Creating our first route

We have now initiated the server, now it's time to create our first route for this program. Below the existing code, add the following:

//   mut s := server.new()
s.get('/greet/:name', fn (req ctx.Req, res mut ctx.Resp) {
   // route code goes here
})

The get method allows us to create a GET route which we can use to access a specific resource inside the browser or an HTTP client. Inside the get method, we need to specify the path for this route which is /greet/:name and the specific function will be used to execute for this route.

We can now send whatever we want to this route. In this case, we need to send the words "Hello" and the name of the person specified by the user. Inside the route function, do the following:

// s.get('/greet/:name', fn (req ctx.Req, res mut ctx.Resp) {
   name := req.params['name']
   res.send('Hello, $name!', 200)
// })

This will send the corresponding text with the response with a status code of 200 which is the equivalent of an OK response.

Getting the name data

Now you're wondering where do we get the contents of the name variable. Earlier we have created a route with the path of /greet/:name and as you can see at the last part there is a "name" word prepended by a colon (:name). This is what we call a route parameter and it enables us to dynamically access and provide the data to the user based on a given value. To get the value of the specific parameter, just use req.params[<param key>]. In this case, /greet/Joe will be routed to /greet/:name and by calling req.params['name'], we can now obtain the name which is Joe.

Starting the server

Our simple greeter web site is done and we can now start the server by executing s.serve(8000) below all the server code. Afterwards open your terminal pointing to your project directory and execute v run . to compile and automatically run the program. Once the program starts, the terminal should output Serving at port: 8000 and you will be able to access it through http://localhost:8000.

Code

module main

import vex.server
import vex.ctx

fn main() {
   // Code goes here!
   mut s := server.new()
   s.get('/greet/:name', fn (req ctx.Req, res mut ctx.Resp) {
     name := req.params['name']
     res.send('Hello, $name!', 200)
   })
   s.serve(8000)
}

In other 20 lines of code, we've been able to create a simple HTTP web site using Vex.