Sending Data

KS
Last updated 2 months 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.

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 camel-cased keys 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 be add logic before and after form submission.

willSendData

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

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

willSendData will receive a single argument, an object containing the serialized key-value pairs from your form. Forms are not currently distinguished, so if you have multiple forms you must inspect the 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. You must return a JSON object, a Promise that resolves with a JSON object, 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

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: { 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>