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