Add comprehensive README documentation
- Feature overview - Installation instructions - Usage guide - Technical architecture details - Troubleshooting section - Customization examples 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
shopkeeperdev
256
README.md
Normal file
256
README.md
Normal file
@@ -0,0 +1,256 @@
|
|||||||
|
# Shopkeeper Order Items Custom
|
||||||
|
|
||||||
|
A Magento 2 module that customizes the order item columns in the Magento admin panel. This module removes tax columns, adds a cost column, and makes product names and SKUs clickable for quick product editing.
|
||||||
|
|
||||||
|
## Features
|
||||||
|
|
||||||
|
- **Remove Tax Columns**: Hides tax amount and tax percent columns from order item view
|
||||||
|
- **Add Cost Column**: Displays product cost alongside price for profitability analysis
|
||||||
|
- **Clickable Product Links**: Product names and SKUs link directly to product edit page
|
||||||
|
- **Clean Admin Interface**: Streamlined order view focusing on essential information
|
||||||
|
- **Security**: Properly escapes HTML output to prevent XSS vulnerabilities
|
||||||
|
|
||||||
|
## What It Does
|
||||||
|
|
||||||
|
### Column Modifications
|
||||||
|
|
||||||
|
**Removed Columns:**
|
||||||
|
- Tax Amount
|
||||||
|
- Tax Percent
|
||||||
|
|
||||||
|
**Added Columns:**
|
||||||
|
- **Cost** - Displays the product's cost attribute (positioned after price column)
|
||||||
|
|
||||||
|
### Interactive Features
|
||||||
|
|
||||||
|
- **Product Name**: Clickable link to product edit page (opens in new tab)
|
||||||
|
- **SKU**: Clickable link to product edit page (opens in new tab)
|
||||||
|
- Both links show "Edit Product" tooltip on hover
|
||||||
|
|
||||||
|
### Cost Display
|
||||||
|
|
||||||
|
- Fetches product cost from catalog
|
||||||
|
- Formats currency using order's currency settings
|
||||||
|
- Displays "N/A" if:
|
||||||
|
- Cost attribute is not set
|
||||||
|
- Product no longer exists
|
||||||
|
- Cost data is unavailable
|
||||||
|
|
||||||
|
## Installation
|
||||||
|
|
||||||
|
### Via Composer
|
||||||
|
|
||||||
|
Add the repository to your Magento project's `composer.json`:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"repositories": {
|
||||||
|
"module-order-items-custom": {
|
||||||
|
"type": "vcs",
|
||||||
|
"url": "https://code.shopkeeper.dev/McQueen/module-order-items-custom.git"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Then install:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
composer require shopkeeper/module-order-items-custom:dev-main
|
||||||
|
php bin/magento module:enable Shopkeeper_OrderItemsCustom
|
||||||
|
php bin/magento setup:upgrade
|
||||||
|
php bin/magento setup:di:compile
|
||||||
|
php bin/magento cache:flush
|
||||||
|
```
|
||||||
|
|
||||||
|
### Manual Installation
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# From your Magento root directory
|
||||||
|
mkdir -p app/code/Shopkeeper/OrderItemsCustom
|
||||||
|
# Upload all module files to app/code/Shopkeeper/OrderItemsCustom/
|
||||||
|
|
||||||
|
php bin/magento module:enable Shopkeeper_OrderItemsCustom
|
||||||
|
php bin/magento setup:upgrade
|
||||||
|
php bin/magento setup:di:compile
|
||||||
|
php bin/magento cache:flush
|
||||||
|
```
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
After installation, the changes are automatically applied to all order views in the admin panel.
|
||||||
|
|
||||||
|
### Viewing Orders
|
||||||
|
|
||||||
|
1. Go to **Sales > Orders**
|
||||||
|
2. Open any order
|
||||||
|
3. Scroll to the **Items Ordered** section
|
||||||
|
|
||||||
|
You'll see:
|
||||||
|
- No tax columns
|
||||||
|
- A new "Cost" column showing product costs
|
||||||
|
- Clickable product names and SKUs that open the product edit page
|
||||||
|
|
||||||
|
### Analyzing Profitability
|
||||||
|
|
||||||
|
With both Price and Cost visible side-by-side, you can quickly:
|
||||||
|
- Calculate profit margins
|
||||||
|
- Identify high-margin products
|
||||||
|
- Review cost accuracy for ordered items
|
||||||
|
|
||||||
|
## Requirements
|
||||||
|
|
||||||
|
- Magento 2.4.x (or 2.3.x with compatible framework versions)
|
||||||
|
- PHP 7.4, 8.1, 8.2, or 8.3
|
||||||
|
- Product cost attribute configured in Magento
|
||||||
|
|
||||||
|
## Technical Details
|
||||||
|
|
||||||
|
### Plugin Architecture
|
||||||
|
|
||||||
|
The module uses Magento's plugin system (interceptors) to modify:
|
||||||
|
|
||||||
|
1. **Magento\Sales\Block\Adminhtml\Order\View\Items**
|
||||||
|
- Plugin: `ItemsColumns`
|
||||||
|
- Removes tax columns
|
||||||
|
- Adds cost column definition
|
||||||
|
|
||||||
|
2. **Magento\Sales\Block\Adminhtml\Order\View\Items\Renderer\DefaultRenderer**
|
||||||
|
- Plugin: `DefaultRenderer`
|
||||||
|
- Renders cost column with formatted values
|
||||||
|
- Adds clickable links to product names and SKUs
|
||||||
|
- Handles missing products gracefully
|
||||||
|
|
||||||
|
### Module Structure
|
||||||
|
|
||||||
|
```
|
||||||
|
Shopkeeper/OrderItemsCustom/
|
||||||
|
├── Plugin/
|
||||||
|
│ └── Order/
|
||||||
|
│ └── View/
|
||||||
|
│ ├── ItemsColumns.php
|
||||||
|
│ └── Items/
|
||||||
|
│ └── Renderer/
|
||||||
|
│ └── DefaultRenderer.php
|
||||||
|
├── etc/
|
||||||
|
│ ├── di.xml
|
||||||
|
│ └── module.xml
|
||||||
|
├── composer.json
|
||||||
|
└── registration.php
|
||||||
|
```
|
||||||
|
|
||||||
|
### Cost Attribute
|
||||||
|
|
||||||
|
The module expects a product attribute with code `cost`. To configure:
|
||||||
|
|
||||||
|
1. Go to **Stores > Attributes > Product**
|
||||||
|
2. Ensure "cost" attribute exists
|
||||||
|
3. Set costs for your products via:
|
||||||
|
- Bulk import
|
||||||
|
- Individual product edit pages
|
||||||
|
- API updates
|
||||||
|
|
||||||
|
## Troubleshooting
|
||||||
|
|
||||||
|
### Cost shows "N/A" for all products
|
||||||
|
|
||||||
|
**Possible causes:**
|
||||||
|
1. Cost attribute not configured
|
||||||
|
2. Cost values not set for products
|
||||||
|
3. Permissions issue accessing product data
|
||||||
|
|
||||||
|
**Solutions:**
|
||||||
|
```bash
|
||||||
|
# Verify cost attribute exists
|
||||||
|
php bin/magento catalog:product:attributes:list | grep cost
|
||||||
|
|
||||||
|
# Reindex if needed
|
||||||
|
php bin/magento indexer:reindex
|
||||||
|
|
||||||
|
# Check product has cost value
|
||||||
|
# Go to Catalog > Products > Edit Product > Advanced Pricing
|
||||||
|
```
|
||||||
|
|
||||||
|
### Links not working
|
||||||
|
|
||||||
|
1. **Clear cache:**
|
||||||
|
```bash
|
||||||
|
php bin/magento cache:flush
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Check admin permissions:**
|
||||||
|
- Ensure your admin role has access to edit products
|
||||||
|
|
||||||
|
3. **Verify module is enabled:**
|
||||||
|
```bash
|
||||||
|
php bin/magento module:status Shopkeeper_OrderItemsCustom
|
||||||
|
```
|
||||||
|
|
||||||
|
### Tax columns still showing
|
||||||
|
|
||||||
|
1. **Clear generated code:**
|
||||||
|
```bash
|
||||||
|
rm -rf generated/code/*
|
||||||
|
php bin/magento setup:di:compile
|
||||||
|
```
|
||||||
|
|
||||||
|
2. **Clear cache:**
|
||||||
|
```bash
|
||||||
|
php bin/magento cache:flush
|
||||||
|
```
|
||||||
|
|
||||||
|
## Customization
|
||||||
|
|
||||||
|
### Removing Different Columns
|
||||||
|
|
||||||
|
To remove other columns, edit `Plugin/Order/View/ItemsColumns.php`:
|
||||||
|
|
||||||
|
```php
|
||||||
|
// Add to the $excludedColumns array
|
||||||
|
$excludedColumns = [
|
||||||
|
'tax-amount',
|
||||||
|
'tax-percent',
|
||||||
|
'discount-amount', // Add this line to remove discount column
|
||||||
|
];
|
||||||
|
```
|
||||||
|
|
||||||
|
### Adding Different Columns
|
||||||
|
|
||||||
|
To add more columns, modify the same file:
|
||||||
|
|
||||||
|
```php
|
||||||
|
$columns = $result->setData([
|
||||||
|
// ... existing columns ...
|
||||||
|
'your-column-name' => [
|
||||||
|
'label' => __('Your Column Label'),
|
||||||
|
],
|
||||||
|
]);
|
||||||
|
```
|
||||||
|
|
||||||
|
Then implement rendering in `Plugin/Order/View/Items/Renderer/DefaultRenderer.php`.
|
||||||
|
|
||||||
|
## Compatibility
|
||||||
|
|
||||||
|
- Magento Open Source 2.3.x, 2.4.x
|
||||||
|
- Magento Commerce 2.3.x, 2.4.x
|
||||||
|
- PHP 7.4, 8.1, 8.2, 8.3
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
For issues or questions:
|
||||||
|
1. Check Magento logs: `var/log/system.log`
|
||||||
|
2. Verify module status: `php bin/magento module:status`
|
||||||
|
3. Ensure cost attribute is configured
|
||||||
|
4. Clear cache and recompile
|
||||||
|
|
||||||
|
## License
|
||||||
|
|
||||||
|
OSL-3.0, AFL-3.0
|
||||||
|
|
||||||
|
## Version
|
||||||
|
|
||||||
|
1.0.0
|
||||||
|
|
||||||
|
## Author
|
||||||
|
|
||||||
|
Shopkeeper (taber@shopkeeper.dev)
|
||||||
Reference in New Issue
Block a user