Subform JavaScript events

[Fedik]

User description

PR for:

• [6.1] Subform: add order-changed event joomla-cms#46093

Also added info about existing events.

---

PR Type

Documentation

---

Description

• Documents JavaScript events for subform field interactions

• Describes five events: subform-row-add, joomla:updated, subform-row-remove, joomla:removed, subform-order-changed

• Clarifies event targets and CustomEvent detail properties

• Notes that all events bubble up in DOM

---

Diagram Walkthrough

flowchart LR
  A["Subform Field"] -->|"row added"| B["subform-row-add event"]
  A -->|"row added"| C["joomla:updated event"]
  A -->|"row removed"| D["subform-row-remove event"]
  A -->|"row removed"| E["joomla:removed event"]
  A -->|"order changed"| F["subform-order-changed event"]
  B -->|"bubbles up"| G["DOM"]
  C -->|"bubbles up"| G
  D -->|"bubbles up"| G
  E -->|"bubbles up"| G
  F -->|"bubbles up"| G

Loading

File Walkthrough

Relevant files

Documentation

subform.md Add comprehensive subform field events documentation          docs/general-concepts/forms-fields/standard-fields/subform.md Added new "Events" section documenting five JavaScript events Documented subform-row-add, joomla:updated, subform-row-remove, joomla:removed events Documented subform-order-changed event with detail properties (row, fromPosition, toPosition) Noted that all events bubble up in DOM +10/-0    new-features.md Document new subform-order-changed event feature                  migrations/60-61/new-features.md Added new section documenting subform-order-changed event feature Referenced PR #46093 as the source of this new event +5/-0

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Clarify redundant subform add/remove events The documentation introduces paired events for adding and removing subform rows (subform-row-add/joomla:updated and subform-row-remove/joomla:removed). This could be confusing; the documentation should clarify the relationship between these events and provide guidance on their intended use cases. Examples: docs/general-concepts/forms-fields/standard-fields/subform.md [153-156] - `subform-row-add` Event dispatched after new row has been added. Target: subform element. CustomEvent detail property contain affected row: `detail.row`. - `joomla:updated` Event dispatched after new row has been added. Target: affected row element. - `subform-row-remove` Event dispatched before removing the row. Target: subform element. CustomEvent detail property contain affected row: `detail.row`. - `joomla:removed` Event dispatched before removing the row. Target: affected row element. Solution Walkthrough: Before: - `subform-row-add` Event dispatched after new row has been added. Target: subform element. CustomEvent detail property contain affected row: `detail.row`. - `joomla:updated` Event dispatched after new row has been added. Target: affected row element. - `subform-row-remove` Event dispatched before removing the row. Target: subform element. CustomEvent detail property contain affected row: `detail.row`. - `joomla:removed` Event dispatched before removing the row. Target: affected row element. ... All events are bubbles up in DOM. After: When a row is added, two events are fired: - `subform-row-add`: Fired on the main subform element. Use this when you need to react to any row addition within the subform. The added row is in `event.detail.row`. - `joomla:updated`: Fired on the newly added row element itself. This is a more generic Joomla event. Similarly, when a row is removed: - `subform-row-remove`: Fired on the main subform element. The row to be removed is in `event.detail.row`. - `joomla:removed`: Fired on the row element that is about to be removed. **Guidance:** Prefer using the `subform-row-*` events for subform-specific logic as they are more explicit and provide context via `event.detail`. Both event types bubble up the DOM. Suggestion importance[1-10]: 7 __ Why: The suggestion correctly identifies a potential point of confusion in the new documentation regarding paired events and proposes a valuable clarification that would significantly improve usability for developers.	Medium
General	Fix detail property grammar Correct the grammar in the CustomEvent detail property description. docs/general-concepts/forms-fields/standard-fields/subform.md [153] -CustomEvent detail property contain affected row: `detail.row`. +CustomEvent `detail` property contains the affected row (`detail.row`). [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies and fixes a grammatical error ("contain" to "contains") in the documentation, which improves its quality and professionalism.	Low
	Fix event bubbling grammar Correct the grammar in the sentence describing DOM event bubbling. docs/general-concepts/forms-fields/standard-fields/subform.md [159] -All events are bubbles up in DOM. +All events bubble up in the DOM. Apply / Chat Suggestion importance[1-10]: 4 __ Why: The suggestion corrects a grammatical error ("are bubbles up" to "bubble up"), improving the clarity and correctness of the documentation.	Low
More