Quickstart

Requirements

Jetzig requires Zig master. Fetch the latest nightly build from the Zig website: https://ziglang.org/download/

Download

Visit the downloads page and follow the instructions download the appropriate pre-compiled binary for your operating system.

Create a new project

Use the interactive command line tool to generate a new project. You will be prompted with a few options to choose how to initialize your project.

$ jetzig init

Launch a server

The command line tool also provides a server launcher that reloads the server when changes are detected. This is a simple wrapper around zig build run.

$ jetzig server

Generate a view

Use the command line tool again to generate a view for the /iguanas endpoint with an index function:

$ jetzig generate view iguanas index

A default view is provided for the root path: /. This view is named root.zig. Other routes are mapped to the name of the view.

For example, the index function in src/app/views/iguanas.zig maps to the following endpoints:

  • /iguanas
  • /iguanas.html
  • /iguanas.json

All views in Jetzig automatically provide JSON endpoints, and any view function with a corresponding template will render HTML.

Jetzig uses its own templating language: Zmpl. The template for the /iguanas.html endpoint is located in src/app/views/iguanas/index.zmpl.

The default response format is html, but this can be overridden by specifying one of the following:

  • .json extension in the URL
  • Accept: application/json request header
  • Content-Type: application/json request header

Create some data

A core concept to Jetzig is its handling of response data. In Jetzig, template data and JSON data are one and the same. Simply add data to your response and it is automatically available in templates and JSON endpoints.

Set the root object of the response data using request.data(.object) or request.data(.array). Add values to the root object and use them in your templates or view them as JSON. All values you wish to publish must be added to the root object before rendering. Here's an example:

// src/app/views/iguanas.zig
const jetzig = @import("jetzig");

pub fn index(request: *jetzig.Request) !jetzig.View {
    var root = try request.data(.object);
    try root.put("message", "Welcome to Jetzig!");
    try root.put("iguana_count", 100_000);

    return request.render(.ok);
}

You can now use Zmpl's data lookup syntax to access these values in your template:

@// src/app/views/iguanas/index.zmpl
<div>Message: {{.message}}</div>
<div>{{.iguana_count}} iguanas!</div>

Browse to http://localhost:8080/iguanas.html to see your rendered HTML (the .html exnension is optional) or visit http://localhost:8080/iguanas.json to see the raw JSON data.

Generate a layout

To avoid having to copy and paste the same page layout repeatedly and to help keep your templates focused and concise, Jetzig provides layout templates.

Use the command line tool again to create a layout named custom_layout:

$ jetzig generate layout custom_layout

Then add the following line of code anywhere in src/app/views/iguanas.zig:

pub const layout = "custom_layout";

All HTML output for view functions in the /iguanas route will now be enclosed inside the content in src/app/views/layouts/custom_layout.zmpl.