return to Table of Contents, Subscribe Forms

Advanced subscribe form customization

If you have embedded a subscribe form on your website (using the embed code generated for you by Direct Mail) and are proficient in JavaScript, you can customize the behavior of the form in the following ways:

  • Change the default button label from "Subscribe" to a label of your choosing
  • Provide custom form validation logic before the form is submitted
  • Provide a custom callback to be invoked when the user subscribes
  • Provide a custom callback to be invoked when there is an error submitting the subscribe form

You can also enable a special test mode that may come in handy while integrating your customizations.

Custom Subscribe Button Label

If you would like to customize the label of the "Subscribe" button, add a data-loc-subscribe attribute to the <form> element and set the value of the attribute to the label you'd like to use (e.g. "Send"). You can also customize the label of the button that appears after the form has been submitted successfully. To do so, add a data-loc-subscribed attribute.

Example:

<form method="post" action="https://..." data-loc-subscribe="Send" data-loc-subscribed="Sent!"...>
...
</form>

Custom Form Validation

If you would like to run your own form validation code before the form is submitted, add a data-validate attribute to the <form> element and set the value of that attribute to the name of your validation function. Your validation function will be passed the subscribe form's DOM element and should return true if the form validates, and false otherwise.

Example:

<form method="post" action="https://..." data-validate="myValidate"...>
...
</form>

<script type="text/javascript">
function myValidate( form )
{
    // Perform validation (like checking for valid email address)
    return true;
}
</script>

Custom Success Callback

If you would like to run your own code when the user successfully subscribes, add a data-callback attribute to the <form> element and set the value of that attribute to the name of your callback function. Your callback function will be passed the subscribe form's DOM element. Your callback function should return false if it does not want the default subscribe form success behavior (which currently is simply setting the name of the subscribe button to "Subscribed").

Example:

<form method="post" action="https://..." data-callback="mySubscribeSuccess"...>
...
</form>

<script type="text/javascript">
function mySubscribeSuccess( form )
{
    alert( "You are subscribed!" );
    return false;
}
</script>

Custom Error Callback

If you would like to run your own code when form submission fails, add a data-errback attribute to the <form> element and set the value of that attribute to the name of your callback function. Your callback function will be passed the subscribe form's DOM element, a string with the failure status (one of "error", "timeout", "abort", "parsererror"), an error code, and a human-readable error message. Your callback function should return false if it does not want the default subscribe form error-handling behavior (which currently to show an alert with the human-readable error message).

Example:

<form method="post" action="https://..." data-errback="mySubscribeError"...>
...
</form>

<script type="text/javascript">
function mySubscribeError( form, textStatus, errCode, errMsg )
{
    alert( "Error: " + errMsg );
    return false;
}
</script>

Test Mode

You may find it useful to enable test mode while integration your custom validation or callback functions. When in test mode, the subscribe form requests will not be sent over the network, but your custom validation, success, and error functions will still be invoked (if defined).

To enable test mode, add a data-test-mode attribute to the <form> element and set the value of that attribute to either "success" or "error".

Example:

<form method="post" action="https://..." data-test-mode="success"...>

Did you find this article helpful? Yes | No