Table documentation

[robbiejackson]

User description

Associated pull request for manual-examples is at joomla/manual-examples#48

---

PR Type

Documentation

---

Description

• Add comprehensive Table class documentation covering basic and advanced functionality

• Document checkout/checkin, ACL assets, ordering, publishing, and hits operations

• Include nested set tables implementation for tree structures with CRUD operations

• Provide reflection methods and reserved column names reference guide

---

Diagram Walkthrough

flowchart LR
  A["Table Documentation"] --> B["Basic Operations"]
  A --> C["Advanced Features"]
  A --> D["Nested Sets"]
  B --> B1["CRUD Methods"]
  B --> B2["Instantiation"]
  C --> C1["Checkout/Checkin"]
  C --> C2["ACL Assets"]
  C --> C3["Ordering & Publishing"]
  D --> D1["Tree Structures"]
  D --> D2["Node Operations"]
  D --> D3["Tree Rearrangement"]

Loading

File Walkthrough

Relevant files

Documentation

index.md Table documentation index and overview                                      docs/general-concepts/table/index.md Create index page introducing Joomla Table class and Active Record pattern Overview of basic, advanced, and nested set table functionality Links to related database documentation +17/-0    basic-table.md Basic Table class functionality and CRUD operations            docs/general-concepts/table/basic-table.md Document basic CRUD operations: load, bind, check, store, save, delete Explain table instantiation via MVC Factory and direct instantiation Provide sample module code demonstrating basic table operations Include module installation and usage instructions +198/-0  advanced-table.md Advanced Table class features and asset management              docs/general-concepts/table/advanced-table.md Document checkout/checkin functionality for concurrent edit prevention Explain ACL assets management with getRules and setRules methods Cover ordering operations: getNextOrder, reorder, move Document publish, hits, and reflection methods Include reserved column names table with aliasing support Provide sample module code demonstrating advanced operations +364/-0  nested.md Nested Set Tables for hierarchical tree structures              docs/general-concepts/table/nested.md Explain Nested Set Model implementation for tree structures in Joomla Document tree terminology: nodes, root, children, leaf nodes, levels Cover root node setup and retrieval operations Document tree traversal: getTree, getPath, isLeaf methods Explain node CRUD operations with setLocation positioning Cover publishing state changes and node deletion with child handling Document tree rearrangement: moveByReference, orderUp, orderDown, move +290/-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: 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: 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: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No logging: The PR adds documentation only and no code paths performing critical actions or logging, so audit trail compliance cannot be evaluated from these changes. Referred Code --- title: Advanced Table Functionality sidebar_position: 2 --- This page covers more advanced functionality of the Joomla Table class. The API definitions are at [Joomla Table APIs](cms-api://classes/Joomla-CMS-Table-Table.html). ## Checkout / Checkin Checkout capability avoids the unexpected results which can arise when 2 users edit the same record simultaneously. The Joomla pattern is that whenever a component displays an "edit" form for a selected record (allowing the user to edit the record), then at that time the record is updated to set the `checked_out` field to the userid of the user editing the record, and the `checked_out_time` field to the current date/time. Another user viewing the same record then sees a padlock symbol against the "locked" record and is prevented from editing it. When the user editing the record successfully saves his/her changes, or cancels the edit, then the record is "checked in" by resetting the `checked_out` and `checked_out_time` fields. ### Checkout ... (clipped 343 lines) 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: No errors shown: The changes are documentation text and example snippets without executable error handling, so robustness cannot be assessed from this diff. Referred Code --- title: Basic Table Functionality sidebar_position: 1 --- This page covers basic functionality of the Joomla Table class. The API definitions are at [Joomla Table APIs](cms-api://classes/Joomla-CMS-Table-Table.html). Introduction ============ The Joomla Table class (Joomla\CMS\Table\Table in libraries/src/Table/Table.php) provides a framework which enables you to do CRUD operations (and more) on database tables. The usual case is that you are developing a component with its own database table, and you use the Table class to implement administrator CRUD operations for data in your database table. The Joomla Table class is an abstract class, so you must create your own table class (for your component's database table) which extends the Joomla Table class. ## Instantiating your table class ... (clipped 177 lines) 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: Example input: Documentation references reading parameters like demonote from URL in examples without detailing validation, but as docs this cannot confirm or deny secure handling. Referred Code The basic functionality demonstrates reading a record from the modules table then writing an update back to that record in the database. The modules table contains the module instances which are displayed on the Joomla site or administrator, and you'll find it useful to view the table through phpmyadmin, for example. Some notes on the functionality of this module: - The module record is loaded from the database record and the title of the module is output - The module params is json decoded into an associative array and the header tag is then set to 'h2' (which controls how the header title is displayed in the module on the web page) - The new note to be written to the module record is read from the `demonote` parameter in the URL, so you can set this yourself by adding `?demonote=something` in the URL - The new note and params are written back to the database record using `bind()` and `store()` commands. - The params will be converted back to a json string because of the line `protected $_jsonEncode = array('params');` in our table class Learn more about managing compliance generic rules or creating your own custom rules
Update

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
Possible issue	✅ Fix incorrect method call syntax Suggestion Impact: The commit updated the code examples to call $table->delete($pk, ...) instead of the incorrect $table->($pk, ...). code diff: ```php -$table->($pk, true); // deletes the node identified by $pk, and deletes all of its children as well -$table->($pk, false); // deletes the node identified by $pk, and moves all of its children up a level in the tree +$table->delete($pk, true); // deletes the node identified by $pk, and deletes all of its children as well +$table->delete($pk, false); // deletes the node identified by $pk, and moves all of its children up a level in the tree Add the missing delete method name to the code example for deleting a node. docs/general-concepts/table/nested.md [244-247] ```php -$table->($pk, true); // deletes the node identified by $pk, and deletes all of its children as well -$table->($pk, false); // deletes the node identified by $pk, and moves all of its children up a level in the tree +$table->delete($pk, true); // deletes the node identified by $pk, and deletes all of its children as well +$table->delete($pk, false); // deletes the node identified by $pk, and moves all of its children up a level in the tree `[Suggestion processed]` <details><summary>Suggestion importance[1-10]: 6</summary> __ Why: The suggestion correctly identifies a syntax error in a documentation code example where the `delete` method name is missing, and provides the correct fix. </details></details></td><td align=center>Low </td></tr> <tr><td align="center" colspan="2"> - [ ] Update <!-- /improve_multi --more_suggestions=true --> </td><td></td></tr></tbody></table>