If you’ve found an error, spotted something missing, or feel a section could be clearer or better explained, we’d love to hear from you. Your feedback helps keep the documentation accurate and useful for everyone.
Please report issues or suggest improvements on GitHub. Community input is invaluable in making the docs stronger.
Not comfortable with GitHub? No problem — you can also get in touch with us directly via our contact form. We welcome all feedback.
Handling Request Errors
The mx-on-error attribute in Trongate MX lets you specify which elements should
update or reinitialise when an AJAX request fails. It offers a means of handling errors
gracefully and keeping your users informed when things don't go quite as planned.
The mx-on-error attribute (which happens to be the focus of this page) is designed for triggering elements, not for executing custom JavaScript!
To execute your own custom JavaScript code after an HTTP request, use the mx-after-swap attribute. You can find the relevant documentation here.
Syntax
Use a CSS selector as the value of mx-on-error. This tells Trongate MX which
element should be updated or reinitialised after a request fails.
How It Works
When Trongate MX encounters a failed AJAX request, here's what happens:
- It checks if the triggering element has an
mx-on-errorattribute. - If it does, the framework finds the target element using your CSS selector.
- Page load events tied to the target element are triggered, reinitialising it.
This makes it easy to display error messages or trigger fallback options when things go wrong.
Example
The code sample below demonstrates a form that posts data to an API endpoint. When something goes wrong, an error message is fetched from the url api/get_error_details and the message is displayed within a <div> that has an id of 'error-message'.
Usually, if a form is submitted - and something goes wrong - it'll be appropriate to display form validation errors. That's not what's happening here!
In our example, the assumption is that we have a more sophistated error message to display when things go wrong. For example, let's imagine a user is enrolling to join a course. Let's further assume that - at the last moment - somebody else has enrolled and there are no more spaces left!
As complicated as it may seem, this is precisely the kind of situation where a more sophisticated error message would be appropriate (as opposed to just a form validation error).
In the error message, we might explain that there are no more spaces left and we may wish to give the user an opportunity to join a waiting list so that they can be kept informed of future courses or even cancellations.
For information on how to render form validation errors with Trongate MX, click here.
The code sample above uses pure HTML. Below is a more secure solution that uses Trongate's form helper functions:
What's Happening?
- If the form submission fails, the
mx-on-error="#error-message"attribute kicks in. - This triggers the
#error-messageelement. - Since
#error-messagehasmx-getandmx-trigger="activate", it fetches and displays the error details.
You might notice we're using a hash ('#') symbol in the form_open() function. This is because the mx-post attribute takes care of the form's destination and method.
Consider using in combination with mx-trigger="activate". Without this attribute, the element may respond to both user events AND programmatic triggers, which might not be what you want. For more information on this topic, refer to our documentation on Triggers in Trongate MX.
Error Handling with Out-of-Band Swaps
When using mx-target="none" with out-of-band swaps, you can still utilize mx-on-error to handle request failures gracefully.
In this example, if the request to api/dashboard_data fails, the #dashboard-error element will be activated. It will then fetch an error message from api/error_message and display it to the user.
This pattern is particularly useful for real-time dashboards and polling scenarios where you need to gracefully handle intermittent API failures without disrupting the entire user interface.
Things to Keep in Mind
mx-on-erroronly works for client-side handling of failed AJAX requests.- It won't affect elements during the initial page load.
- You can target multiple elements by separating selectors with spaces (e.g., "#error-message #status-panel #notification-area").