Velo Tutorial: Processing User Input Before it is Stored in a Collection with Data Hooks

Sometimes you want to validate, alter, or otherwise manipulate user input that you collect using a form before it is stored in your collection. To do so, you can create a data hook that intercepts newly created items before they are stored in your collection. Then you can change the item any way you like and that changed item will be what is added to your collection.

To demonstrate this concept we use an example of a real estate site that has an inquiry form. Users will fill out the form to submit their information. Before the user data is saved in a collection, we will use a hook to format some of the data and add some information to the new item if certain conditions are met.

Prerequisites

This article assumes you are familiar with creating database collections and user input forms. You also might want to read more about data hooks before continuing.

Collection

We begin by creating a database collection that stores the information users submit using a form. Since we are using the collection to store user input, we set its permissions using the Form Submission preset. 

For our example, we call our collection PotentialClients and it has the following fields:

• First Name - Text
• Last Name - Text
• Email - Text
• Phone - Text
• Type -Text (Value will be "Buy" or "Rent")
• Bedrooms - Number
• Bathrooms - Number
• Price - Number
• Priority - Boolean

Input Form

The next step is to create a user input form. Because a hook will be used to modify the collection item that is created when a user submits the form, the fields in the form do not need to exactly match the items in the collection. 

In our example, we use the following form:

The form contains input elements that match almost all of the fields in the PotentialClients collection. Notice that there is no input element that corresponds to the Priority field. That is because the value for the Priority field will be set in the hook that gets called with a user submits the form.

Hook

The final step is to create a hook that modifies the newly created item before it gets inserted into the collection. The beforeInsert hook is triggered when a new item is being inserted into a collection. The hook receives the item that is about to be inserted. In the hook's code, you can modify that item any way you like or create a totally new item. When you're done, you return the modified or new item. That returned item is inserted into the collection instead of the item that the hook received.

The code for hooks is written in the data.js file in the Code Files, Backend section of your site. To learn more about creating hooks, see How to Use Data Hooks.

In our example, the following beforeInsert hook does two things:

• Formats the first and last names so that regardless of how users type their names they:
  • Start with a capital letter. 
  • The rest of the letters are lowercase.
• Checks to see if the potential client is a priority client or not and sets the priority field accordingly.

Let's take a look at the code one piece at a time.

On line 1, we begin the hook function definition. Hook functions are named with the following convention: <collectionName>_<hookType>. So our hook is named PotentialClients_beforeInsert.

On lines 2-3, the hook takes the first and last names and formats them using the toUpperFirst() function imported above.

On lines 5-7, the hook checks the values of the price and type properties. If the potential client is looking to buy a property over $1,000,000, the item in the collection will be marked as a priority item.

Finally, on line 9, the hook returns the modified item. That means the item inserted into the collection will have the formatted names and the priority field set correctly.