diff --git a/README.md b/README.md new file mode 100644 index 0000000..4439fa3 --- /dev/null +++ b/README.md @@ -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)