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.
Modal Form Workflows
Modal form workflows represent the pinnacle of Trongate MX's capabilities, combining dynamic modal creation, form validation, loading states, and success feedback into seamless user experiences. This page demonstrates how to create sophisticated modal-based interfaces that feel professional and responsive.
The Complete Modal Form Pattern
The most elegant pattern in Trongate MX combines all the features we've learned into a single, cohesive workflow. Here's a complete example that showcases this integration:
Modal Trigger Button
The code below could be added to any view file. It will produce a button that, when clicked, will render a dynamic modal element. Have a click and try it for yourself!
NOTE: The modal body will contain a spinner element.
This example uses Font Awesome 4 to render a 'settings' icon. Obviously, you don't need to use Font Awesome 4. However, if you would like to try using Font Awesome 4, including the following code within the 'HEAD' section of your webpage:
Clicking the button dynamically generates a modal element. However, the contents of the modal body initially contain a spinner element while the form content is being loaded.
The spinner element provides immediate visual feedback - even before the form content arrives from the server.
Controller Method for Form Content
The button's mx-get attribute sends a request to settings/draw_form. This controller method is responsible for gathering the necessary data and rendering the form that will appear inside the modal body:
Notice how this method follows standard Trongate automatic routing patterns - it fetches data from the model, prepares it for the view, and then loads a view file. The only difference is that the rendered HTML will appear inside a modal instead of a full page.
Modal Form View
The settings_form view file contains the actual form that users will interact with. This form includes all the Trongate MX attributes needed for validation, success animations, and automatic modal closing:
Key features of this form:
id="settings-form"allows the footer submit button to control this formclass="highlight-errors"enables automatic validation error displaymx-animate-success="true"shows a green checkmark on successful submissionmx-close-on-success="true"automatically closes the modal after the success animation
By adding a valid endpoint URL with a corresponding view file content, your dynamically generated modal should now contain a form (or whatever you'd like to have contained inside the modal body).
Here's an example and please do have a click to see the kind of result you can expect to see...
Form Submission Handler
When the form is submitted, a POST request gets sent the endpoint specified by $form_location. This invokes a controller method that handles validation and processing using familiar Trongate form handling patterns:
This controller method demonstrates the two-path approach:
- Validation fails:
validation_errors(400)sends error details back to the modal, which displays them inline - Validation succeeds: Data is processed and a success message is returned, triggering the success animation and modal closure
Here's a fully working example:
Top tip! When you test the button above, try submitting the form with an empty 'Notification Email' field, so that you can see how validation errors are handled.
How This Pattern Works
This complete workflow demonstrates several key features working together in perfect harmony:
- Modal Creation: The button uses
mx-build-modalto create a modal with custom header and footer - Content Loading: The modal body is populated via
mx-getrequest to load the form, with a spinner shown during loading - Form Integration: The form includes validation, success animation, and automatic modal closing
- User Experience: Success animations provide feedback before the modal closes automatically, while validation errors keep the modal open for corrections
The Beauty of This Pattern: Users get immediate feedback at every step - a loading spinner while content loads, inline validation errors if something's wrong, a success animation when everything works, and automatic cleanup when done. All of this happens without a single page reload or custom JavaScript!
Validation Error Handling in Modals
When validation errors occur, the modal remains open and displays errors inline, allowing users to correct their input without losing context. The rendering of validation errors is automatic and the entire process will work with any normal and valid form. For example:
The corresponding validation handler follows the same pattern:
Modal Footer Integration: Notice how the modal footer contains a submit button with a form property that has been assigned with the same value as the form id property. This associates the button with the form inside the modal body, allowing the submit button to be outside the actual form element. This pattern provides maximum flexibility in modal design while maintaining clean separation between the modal structure and form content.
Modal Form Best Practices:
- Always include
mx-close-on-success="true"for successful form submissions - Use
mx-animate-success="true"to provide visual feedback before closing - Include the
highlight-errorsclass for automatic validation error display - Use modal footers to keep important actions visible and accessible
- Combine loading indicators with modal forms for professional user experiences
- Always validate form data server-side using Trongate's validation class
- To dynamically update page content after successful form submission, consider using the mx-on-success attribute or the mx-after-swap attribute.
Alternative Form Handling Strategies
While the complete modal form pattern demonstrated above represents the most comprehensive approach, Trongate MX provides several additional attributes that can enhance form handling workflows in different scenarios. These attributes offer alternative strategies for managing form validation feedback, error handling, and post-submission workflows.
Enhanced Validation and Error Handling
- mx-after-validation - Executes custom JavaScript functions immediately after form validation errors are displayed, allowing you to implement custom error handling logic, focus management, or additional user interface updates.
- mx-animate-error - Triggers visual error animations when form submissions fail (HTTP response codes 400-599), providing immediate visual feedback to users without requiring custom JavaScript.
- mx-close-on-error - Automatically closes modal dialogs when form submissions encounter errors, useful for scenarios where you want to redirect users away from the modal context on validation failures.
- mx-on-error - Specifies elements to initialize or update after failed form submissions, enabling you to display error messages in specific page locations or trigger error-specific workflows.
Alternative Success Workflows
- mx-redirect-on-success - Automatically redirects users to different URLs after successful form submissions, perfect for multi-step workflows or when you need to navigate users to confirmation pages instead of staying in the current context.
- mx-redirect-on-error - Redirects users to error-specific pages when form submissions fail, useful for handling authentication errors, permission issues, or other scenarios requiring full page navigation.
Combining Strategies
These attributes can be mixed and matched to create sophisticated form handling workflows:
This approach provides multiple fallback strategies: inline validation errors with custom handling, success animations followed by redirection, and specific error content updates - all without writing complex JavaScript event handlers.
Summary
Modal form workflows represent the sophisticated culmination of Trongate MX's capabilities. By combining dynamic modal creation, form validation, loading states, and success feedback, you can create professional user interfaces that feel responsive and polished. These patterns eliminate the need for complex JavaScript while providing users with modern, intuitive experiences that rival any contemporary web application.