Skip to content

API_REFERENCE.md

Latest commit

 

History

History
116 lines (82 loc) · 7.05 KB

API_REFERENCE.md

File metadata and controls

116 lines (82 loc) · 7.05 KB

snapfire API Reference

This document provides a detailed, unambiguous reference for all public API elements of the snapfire crate, suitable for developers or automated systems with no prior knowledge of the library.

1. Introduction & Core Concepts

  • Core Concept: snapfire is a library that integrates the tera templating engine with the actix-web framework. Its primary goal is to provide a simple API for rendering templates and to offer an optional, automatic live-reload feature for development.

  • Primary Handle: The central struct for all operations is snapfire::TeraWeb. An instance of this struct is created at application startup, holds all rendering configuration, and is shared with all Actix handlers.

  • Configuration Entry Point: All configuration and initialization is performed through the snapfire::TeraWebBuilder, which is created via snapfire::TeraWeb::builder().

  • Rendering Pattern: The library uses a "renderable struct" pattern. Calling TeraWeb::render() does not perform the render immediately. Instead, it returns an instance of snapfire::Template. This Template struct is what you return from an Actix handler. Actix then uses snapfire's implementation of the Responder trait on Template to perform the actual rendering asynchronously.

  • Pervasive Types:

    • snapfire::Result<T>: All fallible operations in this library (like build()) return this Result type, which is an alias for std::result::Result<T, snapfire::SnapFireError>.
    • tera::Context: When rendering, users must provide a context object of this type, which comes from the tera crate.

2. Main Types and Their Public Methods

Struct: snapfire::TeraWeb

The primary application state for SnapFire.

Public Methods

  • builder

    • Signature: pub fn builder(templates_glob: &str) -> TeraWebBuilder
    • Description: Creates a new TeraWebBuilder to configure and build a TeraWeb instance. This is the main entry point for using the library.
    • Parameters:
      • templates_glob: &str – A glob pattern used by tera to discover template files. Example: "templates/**/*.html".

  • render

    • Signature: pub fn render(&self, tpl: &str, context: tera::Context) -> Template
    • Description: Prepares a template for rendering by returning a Template struct. This method is synchronous.
    • Parameters:
      • tpl: &str – The name of the template file to render, relative to the templates directory. Example: "pages/index.html".
      • context: tera::Context – The tera::Context object containing the variables for this specific render.

  • configure_routes

    • Availability: Only available when the devel feature is enabled.
    • Signature: #[cfg(feature = "devel")] pub fn configure_routes(&self, cfg: &mut actix_web::ServiceConfig)
    • Description: Configures Actix application routes required for snapfire's development features (specifically, the live-reload WebSocket). In release builds (without the devel feature), this method is a no-op.
    • Parameters:
      • cfg: &mut actix_web::ServiceConfig – The mutable Actix service configuration that the WebSocket route will be added to.

Struct: snapfire::TeraWebBuilder

A builder used to configure and create a TeraWeb instance.

Public Methods

  • add_global

    • Signature: pub fn add_global<S: Into<String>, T: serde::Serialize>(mut self, key: S, value: T) -> Self
    • Description: Adds a variable to the global context, making it available to all templates rendered by this instance.
    • Parameters:
      • key: S where S: Into<String> – The name of the variable as it will be used in templates.
      • value: T where T: serde::Serialize – Any value that implements the serde::Serialize trait.

  • configure_tera

    • Signature: pub fn configure_tera<F>(mut self, configurator: F) -> Self where F: FnOnce(&mut tera::Tera) + 'static
    • Description: Provides a closure for advanced, direct manipulation of the tera::Tera instance before it is finalized. Use this to register custom filters, functions, etc.
    • Parameters:
      • configurator: F where F: FnOnce(&mut tera::Tera) + 'static – A closure that receives a mutable reference to the newly created tera::Tera instance.

  • watch_static

    • Availability: Only available when the devel feature is enabled.
    • Signature: #[cfg(feature = "devel")] pub fn watch_static(mut self, path: &str) -> Self
    • Description: Adds a static asset directory path for the live-reload watcher to monitor for changes.
    • Parameters:
      • path: &str – The path to a directory to watch. Example: "static/css".

  • ws_path

    • Availability: Only available when the devel feature is enabled.
    • Signature: #[cfg(feature = "devel")] pub fn ws_path(mut self, path: &str) -> Self
    • Description: Customizes the URL path for the live-reload WebSocket endpoint.
    • Parameters:
      • path: &str – The URL path. Defaults to "/_snapfire/ws".

  • auto_inject_script

    • Availability: Only available when the devel feature is enabled.
    • Signature: #[cfg(feature = "devel")] pub fn auto_inject_script(mut self, enabled: bool) -> Self
    • Description: Controls whether the live-reload JavaScript is automatically injected into HTML responses.
    • Parameters:
      • enabled: bool – Set to false to disable injection. Defaults to true.

  • build

    • Signature: pub fn build(self) -> Result<TeraWeb>
    • Description: Consumes the builder and attempts to create the final TeraWeb instance. This can fail if the template glob is invalid or if the watcher fails to initialize.

Struct: snapfire::Template

A struct representing a render operation. It has no public fields or methods. Its primary interface is its implementation of actix_web::Responder.

Struct: snapfire::actix::dev::InjectSnapFireScript

An Actix middleware. It has no public fields or methods. It is instantiated via InjectSnapFireScript::default() and used with actix_web::App::wrap().

3. Public Type Aliases

Type Alias: snapfire::Result

  • Definition: pub type Result<T, E = SnapFireError> = std::result::Result<T, E>;
  • Description: The standard Result type used throughout the snapfire crate.

4. Error Handling

Enum: snapfire::SnapFireError

The unified error enum for all fallible operations in the library.

Enum Variants

  • Tera(tera::Error): Wraps an error from the underlying tera crate.
  • Io(std::io::Error): Wraps a standard I/O error.
  • Serialization(String): An error occurred during context serialization.
  • Watcher(notify::Error): (Only available when the devel feature is enabled). Wraps an error from the notify file watcher crate.