@spec html(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Sends an HTML response with a 200 status code and HTML content.

Warning: The following function does not escape HTML content. Passing user-generated or untrusted input may result in Cross-Site Scripting (XSS) vulnerabilities. Only use this function with trusted, static HTML content. Use Francis.HTML.escape/1 for escaping untrusted content, or use safe_html/2 which escapes content automatically.

Examples

defmodule Example do
  use Francis

  get("/", fn conn ->
    html(conn, "<h1>Hello World!</h1>")
  end)
end

@spec html(Plug.Conn.t(), integer(), String.t()) :: Plug.Conn.t()

Sends an HTML response with the given status code and HTML content.

Warning: The following function does not escape HTML content. Passing user-generated or untrusted input may result in Cross-Site Scripting (XSS) vulnerabilities. Only use this function with trusted, static HTML content. Use Francis.HTML.escape/1 for escaping untrusted content, or use safe_html/2 which escapes content automatically.

Examples

defmodule Example do
  use Francis

  get("/", fn conn ->
    html(conn, 201, "<h1>Created</h1>")
  end)
end

@spec json(Plug.Conn.t(), map() | list()) :: Plug.Conn.t()

Sends a JSON response with a 200 status code and the given data.

Examples

defmodule Example do
  use Francis

  get("/api/data", fn conn ->
    json(conn, %{message: "Success", data: [1, 2, 3]})
  end)
end

@spec json(Plug.Conn.t(), integer(), map() | list()) :: Plug.Conn.t()

Sends a JSON response with the given status code and data.

Examples

defmodule Example do
  use Francis

  post("/users", fn conn ->
    json(conn, 201, %{id: 123, message: "User created"})
  end)
end

@spec markdown(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Sends a Markdown response with a 200 status code and the given content.

Examples

defmodule Example do
  use Francis

  get("/readme", fn conn ->
    markdown(conn, "# Hello World!")
  end)
end

@spec markdown(Plug.Conn.t(), integer(), String.t()) :: Plug.Conn.t()

Sends a Markdown response with the given status code and content.

Examples

defmodule Example do
  use Francis

  get("/readme", fn conn ->
    markdown(conn, 200, "# Hello World!")
  end)
end

@spec redirect(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Redirects the connection to the specified path with a 302 status code.

Only relative paths are accepted. Absolute URLs (e.g. http://...) will raise an ArgumentError to prevent open redirect vulnerabilities. Protocol-relative URLs (e.g. //evil.com) are neutralized to "/", as are paths a browser could normalise into one: paths containing a backslash (/\evil.com), ASCII control characters such as tab, CR or LF (/\t/evil.com), or leading whitespace.

Examples

defmodule Example do
  use Francis

  get("/old", fn conn -> redirect(conn, "/new") end)
end

@spec redirect(Plug.Conn.t(), integer(), String.t()) :: Plug.Conn.t()

Redirects the connection to the specified path with a custom status code.

Only relative paths are accepted. See redirect/2 for details on URL validation.

Examples

defmodule Example do
  use Francis

  get("/old", fn conn -> redirect(conn, 301, "/new") end)
end

@spec safe_html(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Sends a response with a 200 status code, escaping the entire content string to prevent XSS.

Unlike html/2, this function escapes all HTML special characters in the content. Use it when the entire response is untrusted input that should be rendered as escaped text.

To mix trusted markup with user content, use html/2 with Francis.HTML.escape/1 on only the interpolated values:

html(conn, "<h1>Hello, #{Francis.HTML.escape(user_input)}!</h1>")

Examples

defmodule Example do
  use Francis

  get("/", fn conn ->
    user_input = conn.params["name"]
    safe_html(conn, user_input)
  end)
end

@spec safe_html(Plug.Conn.t(), integer(), String.t()) :: Plug.Conn.t()

Sends a response with the given status code, escaping the entire content string to prevent XSS.

Unlike html/3, this function escapes all HTML special characters in the content. Use it when the entire response is untrusted input that should be rendered as escaped text.

To mix trusted markup with user content, use html/3 with Francis.HTML.escape/1 on only the interpolated values:

html(conn, 201, "<h1>Created: #{Francis.HTML.escape(user_input)}</h1>")

Examples

defmodule Example do
  use Francis

  get("/", fn conn ->
    user_input = conn.params["name"]
    safe_html(conn, 201, user_input)
  end)
end

@spec text(Plug.Conn.t(), String.t()) :: Plug.Conn.t()

Sends a text response with a 200 status code and the given text.

Examples

defmodule Example do
  use Francis

  get("/hello", fn conn ->
    text(conn, "Hello World!")
  end)
end

@spec text(Plug.Conn.t(), integer(), String.t()) :: Plug.Conn.t()

Sends a text response with the given status code and text.

Examples

defmodule Example do
  use Francis

  get("/text", fn conn ->
    text(conn, 200, "Hello World!")
  end)
end