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.
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:
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" ]
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
/contact, the form needs to be submitted to
To specify the path for a given handler, set
path equal to it. The path must
begin with a
[handlers.email.example] path = "/contact"
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
[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>
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
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
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" = [""]