Sending Data

KS
Last updated 12 days ago

Learn how to send data to a server from your Mason features.

You can send data to a server by embedding form elements in your Mason feature. Configure your form's HTTP action, method, and fields using the Configure Form tool in the left tool sidebar of the Mason Builder. Your server must accept and respond with application/json.

Input Types

Mason supports inputs of the following type:

  • checkbox

  • email

  • hidden

  • number

  • password

  • tel

  • text

  • url

in addition to select elements, which may contain any value string.

Payload

All forms are submitted from your component asynchronously using window.fetch. For GET requests, form fields will be sent as URL encoded query parameters. For all other methods, form fields will be serialized with the keys matching the name attribute provided in the Mason Builder, and sent with an application/json Content-Type header.

Consider the form below

which will have the following payload when sent via POST

{
email: 'john@appleseed.com',
password: '12345678',
firstName: 'John',
lastName: 'Appleseed'
}

Validation

Mason will abort submission if any required fields are empty. To perform custom validation, use the willSendData callback.

Callbacks

Include willSendData and didReceiveData functions as props on any component that contains forms to add logic before and after form submission. Note that didReceiveData will only be called after a 2XX response - Mason will handle errors.

willSendData

Invoked prior to sending data to the form's action, in response to a user action.

render() {
<Register id="YOUR_COMPONENT_ID" willSendData={(form) => {
const { data: { password } } = form;
if (password && password.length >= 8) {
return form;
}
return false;
}} />
}

willSendData will receive a single argument, an object containing the form action, a headers object, and the form data serialized as key-value pairs from your form.

{
action: 'https://www.example.com/form',
data: {
email: 'janedoe@appleseed.com',
password: 'verysecure',
},
headers: {},
}

You may mutate and return this object, but it should contain the exact same top-level keys. You must return this object - if you don't to modify it simply return it.

Forms are not currently distinguished, so if you have multiple forms you must inspect the action and/or data contents to determine which form is being submitted.

If the data fails validation, return boolean false to abort form submission. You may return modified data, including adding or removing key-value pairs, and the return value will be sent to the server. If you want to send the data as-is, return the data without modification. If you need to perform asynchronous action prior to form submission, return a Promise that resolves with a JSON object matching the required signature, or false.

didReceiveData

Invoked upon 2xx response code receipt from a server in response to a form submission. It will receive a single argument, an object containing the parsed JSON response body.

render() {
<Register id="YOUR_COMPONENT_ID" didReceiveData={(user) => {
//do something with user
return user;
}} />
}

You may modify and return the response.

Callbacks with HTML

If you're embedding your feature as HTML, you cannot pass functions as attributes. Instead, you must use event handlers. The events emitted by Mason features are name-spaced with mason and named the same as the callback functions you provide in React. The data will be provided in the event's detail property.

Because events are immutable, you cannot modify the data to be sent. However, you may abort by returning false from the event handler. Aborting is only possible with the willSendData event.

<mason-register id="register" data-id="YOUR_COMPONENT_ID"></mason-register>
<script type="text/javascript">
const registerNode = document.getElementById('register');
registerNode.addEventListener('mason.willSendData', function(event) {
const { detail: { data: { password } } } = event;
if (password && password.length >= 8) {
return true;
}
return false;
});
registerNode.addEventListener('mason.didReceiveData', function(event) {
const user = event.detail;
//do something with user
}
</script>