On form submission

It’s possible to run some custom code just before or just after form data is sent from a user’s device to a data source (or a third party database).

Scenarios where you may want to use these triggers include

• checking and validating form data before it’s submitted
• displaying a confirmation message once the data has been sent
• calculating a ‘quiz’ score and displaying it back to the user
• redirecting a user to a different screen depending on the data

You can run your custom code by attaching it to Fliplet Hook events. We have three hook events related to form submission. Hooks to do something before or after form submission are listed here. The third hook (do something if a form fails to submit) can be found here.

Before submitting

This hook will run after a form submission has been triggered (eg, by clicking a submit button) but before the data is sent to a datasource. It can be used to change the data, to add more data or to intercept the default submission process and send the data somewhere else (eg: to a third party database instead of a Fliplet datasource).

The code below runs after a form submission has been triggered. In this example, we’re creating (or updating) a field called “users-email” to be “hello@fliplet.com”.

Fliplet.Hooks.on('beforeFormSubmit', function (data) {
  // Add your code here

  // Change the data before it's sent
  data['Email'] = 'hello@fliplet.com';
});

You can cancel the submission by using a Promise.reject().

Fliplet.Hooks.on('beforeFormSubmit', function (data) {
  return Promise.reject('');
});

You can also cancel the submission and display an error message to the user.

Fliplet.Hooks.on('beforeFormSubmit', function (data) {
  return Promise.reject('The form submission was stopped!');
});

After submitting

This hook will run as soon as the data is sent. We have three scenarios where we can run custom code after submission:

1. We can run code immediately after the data is sent to the data source.
2. We can run code after we’ve sent the data and received a confirmation that it has been successfully saved.
3. We can run code if the data is unable to be sent (eg, due to no connectivity) and has been queued. In this instance, the form will repeatedly try to submit the data once a connection has been established. The app does need to be running to do this however.

As noted before we can also check there wasn’t an error with the submission. For details click here.

The code below covers the first case. It will be run when the data is submitted regardless of whether it’s successfully saved or not.

Fliplet.Hooks.on('afterFormSubmit', function (response) {
  // Add your code here
});

For scenarios 2 and 3 we can test the type of response we get from the data source. The response we receive contains the following two properties:

• formData – the data that we previously sent.
• result – the result. If the data save was successful, the result will contain information relating to the save (eg, data source ID and row ID). However if the device is offline then the result will contain a property called status that will say “queued”.

Below are two examples of the structure of the response. The first response is a successful save and the second is an example of a queued response.

// Successfully sent and saved
{
  formData: {
    'Question 1': 'My answer',
    'Email input': 'hugo@understandesign.com',
    'Star rating': '4',
    'Date picker': '2020-03-27'
  },
  result: {
    id: 14273660,
    data: {
      'Question 1': 'My answer',
      'Date picker': '2020-03-27',
      'Email input': 'hugo@understandesign.com',
      'Star rating': '4'
    },
    dataSourceId: 197784,
    updatedAt: '2020-03-27T12:19:03.433Z',
    createdAt: '2020-03-27T12:19:03.345Z',
    deletedAt: null,
    order: null
  }
}

// Queued to be sent once the device get online
{
  formData: {
    'Question 1': 'My answer',
    'Email input': 'hugo@understandesign.com',
    'Star rating': '4',
    'Date picker': '2020-03-27'
  },
  result: [
    {
      status: 'queued',
      createdAt: 1585311753199
    }
  ]
}

Below is a more detailed example where we are checking the submitted data against the correct answer (in this case it’s “Technology”) and giving the user a score. If correct, the user gets a score of 5. If almost correct (eg “Tech”) the user gets a score of 2. After doing this we redirect the user to a new screen using Fliplet.Navigate.screen(). The ID of the screen we are going to is ‘123’ and we pass that screen the score in a URL query.

Fliplet.Hooks.on('afterFormSubmit', function (response) {
  var formData = response.formData;
  var correctAnswer = 5;
  var almostCorrectAnswer = 2;
  var totalScore = 0;

  // Check for correct answers
  if (formData['form-field-name'] === 'Technology') {
    totalScore += correctAnswer;
  } else if (formData['form-field-name'] === 'Tech') {
    totalScore += almostCorrectAnswer;
  }

  // Redirect to another screen with the totalScore query
  Fliplet.Navigate.screen(123, {
    query: '?totalScore=' + totalScore
  });
});

On the new screen we can access the score by including the following javascript:

var query = Fliplet.Navigate.query;

// Access the score with query.totalScore
var totalScore = query.totalScore;

The variable query will be an Object that will contain the totalScore value along with any others that you’ve passed. You can then access them with query.totalScore.