Add comprehensive README documentation

- Installation instructions - Configuration guide - Usage examples - Troubleshooting section - Amasty integration details 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
2025-11-06 15:18:44 -05:00
parent d2c024cfe3
commit 5794fca0bb
1 changed files with 213 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,213 @@
+# Shopkeeper PDFing PO
+
+A Magento 2 module that enables staff to print PDF purchase order documents using Amasty's PDF Customizer templates and Amasty Custom Order Attributes.
+
+## Features
+
+- **PDF Purchase Orders**: Generate professionally formatted PO documents
+- **Amasty Integration**: Leverages Amasty PDF Customizer templates for design flexibility
+- **Custom Attributes**: Incorporates Amasty Custom Order Attributes in PO documents
+- **Admin Interface**: Easy access from order view page
+- **Template Customization**: Use Amasty's visual template editor for PO layout
+
+## Requirements
+
+- Magento 2.4.x
+- PHP 7.4 or higher
+- **Amasty PDF Customizer (Subscription Package)** - Required
+- **Amasty Order Attributes (Subscription Package)** - Required
+
+## Installation
+
+### Via Composer
+
+Add the repository to your Magento project's `composer.json`:
+
+```json
+{
+    "repositories": {
+        "module-pdfing-po": {
+            "type": "vcs",
+            "url": "https://code.shopkeeper.dev/McQueen/module-pdfing-po.git"
+        }
+    }
+}
+```
+
+Then install:
+
+```bash
+composer require shopkeeper/module-pdfing-po:dev-main
+php bin/magento module:enable Shopkeeper_PDFingPO
+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/PDFingPO
+# Upload all module files to app/code/Shopkeeper/PDFingPO/
+
+php bin/magento module:enable Shopkeeper_PDFingPO
+php bin/magento setup:upgrade
+php bin/magento setup:di:compile
+php bin/magento cache:flush
+```
+
+## Configuration
+
+### Step 1: Install Required Modules
+
+Ensure Amasty modules are installed and configured:
+
+```bash
+composer require amasty/module-pdf-customizer-subscription-package
+composer require amasty/module-order-attributes-subscription-package
+```
+
+### Step 2: Configure PDF Template
+
+1. Navigate to **Stores > Amasty Extensions > PDF Customizer**
+2. Create or edit a template for Purchase Orders
+3. Configure the template layout, headers, footers, and content
+4. Include any custom order attributes you want displayed
+
+### Step 3: Module Configuration
+
+Configure the module at:
+**Stores > Configuration > Shopkeeper > PDFing PO**
+
+(If applicable - adjust based on your actual configuration paths)
+
+## Usage
+
+### Printing a Purchase Order
+
+1. Go to **Sales > Orders**
+2. Open any order
+3. Look for the "Print Purchase Order" button (location depends on implementation)
+4. Click to generate and download the PDF
+
+The PDF will be generated using your configured Amasty PDF template and will include:
+- Order details
+- Customer information
+- Product line items
+- Custom order attributes (if configured)
+- Any other elements defined in your Amasty template
+
+## Features & Benefits
+
+### Integration with Amasty PDF Customizer
+
+- Use Amasty's drag-and-drop template builder
+- Professional-looking PO documents
+- Consistent branding across documents
+- Easy template modifications without code changes
+
+### Custom Order Attributes
+
+- Display customer PO numbers
+- Show shipping instructions
+- Include delivery dates
+- Any custom fields defined in Amasty Order Attributes
+
+## Troubleshooting
+
+### PDF not generating
+
+1. **Check Amasty modules are enabled**:
+   ```bash
+   php bin/magento module:status | grep Amasty
+   ```
+
+2. **Verify PDF template exists**:
+   - Go to Stores > Amasty Extensions > PDF Customizer
+   - Ensure at least one template is configured
+
+3. **Check permissions**:
+   ```bash
+   chmod -R 755 var/ pub/ generated/
+   ```
+
+### Custom attributes not showing
+
+1. **Verify attributes are assigned to the order**:
+   - Check order edit page for custom attribute values
+
+2. **Ensure attributes are added to PDF template**:
+   - Edit your Amasty PDF template
+   - Add custom attribute variables
+
+### Button not appearing
+
+1. **Clear cache**:
+   ```bash
+   php bin/magento cache:flush
+   ```
+
+2. **Check ACL permissions**:
+   - Ensure user role has proper permissions
+   - Review Stores > Configuration > Shopkeeper > PDFing PO ACL settings
+
+## Module Structure
+
+```
+Shopkeeper/PDFingPO/
+├── Block/
+│   └── Adminhtml/
+│       └── Order/
+│           └── View/
+│               └── PrintPo.php
+├── Controller/
+│   └── Adminhtml/
+│       └── Order/
+│           └── PrintPo.php
+├── etc/
+│   ├── acl.xml
+│   ├── adminhtml/
+│   │   ├── menu.xml
+│   │   └── routes.xml
+│   └── module.xml
+├── view/
+│   └── adminhtml/
+│       └── layout/
+│           └── sales_order_view.xml
+├── composer.json
+└── registration.php
+```
+
+## Dependencies
+
+This module requires:
+
+```json
+{
+    "amasty/module-pdf-customizer-subscription-package": "*",
+    "amasty/module-order-attributes-subscription-package": "*"
+}
+```
+
+## Support
+
+For issues or questions:
+1. Verify Amasty modules are installed and active
+2. Check Magento logs: `var/log/system.log`
+3. Review Amasty PDF Customizer documentation
+4. Verify module status: `php bin/magento module:status`
+
+## License
+
+Proprietary - Shopkeeper
+
+## Version
+
+1.0.0
+
+## Compatibility
+
+- Magento 2.4.x
+- Amasty PDF Customizer (subscription package)
+- Amasty Order Attributes (subscription package)