☰
Trongate MX
Documentation

Help Improve Our Docs

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.

» » »
Attaching DOM Values To Requests

Attaching DOM Values To Requests

The mx-dom-vals attribute in Trongate MX enables you to dynamically attach values from DOM elements to your HTTP requests. This powerful feature allows you to capture and transmit information from specific elements on your page, such as text content or input values.

Syntax

The mx-dom-vals attribute requires a JSON object where each key represents a parameter name and the value is an object containing two properties:

  • selector: A CSS selector that identifies the target element.
  • property: The element property to capture (e.g., innerText, value, innerHTML).

Basic Example

Using Trongate's form helper functions:

Pure HTML equivalent:

When clicked, this button will:

  • Find the first <h1> element on the page.
  • Capture its outer HTML (including the h1 tags).
  • Send this value to the server as a parameter named "headline".

Real-World Examples

Example 1: Capturing Paragraph Text

Using Trongate's form helper functions:

Pure HTML equivalent:

Example 2: Using json_encode with PHP Arrays

Using Trongate's form helper functions:

Pure HTML equivalent:

Example 3: Capturing Multiple Elements

Using Trongate's form helper functions:

Pure HTML equivalent:

Available Properties

You can use any of these properties in your mx-dom-vals:

  • value: Gets the current value (best for form inputs).
  • innerText: Gets the text content only.
  • innerHTML: Gets the HTML content inside the element.
  • outerHTML: Gets the entire element including its HTML tags.

Server-Side Handling

The captured values are accessible in your controller using the post() function:

  1. Use Specific Selectors
    • Prefer IDs and unique class names.
    • Avoid relying on element position or order.
  2. Choose Appropriate Properties
    • Use value for form inputs.
    • Use innerText for capturing text content.
    • Use innerHTML when HTML markup is needed.
  3. Validation
    • Always validate captured values server-side.
    • Don't trust DOM values for critical operations.
    • Apply appropriate sanitization for HTML content.

Common Pitfalls

  • Invalid selectors will cause the value to be omitted.
  • Missing elements will be silently ignored.
  • Malformed JSON will prevent all values from being captured.
  • GET requests do not support mx-dom-vals.

Summary

The mx-dom-vals attribute provides a powerful way to capture and transmit DOM values with your HTTP requests. By using specific selectors and appropriate properties, you can easily include dynamic page content in your form submissions. Remember to use json_encode() when working with complex values and always validate the captured data server-side.

×