If you like my work, please consider supporting its development.

Even though handlers in Nebula Forms are implemented as plugins, there are certain configuration options that are common to all of them. This page outlines what those options are.

Allowed Origins

Handlers can be configured to respond only to requests from certain origins, a word in this case being a combination of protocol and domain name. Each of these are considered different origins:

  • http://example.com
  • https://example.com
  • https://www.example.com

There is also a special value, "*", that represents that all origins will be handled. This is a very dangerous value to use, since it means any site can create forms that are sent to this handler. It is almost always better to create a list of allowed origins instead.

To set the list of allowed origins for a handler, set the value of allowed_origins to an array of values. For example:

[handlers.email.example]
    allowed_origins = [
        "https://bluestnight.com",
        "https://shadow53.com"
    ]

Handler Path

Every handler is registered to a particular path that it responds to, relative to the base URL of the Nebula Forms instance.

If Nebula is hosted at https://forms.example.com and a handler is registered to /contact, the form needs to be submitted to https://forms.example.com/contact.

Multiple handlers can be registered to the same path. The allowed origins and handle conditions are used to determine whether a particular handler should be used for a given submission to that form.

To specify the path for a given handler, set path equal to it. The path must begin with a /

[handlers.email.example]
    path = "/contact"

Honeypots

A honeypot is a form field that is hidden from humans but is visible to spambots, which parse the source code of a page. The honeypots used by Nebula must remain blank - if they contain a value, the form submission is discarded. Regardless of if the submission was processed or discarded, the server returns a status code indicating success - this prevents spam bots from trying again.

Some spam bots are smart enough to figure out that a field is a honeypot and doesn’t fill it out, but this method still stops a lot of drive-by bot spamming.

Keep in mind that a honeypot will not stop a human spammer visiting your site. Other precautions will need to be made to stop that kind of spam.

To enable honeypot filtering on a handler in Nebula, set honeypot to the value of the input’s name attribute.

[handlers.email.example]
    # Spambots like to leave links and this name looks like
    # a field to put links in.
    honeypot = "homepage"
<form name="example-form">
    Name: <input type="text" name="name" required><br/>
    Email: <input type="email" name="email" required><br/>
    <!-- This field is hidden with CSS -->
    <input class="hide" type="text" name="homepage">
    Contact Reasion: <textarea name="reason"></textarea><br/>
    <button type="submit">Submit</button>
</form>

Handle Conditions

As well as with origins and paths, handlers can be configured to be executed based on the contents of the form submission.

There are two main ways to use form input values to determine whether the handler should handle the submission. The first is based on whether the input has any value; the second, based on whether the input’s value is within a set of valid values.

In both cases, conditions are set by settings key-value pairs under handle_if in the handler configuration, where the key is the value of the input field’s name attribute and the key matches one of the specifications below. See below for examples of how to set conditions, as well.

When using conditions, all conditions must be met in order for the handler to handle. There is currently no support for either/or conditions - you will have to create separate handlers for each case.

Handler conditions are triggers, not validators. If you want to validate that a required input matches some condition, do so in a template so you can display an error to the user. Using conditions will only cause the form entry to be ignored.

If Input Is Not Empty

If the should run when the input is non-empty but has any value otherwise, set the key-value to true. An example can be found below.

If Input Has a Specific Value

If the input must have a specific value or one of a set of specific values - like a checkbox or radio button must be checked - set the key-value to a list of allowed values. If the input does not match any of those values, the form submission is skipped by this handler.

If the input can be anything matching a particular pattern, use the “not empty” condition and validate that it matches the pattern inside of a template.

If Input Is Empty

Using the above method, you can set a condition for an empty value by making a list containing only the empty string "".

Examples

This example is for sending a confirmation email to someone who filled out a contact form with an optional email field.

[handlers.email.confirmation_email]
    allowed_origins = ["https://example.com"]
    honeypot = "honeypot input"
    # Other options
[handlers.email.confirmation_email.handle_if]
    # Only send confirmation if there is an email address to send to
    # Email address will be validated by the template for the "to"
    # email header
    email = true
    # User must have checked the "send confirmation" box.
    # "yes" is the value of the checkbox's `value` attribute
    send_confirm = ["yes"]
    # This is equivalent to setting the "honeypot" option on the handler
    # Quotes around the key allows there to be spaces in the key
    "honeypot input" = [""]