 |
VOOZH | about |
|
VOOZH | about |
This page documents the Grid and Form components used in Maho's admin interface. These components provide the foundation for displaying data tables (grids) and collecting user input (forms) throughout the backend. The grid system handles tabular data display with filtering, sorting, pagination, and mass actions. The form system manages input fields, validation, dependencies, and dynamic behaviors. Both systems are built on a combination of server-side PHP blocks and client-side JavaScript controllers.
The grid system displays collections of data in a tabular format. While the layout and columns are defined in PHP, the interactivity is driven by specialized JavaScript utilities.
The following diagram maps the relationship between the PHP Block classes and the JavaScript entities that manage the Grid UI.
Sources: app/code/core/Mage/Adminhtml/Block/Widget/Grid.php17-42 app/code/core/Mage/Adminhtml/Block/Widget/Grid.php243-272 public/js/mage/adminhtml/grid.js10-37
The primary class for grids is Mage_Adminhtml_Block_Widget_Grid. Developers override _prepareCollection() to define the data source and _prepareColumns() to define the table structure.
| Method | Role | File Reference |
|---|---|---|
addColumn() | Defines a column with header, index, and type | app/code/core/Mage/Adminhtml/Block/Widget/Grid.php431-440 |
_prepareCollection() | Loads the resource model and sets it to the block | app/code/core/Mage/Adminhtml/Block/Sales/Order/Grid.php40-45 |
addExportType() | Adds options for CSV or Excel export | app/code/core/Mage/Adminhtml/Block/Sales/Order/Grid.php138-139 |
setUseAjax(true) | Enables AJAX-based filtering and pagination | app/code/core/Mage/Adminhtml/Block/Sales/Order/Grid.php23 |
Specific implementations like Mage_Adminhtml_Block_Sales_Order_Grid use _getCollectionClass() to specify the grid collection resource app/code/core/Mage/Adminhtml/Block/Sales/Order/Grid.php34-37 Catalog grids like Mage_Adminhtml_Block_Catalog_Product_Grid handle complex EAV attribute joins within _prepareCollection() to display product names, status, and visibility across different store scopes app/code/core/Mage/Adminhtml/Block/Catalog/Product/Grid.php41-115
Columns are managed by Mage_Adminhtml_Block_Widget_Grid_Column, which delegates rendering to specific renderer classes based on the column type (e.g., date, datetime, number) app/code/core/Mage/Adminhtml/Block/Widget/Grid_Column.php27-32 app/code/core/Mage/Adminhtml/Block/Widget/Grid_Column.php247-250
Sources: app/code/core/Mage/Adminhtml/Block/Widget/Grid.php17-196 app/code/core/Mage/Adminhtml/Block/Sales/Order/Grid.php15-141 app/code/core/Mage/Adminhtml/Block/Catalog/Product/Grid.php41-115 app/code/core/Mage/Adminhtml/Block/Widget/Grid_Column.php240-255
The varienGrid JavaScript class public/js/mage/adminhtml/grid.js10-37 provides the client-side logic for grid functionality. It initializes the grid, handles user interactions, and manages AJAX updates.
Key varienGrid Methods:
| Method | Description | File Reference |
|---|---|---|
constructor(containerId, url, ...) | Initializes the grid with its container ID, base URL, and variable names for pagination/sorting. Binds event listeners. | public/js/mage/adminhtml/grid.js11-37 |
initGrid() | Attaches event listeners to table rows for mouse interactions (mouseover, mouseout, mousedown, click, dblclick) and to column headers for sorting. Calls bindFilterFields() and bindFieldsChange(). | public/js/mage/adminhtml/grid.js38-78 |
initGridAjax() | Re-initializes the grid after an AJAX update, including re-executing scripts within the updated content. | public/js/mage/adminhtml/grid.js79-90 |
doSort(event) | Handles column header clicks to trigger sorting. Updates the URL with sortVar and dirVar and reloads the grid. | public/js/mage/adminhtml/grid.js159-170 |
reload(url) | Performs an AJAX request to update the grid content. It uses mahoFetch to send form data (including form_key) and replaces the grid's HTML with the response. | public/js/mage/adminhtml/grid.js177-219 |
doFilter() | Collects filter values from input fields and reloads the grid via reload(). | public/js/mage/adminhtml/grid.js221-230 |
resetFilter() | Clears all filter input fields and reloads the grid. | public/js/mage/adminhtml/grid.js232-240 |
rowMouseClick(event) | Triggers the rowClickCallback (e.g., openGridRow) and fires a gridRowClick global event. | public/js/mage/adminhtml/grid.js130-148 |
Sources: public/js/mage/adminhtml/grid.js10-240
The form system provides a framework for building admin forms with validation, dependencies, and dynamic behaviors.
This diagram bridges the PHP Block architecture to the JavaScript varienForm implementation.
Sources: app/code/core/Mage/Adminhtml/Block/Widget/Form/Container.php113-120 public/js/mage/adminhtml/form.js10-21
The varienForm class manages client-side form submission and validation. It is instantiated with a form ID and an optional validation URL public/js/mage/adminhtml/form.js11-21
Key Functions:
submit(url): Fires formSubmit event via varienGlobalEvents, resets error sections, validates fields, and performs AJAX validation if a URL is provided public/js/mage/adminhtml/form.js41-56_validate(): Uses mahoFetch to send form data to the server for remote validation public/js/mage/adminhtml/form.js62-72_submit(): Final execution of the native HTML form submit, optionally updating the action URL public/js/mage/adminhtml/form.js88-94checkErrors(): Callback that marks fields and their parent containers (like tabs) with error states via varienElementMethods.setHasError public/js/mage/adminhtml/form.js23-28Sources: public/js/mage/adminhtml/form.js10-95 public/js/mage/adminhtml/events.js80-124
Validation in Maho combines client-side checks with optional server-side AJAX validation.
Sources: public/js/mage/adminhtml/form.js30-82
Maho forms often use tabs. When a field fails validation, the system propagates the error state up to the tab header to alert the user even if the error is on a hidden tab:
setHasError(): Iterates up the DOM tree from the invalid element public/js/mage/adminhtml/form.js135-162statusBar property (assigned during tab creation in varienTabs), that status bar (the tab link) receives the error CSS class public/js/mage/adminhtml/form.js142-149Sources: public/js/mage/adminhtml/form.js135-162 public/js/mage/adminhtml/tabs.js33-34
The varienTabs class handles the navigation and content management of multi-section forms.
destElementId container public/js/mage/adminhtml/tabs.js27-42ajax class load their content on demand using mahoFetch. It handles both HTML responses (rendered into the container) and JSON responses (checking for errors or session expiry) public/js/mage/adminhtml/tabs.js152-171activeTab and fires tabChangeBefore events to allow observers to prevent tab switching if necessary public/js/mage/adminhtml/tabs.js138-145Sources: public/js/mage/adminhtml/tabs.js11-182
Maho supports dynamic field dependencies in the admin interface, most notably in System Configuration and complex entity forms.
In Mage_Adminhtml_Block_System_Config_Form, the system builds a dependency map using _buildDependenceCondition() app/code/core/Mage/Adminhtml/Block/System/Config/Form.php214-215 This map is then passed to a Mage_Adminhtml_Block_Widget_Form_Element_Dependence block app/code/core/Mage/Adminhtml/Block/System_Config_Form.php194-203 which generates the necessary JavaScript to show/hide fields based on the values of other fields.
Sources: app/code/core/Mage/Adminhtml/Block/System/Config/Form.php194-215
Manages the dynamic update of state/province dropdowns based on the selected country public/js/mage/adminhtml/form.js184-196 It handles switching between a <select> element and a text <input> depending on whether region data is available for the chosen country.
Mage_Adminhtml_Block_Widget_Form_Container provides built-in support for navigating between entities (e.g., Previous/Next Order) while viewing a single record. It retrieves the navigation sequence from the session, which is populated when the user interacts with the corresponding grid app/code/core/Mage/Adminhtml/Block/Widget/Form/Container.php60-103
Sources: public/js/mage/adminhtml/form.js184-196 app/code/core/Mage/Adminhtml/Block/Widget/Form/Container.php60-103 app/design/adminhtml/default/default/template/widget/form/container.phtml21-27
Refresh this wiki