Differences

This shows you the differences between two versions of the page.

--- magento2:extensions:magento-2-product-attachment [2026/08/20 23:53] – created - external edit 127.0.0.1
+++ magento2:extensions:magento-2-product-attachment [2026/09/18 19:05] (current) – swatwik
@@ Line 1: / Line 1: @@
 ====== Magento 2 Product Attachment User Guide ======
-===== Related overview =====
+===== Extension Overview =====
-For a shopper-friendly overview of features and setup, see the [[https://toweringmedia.com/magento-2-product-attachment-user-guide|Magento 2 Product Attachment User Guide - Manuals & Specs]] on the storefront. This wiki page remains the full technical documentation.
+The **Magento 2 Product Attachment** extension gives store administrators a simple way to add documents and other files to products.
-===== Extension context =====
+These files can be used for product manuals, specifications, installation instructions, warranty information, brochures, or any other information that customers may need.
-This is a Toweringmedia Magento 2 extension guide for the current admin extension catalog.
+Attachments can be uploaded to Magento or added as an external link. Once an attachment is created, it can be assigned to products or categories and made available to selected customer groups.
-===== Product page =====
+The extension also provides options for showing attachments on the product page, category page, customer order view, and transactional emails.
-  * [[https://toweringmedia.com/magento-2-product-attachment|Magento 2 Product Attachment]] (SKU ''tm-product attachment'')
+===== Installation =====
-===== Overview =====
+Please refer to the installation guide in the following article:
-This extension attaches downloadable files — manuals, spec sheets, safety data sheets, warranty documents — to Magento 2 products and categories. Attachments appear in a product page tab, can be reused across products via category assignment, and can optionally be included with customer orders. A download report shows which files customers are actually retrieving.
+[[https://toweringmedia.com/installation|Magento 2 Extension Installation Guide]]
-===== What this extension does =====
+===== Admin Configuration =====
-  * Attach files to products and display them in a PDP tab.
+After the extension has been installed, its settings can be found in the Magento Admin under:
-  * Assign attachments at category level and roll them down to products in that category.
-  * Group attachments and assign custom file-type icons.
-  * Optionally include attachments with customer orders.
-  * Bulk import attachments.
-  * Download reporting.
-===== Requirements =====
+**Stores → Configuration → Towering Media → Product Attachments**
-  * Magento 2.4.x (Open Source or Adobe Commerce).
+The configuration is divided into several sections.
-  * PHP: ^8.1 || ^8.2 || ^8.3 (as declared by the published package).
-  * A current Toweringmedia license and Composer credentials for ''https://composer.toweringmedia.com/''.
-  * Composer resolves ''toweringmedia/module-base'' automatically.
-===== Installation =====
+==== General ====
-Install and validate in a staging environment before production rollout.
+The **General** section contains the main settings for the extension.
-<code bash>
+^ Setting ^ Description ^
-cd /path/to/magento
+| **Enable Module** | Turn the extension on or off for the selected store view. |
-composer require toweringmedia/module-product-attachments
+| **Add Category Files to Products** | When enabled, files assigned to a category can also be made available on products in that category. |
+| **Display Include In Order Files on Product Pages** | Controls whether files marked as **Include In Order** should also be shown on the product page. |
+| **Download URL Type** | Controls the type of URL generated for attachment downloads. The example configuration uses **Opaque Hash**. |
-bin/magento module:enable Toweringmedia_ProductAttachments
+> **Note:** Settings marked as **[store view]** can be configured separately for different store views.
-bin/magento setup:upgrade
-bin/magento setup:di:compile
+==== Product Tab ====
-bin/magento setup:static-content:deploy -f
-bin/magento cache:flush
+These settings control the Product Attachments section on the product page.
+^ Setting ^ Description ^
+| **Show Product Attachments Tab** | Shows or hides the attachment tab on the product page. |
+| **Tab Title** | Sets the title displayed to customers. For example, **Product Attachments** or **Downloads**. |
+| **Tab Position** | Sets the position of the attachment tab. The extension recommends avoiding multiples of 10. |
+| **Show File Icon** | Shows the file icon next to an attachment. |
+| **Show File Size** | Shows the file size next to the attachment. |
+For example, the tab title can be changed from **Product Attachments** to **Downloads** if that better fits the store.
+==== Category Page ====
+Use these options if you want to show files that belong to a category.
+^ Setting ^ Description ^
+| **Show Category Attachments in Sidebar** | Shows or hides the category attachment block in the sidebar. |
+| **Block Title** | Sets the heading shown above the attachment list. |
+| **Show File Icon** | Shows the file icon. |
+| **Show File Size** | Shows the file size. |
+This is useful when the same document applies to a complete category rather than one specific product.
+{{:magento2:extensions:pt-config1.png?400|}}
+==== Order View Page ====
+This section controls attachments that customers can see from their order details.
+^ Setting ^ Description ^
+| **Show Attachments** | Turns the attachment section on or off in the order view. |
+| **Block Title** | Sets the title of the attachment section. |
+| **Type of Attachments to Display** | Controls which attachments are shown. The example uses **Include in order only**. |
+| **Order Statuses** | Optional. Enter status codes separated by commas, such as `pending,processing,complete`. Leave it empty to show attachments for all order statuses. |
+This gives the administrator control over when attachments should be available from an order.
+==== Order Email ====
+If product attachments need to be included in transactional emails, configure the settings in this section.
+^ Setting ^ Description ^
+| **Add Attachments to Transactional Emails** | Turns email attachments on or off. |
+| **Block Title** | Sets the title used for the attachment section in the email. |
+| **Type of Attachments to Display** | Controls which attachments are included in the email. |
+==== Download ====
+The **Autodetect File MIME Type on Download** option controls how Magento determines the file type when an attachment is downloaded.
+When this option is set to **Yes**, the extension detects the file's MIME type during the download. Downloads use `Content-Disposition: attachment`.
+==== Link Health ====
+The **Link Health** settings are useful when attachments use external URLs.
+The extension can check external links daily and send an email when a broken link is found.
+^ Setting ^ Description ^
+| **Enable Daily Link Health Check** | Enables or disables the daily link check. |
+| **Notification Emails** | Email addresses that should receive notifications when broken links are found. Multiple addresses can be separated with commas. |
+Example:
+<code>
+admin@example.com, support@example.com
 </code>
-Currently published versions at the time of writing:
+{{:magento2:extensions:pt-config2.png?400|}}
-  * ''toweringmedia/module-product-attachments'' — 0.1.0
+===== Managing Product Attachments =====
-Toweringmedia packages are served from the licensed Composer repository ''https://composer.toweringmedia.com/''. If Composer reports that the package could not be found, your credentials are missing or the license does not cover this package yet. Retrieve your keys from **My Account** on toweringmedia.com, or contact [[mailto:support@toweringmedia.com|support@toweringmedia.com]].
+The **Product Attachments** grid is used to manage existing attachments.
-General installation notes that apply to every Toweringmedia extension are in the [[https://toweringmedia.com/installation|installation guide]].
+Open:
-==== Package naming note ====
+**Towering Media → Product Attachments**
-The storefront product is named **Product Attachment** (singular) but the Composer package is ''toweringmedia/module-product-attachments'' (plural). The install command above uses the real package name.
+The grid contains information such as:
-===== Configuration =====
+  * ID
+  * File Label
+  * Attachment Type
+  * Link Status
+  * Visible
+  * Action
+  * Icon
+  * File Name
+  * MIME Type
+  * File Size
+  * Created At
+  * Updated At
+  * Customer Groups
-  * Stores > Configuration > Towering Media > **Product Attachments** (config section ''toweringmedia_product_attachments'').
+To create a new attachment, click **Add New Attachment**.
-  * Groups: ''general'' (enable, roll category files down to products, show "include in order" on PDP, URL type) and ''product_tab'' (PDP tab behaviour).
-  * Admin screens: Catalog > **Product Attachments**, **Attachment Icons**, **Attachment Groups**, **Import Attachments**; Reports > **Attachment Downloads**.
-===== Basic usage and what to expect =====
+The grid also provides **Import** and **Export** options for working with attachment data.
-  - Upload files under Catalog > Product Attachments and assign them to products or categories.
+{{:magento2:extensions:pt-grid.png?400|}}
-  - Open a product on the storefront and confirm the attachments tab renders with working download links.
-  - Use Reports > Attachment Downloads to see which documents customers retrieve.
-===== Notes and limitations =====
+===== Adding an Attachment =====
-  * This package is published at a pre-1.0 version.
+Click **Add New Attachment** to create a new attachment.
-===== Validation checklist =====
+The attachment form contains the information needed to upload the file, control who can see it, and decide where it should be used.
-  * ''bin/magento module:status'' shows the module(s) as enabled.
+==== Attachment Type ====
-  * Extension configuration saves without errors in Admin.
-  * The admin screens listed above are reachable and load without error.
+Select the attachment type.
-  * Expected storefront/admin behavior is present after a cache flush.
-  * No critical PHP/JS errors appear in ''var/log/'' during the primary test flow.
+For an uploaded document, select **File**.
+==== File ====
+Click **Upload** and select the file you want to use.
+When editing an existing attachment, the uploaded file can also be removed.
+==== Attachment Name ====
+Enter a name that makes the attachment easy to identify in the Admin.
+Example:
+<code>
+Sample Product Manual
+</code>
+==== Label ====
+The label is the name customers will see on the storefront.
+Example:
+<code>
+Product Manual
+</code>
+The attachment name and label do not have to be the same.
+==== Customer Groups ====
+Select the customer groups that should have access to the attachment.
+The available customer groups may include:
+  * NOT LOGGED IN
+  * General
+  * Wholesale
+  * Retailer
+If no customer group is selected, the attachment is available to all customer groups.
+==== Is Visible ====
+Set **Is Visible** to **Yes** when the attachment should be available on the storefront.
+Set it to **No** if you want to keep the attachment in the Admin but temporarily hide it from customers.
+{{:magento2:extensions:pt-edit1.png?400|}}
+==== Include In Order ====
+Set **Include In Order** to **Yes** when the attachment should also be available with the customer's order.
+Depending on the configuration, these attachments can also be shown in the customer's order view and included in transactional emails.
+===== Assigning the Attachment =====
+After adding the file, use the **Attach To** section to decide where the attachment should be available.
+==== Categories ====
+Select one or more categories.
+For example, a document that applies to all bags can be assigned to the **Bags** category.
+If **Add Category Files to Products** is enabled, category attachments can also be made available on the products in that category.
+==== Products ====
+Click **Add products** and select the products that should use the attachment.
+The product selection list includes information such as:
+  * Product ID
+  * Thumbnail
+  * Product Name
+  * Status
+  * Product Type
+  * SKU
+  * Price
+If a product is already assigned and you want to remove it, use the **Remove** action.
+Once the attachment and product assignments are complete, click **Save Attachment**.
+{{:magento2:extensions:pt-edit2.png?400|}}
+===== User Experience =====
+Once an attachment is enabled and assigned to a product, customers can access it from the storefront.
+==== Product Page ====
+The attachment section is displayed on the product page according to the extension configuration.
+In the example below, the **Product Attachments** section appears below the main product information.
+The customer can see the attachment label and, when file size display is enabled, the size of the file.
+For example, the **Joust Duffle Bag** product displays:
+<code>
+Product Attachments
+Product Manual (4.5 KB)
+</code>
+The customer can click **Product Manual** to access the document.
+The exact location and appearance of the attachment section may vary depending on the Magento theme and configuration.
+{{:magento2:extensions:pt-frontend.png?400|}}
 ===== Troubleshooting =====
-  * **Composer cannot find the package**: confirm the ''https://composer.toweringmedia.com/'' repository and your credentials are present in ''auth.json'', and that your license covers this package.
+Most attachment issues are related to visibility, product assignment, customer groups, configuration, or Magento cache.
-  * **Feature not visible**: verify module status, flush cache, and redeploy static content.
-  * **Admin setting not applying**: clear cache and confirm the config scope (default / website / store view).
-  * **Unexpected behavior**: retest with only the required related modules enabled.
-===== Support =====
+==== Attachment is not showing on the product page ====
-  * [[mailto:support@toweringmedia.com|support@toweringmedia.com]]
+Check the following:
-  * [[https://toweringmedia.com/magento-maintenance-support|Magento maintenance and support]]
-===== Related Magento 2 docs =====
+  * Make sure **Is Visible** is set to **Yes**.
+  * Make sure the attachment is assigned to the correct product.
+  * Check that **Show Product Attachments Tab** is set to **Yes**.
+  * If it is a category attachment, check the category assignment.
+  * If required, check **Add Category Files to Products**.
+  * Clear the Magento cache and test the product page again.
-  * [[magento2:extensions:start|Magento 2 extension index]]
+==== Customer cannot see the attachment ====
-  * [[start|Global docs home]]
+Check the **Customer Groups** selected for the attachment.
+Also check:
+  * The attachment is visible.
+  * The customer is using the expected store view.
+  * The attachment is assigned to the correct product or category.
+==== Attachment cannot be downloaded ====
+Check that:
+  * The uploaded file still exists.
+  * The attachment is configured correctly.
+  * The **Download URL Type** setting is correct.
+  * There are no download-related errors in the Magento or web server logs.
+If the problem occurs only with a particular file type, also check the server's MIME type configuration.
+==== External link is not working ====
+If the attachment uses an external URL:
+  * Open the URL directly in a browser.
+  * Check the URL for typing or formatting errors.
+  * If **Link Health** is enabled, check for broken-link notifications.
+  * Update the attachment if the external file has been moved.
+==== Attachment is missing from the customer order ====
+Check the following:
+  * Set **Include In Order** to **Yes**.
+  * Check **Show Attachments** under **Order View Page**.
+  * Check **Type of Attachments to Display**.
+  * If **Order Statuses** are configured, make sure the current order status is included.
+==== Attachment is not included in the order email ====
+Check:
+  * **Add Attachments to Transactional Emails** is set to **Yes**.
+  * The attachment is marked **Include In Order**.
+  * The **Type of Attachments to Display** setting under **Order Email** is correct.
+  * Place a test order and check the resulting email.
+==== Category attachment is not showing ====
+Check:
+  * The attachment is assigned to the correct category.
+  * **Show Category Attachments in Sidebar** is set to **Yes**.
+  * The category attachment settings are correct.
+  * If the file should also appear on products, check **Add Category Files to Products**.
+==== Changes are not visible ====
+After changing the configuration:
+  * Click **Save Config**.
+  * Clear the Magento cache.
+  * If required, refresh static content according to the store's deployment process.
+  * Test the page again using a private/incognito browser window.
+==== Link Health notifications are not being sent ====
+Check:
+  * **Enable Daily Link Health Check** is set to **Yes**.
+  * Valid addresses have been entered in **Notification Emails**.
+  * Multiple email addresses are separated with commas.
+  * Magento cron is running correctly.
+===== Before Contacting Support =====
+If the issue continues, provide the following information when contacting support:
+  * Magento version and PHP version.
+  * The affected product or attachment.
+  * The store view where the issue occurs.
+  * Steps used to reproduce the problem.
+  * Relevant Magento or web server log messages.
+  * Screenshots of the Admin configuration and storefront issue.
+This information will make it easier to identify the problem and reproduce it.
+===== Support =====
+  * [[mailto:support@toweringmedia.com|support@toweringmedia.com]]
+  * [[https://toweringmedia.com/magento-maintenance-support|Magento maintenance and support]]