# HTML Building with Ztack Ztack's `html.zig` module provides a powerful, type-safe, and efficient way to programmatically generate HTML content in Zig. It focuses on minimizing allocations, enabling direct streaming to network sockets or files, and offering a clean builder API for common HTML elements. ## Core Concepts: `HtmlDocument` and `Element` At the heart of Ztack's HTML generation are two key types: * **`html.HtmlDocument`**: This struct manages the overall construction and rendering of an entire HTML page. You initialize it with an allocator, build a page using arrays of elements, and then either get the complete HTML as a `[]const u8` or stream it directly to a writer. * **`html.Element`**: This is the fundamental building block. Every HTML builder function returns an `Element`, representing a self-contained HTML tag or text node. These elements can then be nested to form complex page structures. You can find the full API reference for these types in the [Ztack API Reference]. ### Initializing and Rendering a Page To start building an HTML page, you first need an instance of `HtmlDocument`: ```zig const std = @import("std"); const html = @import("html"); pub fn main() !void { var gpa = std.heap.GeneralPurposeAllocator(.{}){}; defer _ = gpa.deinit(); const allocator = gpa.allocator(); var doc = html.HtmlDocument.init(allocator); defer doc.deinit(); // Assuming deinit exists to clean up internal state // ... define head_elements and body_elements ... // Option 1: Build a complete page as a byte slice const html_output = try doc.build(head_elements, body_elements); std.debug.print("{s}\n", .{html_output}); // Option 2: Render directly to a writer (e.g., std.io.stdout.writer()) // var writer = std.io.stdout.writer(); // try doc.renderToWriter(writer, head_elements, body_elements); } ``` #### `doc.build(head_elements: []const Element, body_elements: []const Element) ![]const u8` This function takes two arrays of `Element`s – one for the `` section and one for the `` section – and returns a `[]const u8` containing the complete, rendered HTML document. This is useful when you need the entire HTML content in memory, for example, to send as an HTTP response body. #### `doc.renderToWriter(writer: anytype, head_elements: []const Element, body_elements: []const Element) !void` For maximum efficiency, especially with large pages or when sending data directly over a network socket, `renderToWriter` allows you to stream the generated HTML directly to any `std.io.Writer` implementation. This method avoids intermediate string buffers and reduces memory allocations significantly, often leading to ~50% faster rendering for large pages and a 99.9% reduction in intermediate allocations. ## HTML Builder API The `html.zig` module provides a rich set of helper functions, each corresponding to a standard HTML element. These functions typically take an optional class/ID string (represented by `?[]const u8` for nullable strings) and an array of child `Element`s. ### Text Content To include plain text within an HTML element, use `html.text()`: ```zig const my_text_element = html.text("This is some plain text."); ``` * **`html.text(content: []const u8) Element`**: Creates a text node. `content` is the string to be displayed. ### Containers and Structural Elements These functions help define the layout and hierarchy of your page. ```zig const heading_content = html.h1("main-title", &[_]html.Element{ html.text("Welcome to Ztack!") }); const paragraph_content = html.p(null, &[_]html.Element{ html.text("This is a paragraph with some "), html.span("highlight", &[_]html.Element{ html.text("highlighted") }), html.text(" text."), }); const container = html.div("page-container", &[_]html.Element{ heading_content, paragraph_content, }); ``` * **`html.div(class_or_id: ?[]const u8, children: []const Element) Element`**: Creates a `

` element. `class_or_id` can be a class string or an ID string (e.g., "my-div-id" or "my-class"). * **`html.h1(class: ?[]const u8, children: []const Element) Element`**: Creates an `

` heading. * `html.h2(class: ?[]const u8, children: []const Element) Element`: Creates an `

` heading. * `html.p(class: ?[]const u8, children: []const Element) Element`: Creates a `
` (paragraph) element. * `html.span(class: ?[]const u8, children: []const Element) Element`: Creates a `` element. * All container functions accept `children: []const Element`, which is an array literal of child elements to be nested inside. Use `null` for `class` or `class_or_id` if no attribute is needed. ### Interactive Elements Ztack provides dedicated builders for common interactive UI components. ```zig const simple_button = html.button("btn-info", "alert('Hello!');", &[_]html.Element{ html.text("Click for Alert") }); const delegated_button = html.button_data("btn-primary", "click:handleClick", &[_]html.Element{ html.text("Click Me (Delegated)") }); const text_input = html.input("text", "username", "form-control"); const value_input = html.input_with_value("hidden", "user_id", "123"); const learn_more_link = html.anchor("/docs", "link-style", &[_]html.Element{ html.text("Learn More") }); ``` * `html.button(class: ?[]const u8, onclick: []const u8, children: []const Element) Element`: Creates a `

` heading. * **`html.h2(class: ?[]const u8, children: []const Element) Element`**: Creates an `

` heading. * `html.h2(class: ?[]const u8, children: []const Element) Element`: Creates an `

HTML Building with Ztack

Page Viewers

Guest Views