Information¶

The formsender app is a simple program that is designed to aid in the collection of form data. When a form is submitted, the app gathers the data from it and emails it to a configured email address.

How To Use Formsender¶

In conf.py.dist there are several settings that Formsender relies on. To use these settings copy them to a new conf.py file in the root directory. You can change the following variables to match your setup:

EMAIL = u'email@example.com'
TOKN = u's0m3T0k3n$tr1ng'
CEILING = 10
DUPLICATE_CHECK_TIME = 3600
HOST = "0.0.0.0"
PORT = 5000
SMTP_HOST = "smtp.osuosl.org"
FROM = "formsender@osuosl.org"

• EMAIL is where the form data will be sent.
• TOKN is the validating token from the form. This must match a hidden field in your form called ‘tokn’. You can find and set the TOKN variable in your conf.py file. Just make sure you also set the hidden tokn field value to match.
• CEILING is the maximum number of submit requests formsender will accept per second.
• DUPLICATE_CHECK_TIME is the time (in seconds) to check past form submissions for duplicate submissions.
• HOST and PORT is where the run_simple listener listens for POST requests
• SMTP_HOST sets the host for the sendmail function. Must be a smtp server
• FROM is the address the email will be sent from

You can run flake8 on request_handler (the application):

$ make flake

Once a valid conf.py file exists, tests can be run:

$ make tests

To run the application locally for development purposes:

$ make run

The app will now wait at HOST:PORT for the form to be submitted, and will email the information submitted to the email specified. HOST and PORT can be changed in conf.py to match your desired setup.

Set Up a Form¶

To use Formsender, you need to write an html form with several required and optional fields. Formsender uses these fields to authenticate the form and format the outgoing email message. To include these fields in your form just set the name, type, and value properties like this:

<input type="hidden" name="last_name" value=""/>

All Other Fields¶

Formsender formats the email like so:

Contact:
--------
NAME:   Submitted Name
EMAIL:   email@example.com

Information:
------------
Community Size:

About 15 developers

Deployment Timeframe:

Within 7 days

Distribution:

Fedora

Duration Of Need:

Six months

The contact information, name and email, is placed at the beginning of the email. All following fields are placed in alphabetical order by the input name. Formsender formats each input name to title case and uses it as titles in the email. Make sure these name fields are descriptive and do not use strange formatting like the following:

<input type="text" name="submitted[distribution]" value="" />

Formsender does not know how to interpret this name and will result in a Bad Request error from the server.

Error Codes¶

Formsender returns different error codes when invalid data is sent from the form.

These error codes can be handled with a little javascript in your redirect page:

// Get error number and message from query string
function getQueryVariable(variable) {
  var query = window.location.search.substring(1);
  var vars = query.split("&");
  for (var i = 0; i < vars.length; i++) {
    var pair = vars[i].split("=");
    if(pair[0] == variable) {
      return pair[1];
    }
  }
  return (false);
}

var errorNumber = getQueryVariable("error");
var errorMessage = getQueryVariable("message");

// errorMessage will only be a string if a query string is present.
// If a query string is present, there was an error. Format the message.
if (typeof errorMessage == "string") {
  errorMessage = errorMessage.replace("+", " ").replace("/", "");
}

// If both these exist, there was an error with the submission, write to page
if (errorNumber && errorMessage) {
  document.write("<h3 style='color:red'>An error occurred with your form submission</h3>",
                 "<p style='color:red'>Error number: ", errorNumber, "</p>",
                 "<p style='color:red'>Error message: ", errorMessage, "</p>");
}

Using Formsender with Docker¶

Formsender ships with a Dockerfile for easier development. Consult the docker documentation for instructions on how to use docker: http://docs.docker.com/

$ docker-compose build

$ docker-compose build --no-cache

$ docker-compose up