Fullmoon Lua Web Framework

An action handler is a function passed to setRoute. Multiple handlers can be chained for a single route. The processing stops as soon as a handler returns a non-false value.

Handler Return Values:

• true: Stops processing, sets specified headers, and returns the response body.
• false or nil: Stops the current route's processing and proceeds to the next registered route (useful for middleware/filters).
• string: Sends a 200 OK response with the string as the body. Content-Type is inferred.
• function: Executes a serve* method and signals the end of processing.
• Other values: Treated as true (a warning is logged).

Chaining Handlers (Middleware Pattern):

To implement logic that applies to multiple routes (like user authentication), return false from the first handler to allow subsequent handlers to run.

local uroute = "/user/:id"
fm.setRoute({uroute.."/*", method = {"GET", "POST", otherwise = 405}},
    function(r)
      -- retrieve user information and store in r.user
      return false -- continue handling to the next route
  end)
fm.setRoute(fm.GET(uroute.."/view"), function(r) ... end)

Fullmoon's template engine allows mixing text with Lua statements and expressions. Templates are parsed during registration and converted into Lua functions for high performance.

Key Characteristics:

• Direct Rendering: Templates render directly to the output buffer (delegated to redbean) rather than returning a string.
• Restricted Environment: Templates only have access to explicitly passed parameters or the vars and block tables.
• Syntax Types:
  • {% statement %}: Executes Lua statements (e.g., if, for).
  • {%& expression %}: Renders a Lua expression as HTML-safe text.
  • {%= expression %}: Renders a Lua expression as-is (no escaping). Use with caution to avoid XSS.

Core Functions:

• setTemplate(name, text[, parameters]): Registers a template. Overwrites existing templates with the same name.
• render(name, parameters): Renders a registered template using the provided parameters.

fm.setTemplate("hello", "Hello, {%& title %}!")
fm.render("hello", {title = "World"})

Fullmoon uses a block-based system to enable composable layouts and component inheritance. You can define default content for a section using {% function block.name() %} ... {% end %} and then call it with {% block.name() %}.

Child templates can overwrite these blocks by redefining the same function before rendering the parent template. This creates a render tree where the most specific (deepest) definition of a block is used.

Key behaviors:

• Overwriting: A child template defines a block to customize a parent's layout.
• Nesting: Blocks can be nested within other blocks or Lua statements.
• Optional Blocks: To prevent errors if a block is not defined anywhere in the render tree, check for its existence before calling: {% block.name and block.name() %}.
• Super Reference: You can explicitly call a block from a specific template using the syntax {% block.<templatename>.<blockname>() %} to simulate a 'super' call.

-- base/layout template
{% function block.greet() %} -- 1. defines default "greet" block
  Hi
{% end %}
{% block.greet() %}          -- 2. calls "greet" block

-- child template
{% function block.greet() %} -- 3. defines "greet" block
  Hello
{% end %}
{% render('base') %}         -- 4. renders "base" template

-- grandchild template
{% function block.greet() %} -- 5. defines "greet" block
  Bye
{% end %}
{% render('child') %}        -- 6. renders "child" template

Fullmoon processes HTTP requests by matching the path URL against registered routes in the order they were defined. The routing lifecycle follows these steps:

1. Path Matching: Matches the request URL against route URLs sequentially.
2. Condition Verification: Checks any conditions associated with the matching route.
3. Action Execution: Calls the specified action handler (a Lua function) if all conditions are met, passing a request table.
4. Response Serving: Serves the response if the handler returns something other than false or nil.

Important Behaviors:

• Order Matters: Routes are evaluated in registration order. More specific routes (e.g., /user/bob) must be registered before more general routes (e.g., /user/:name) to ensure they are matched correctly.
• Condition Failure: If a condition fails, routing for that route is aborted, and the next route is checked. However, a condition can set an otherwise value to trigger a specific response status code immediately.
• 404 Handling: If no routes match, a 404 is returned. You can customize this by setting a custom 404 template using fm.setTemplate("404", "...").

Fullmoon supports two patterns for complex layouts:

1. Dynamic Template Selection

Pass the name of the template you want to render as a parameter to a wrapper template.

fm.setTemplate("header", "<h1>{% render(content, {title = title}) %}</h1>")
fm.render("header", {title = 'World', content = 'hello_template_name'})

2. Blocks (Inheritance Pattern)

Define a 'layout' template that calls functions stored in the block table. 'Child' templates can then overwrite these functions in the block table before rendering the layout.

Workflow:

1. Layout: Defines a block function in block.name() and calls {% block.name() %} where it should appear.
2. Child: Defines {% function block.name() %} ... {% end %} to provide new content, then calls render on the layout.

Note: The block must be explicitly called from the base/layout template to be rendered.

-- Layout template
fm.setTemplate("header", "<h1\>{% function block.greet() %}Hi{% end %}{% block.greet() %}, {%& title %}!</h1>")

-- Child template overwriting the block
fm.setTemplate("hello", "{% function block.greet() %}Hello{% end %}{% render('header', {title=title}) %}")

fm.render("hello", {title = 'World'}) -- renders <h1>Hello, World!</h1>

Routes can be filtered using various request attributes. When a condition is not met, the routing engine skips the route and checks the next one.

Supported conditions include:

• method: HTTP method (e.g., GET, POST).
• host: The Host header (use Host for the header, host for the request property).
• scheme: The request protocol (e.g., http, https).
• clientAddr / serverAddr: IP addresses (can use custom validators like fm.isLoopbackIp).
• ContentType: Request headers (e.g., ContentType = "application/json"). Note: only the media type is compared; boundaries/charsets are ignored.
• params: Request parameters (e.g., name = "Bob").
• Headers: Any header can be checked using its name as a key (e.g., X-Custom-Header = "value").

Precedence for overlapping names:

1. Multi-word request headers (e.g., ContentType)
2. Request parameters
3. Request properties (method, port, host, etc.)
4. Single-word request headers

Parameters can be passed to templates at two stages:

1. Registration: Using setTemplate(name, text, parameters), where parameters act as defaults.
2. Rendering: Using render(name, parameters), which overrides defaults.

Global Variables: Use setTemplateVar(name, value) to make a value accessible to all templates via the vars table.

Handling Undefined Values: By default, nil or false values render as empty strings. To enforce strictness, you can set a special if-nil variable in vars to trigger an error or log when a value is missing:

fm.setTemplateVar('if-nil', function() error"missing value" end)

-- Setting a global variable
fm.setTemplateVar('title', 'World')
fm.setTemplate("hello", "Hello, {%& vars.title %}!")
fm.render("hello") -- renders `Hello, World!`

-- Overriding via render
fm.render("hello", {title = "All"}) -- renders `Hello, All!`