PDF Product Catalogs for WooCommerce

Developer starting point

This baseline is generated from the reviewed local technical reference and source folder. Deployed-version parity and external-provider effects remain separate verification steps.

Admin Workflow

1. Create or Edit a Catalog

An administrator opens:

WooCommerce > PDF Catalogs

Then they create a new catalog or edit an existing catalog record.

2. Choose a Template

The user selects a layout template, typically the bundled shortcode-builder template or a user-created/uploaded template.

3. Choose a Settings Profile

For shortcode-builder layouts, the user can choose a saved template settings profile. This profile controls design and rendering settings while the catalog itself controls the actual product/category selection.

4. Select Product Data

The user selects included categories, excluded categories, and/or individual products.

The final product set is built by merging selected products and category products, then removing products that belong to excluded categories.

5. Configure Output Options

The user can configure:

• Image size.
• Category grouping.
• Product URL inclusion.
• Product card width.
• Extra product meta keys.

6. Save the Catalog

The plugin saves the catalog definition and associated metadata.

7. Generate the PDF

The user clicks Generate PDF. The plugin marks the catalog as queued, clears any previous file reference/log, and schedules the generation job.

8. Review or Download

When generation completes, the admin status card shows the generated PDF link.

---

Technical Architecture

Main Bootstrap File

athenian-pdf-product-catalogs.php

Responsibilities:

• Declares plugin metadata.
• Defines constants.
• Loads the autoloader.
• Confirms WooCommerce is active.
• Initializes the plugin on plugins_loaded.

Important constants:

ATH_PPC_VERSION
ATH_PPC_FILE
ATH_PPC_PATH
ATH_PPC_URL
ATH_PPC_SLUG

Namespace

The plugin uses the namespace:

Athenian\PDFProductCatalogs

Autoloading

The plugin includes a simple PSR-style autoloader:

includes/Support/Autoloader.php

Classes under Athenian\PDFProductCatalogs\ are mapped to files under:

includes/<ClassPath>.php

Core Plugin Class

includes/Plugin.php

Responsibilities:

• Registers the hidden catalog CPT.
• Initializes admin pages.
• Initializes background generation jobs.
• Initializes persistence helpers.
• Initializes shortcode runtime.
• Creates upload directories on activation.
• Flushes rewrite rules on activation/deactivation.

Admin Layer

includes/Admin/Admin.php
includes/Admin/Pages/CatalogsPage.php
includes/Admin/Pages/TemplatesPage.php

Responsibilities:

• Adds WooCommerce submenu pages.
• Enqueues admin CSS/JS.
• Localizes AJAX nonce and URL.
• Renders catalog list and edit screens.
• Handles catalog save/delete/generate actions.
• Renders template management and builder screens.
• Handles template upload, duplicate, preview, and delete operations.

Job Layer

includes/Jobs/GenerateCatalogJob.php

Responsibilities:

• Registers the generation hook.
• Queues catalog generation using Action Scheduler when available.
• Falls back to WP-Cron when Action Scheduler is not available.
• Sets status metadata before and after generation.
• Captures generation errors and stack traces in catalog log metadata.

PDF Layer

includes/PDF/CatalogGenerator.php
includes/PDF/MiniPDF.php

Responsibilities:

• Collects selected WooCommerce products.
• Applies category include/exclude logic.
• Resolves template configuration.
• Groups products by category when enabled.
• Generates output PDF paths.
• Renders shortcode-builder output through HTML/CSS and Dompdf when available.
• Writes fallback PDFs when needed.
• Converts WooCommerce images to JPEG-compatible temporary files.
• Supports legacy/vector drawing through MiniPDF.

Template Support Layer

includes/Support/Templates.php
includes/Support/TemplateBuilder.php
includes/Support/ShortcodeTemplateRuntime.php
includes/Support/Util.php

Responsibilities:

• Discover plugin and uploaded templates.
• Parse CSS variables from template CSS.
• Convert CSS colors to RGB for PDF drawing.
• Build template manifests from builder payloads.
• Save user-authored templates to uploads.
• Render preview documents.
• Resolve dynamic placeholders.
• Render shortcode-based catalog previews.
• Store and retrieve saved template configurations.
• Provide product/category sample data when WooCommerce data is unavailable.

---

Data Model

Custom Post Type

ath_pdf_catalog

The CPT stores saved catalog records. It is private, not publicly queryable, and not shown in the standard WordPress admin menu.

Catalog Post Meta

| Meta key | Purpose | |---|---| | _ath_ppc_template | Selected template ID. | | _ath_ppc_shortcode_config_key | Saved shortcode-builder settings profile key. | | _ath_ppc_product_card_width | PDF product card width override, 0–420. | | _ath_ppc_include_desc | Legacy/back-compat description toggle. Current generator notes descriptions are no longer rendered in the non-shortcode path. | | _ath_ppc_include_url | Whether to include product URL / product link button where supported. | | _ath_ppc_group_by_cat | Canonical category grouping flag used by the custom admin screen and generator. | | _ath_ppc_image_size | WordPress/WooCommerce image size used for catalog output. | | _ath_ppc_category_ids | Included WooCommerce product category term IDs. | | _ath_ppc_exclude_category_ids | Excluded WooCommerce product category term IDs. | | _ath_ppc_product_ids | Explicitly included WooCommerce product IDs. | | _ath_ppc_extra_meta_keys | Additional product meta keys for template-supported output. | | _ath_ppc_status | Catalog generation state. | | _ath_ppc_log | Last generation error/log output. | | _ath_ppc_file_rel | Relative upload path of generated PDF. | | _ath_ppc_generated_at | Last generated timestamp. |

Options

| Option key | Purpose | |---|---| | ath_ppc_shortcode_template_configs | Stores saved shortcode-builder catalog settings and section configurations by key. |

Upload Paths

| Path | Purpose | |---|---| | wp-content/uploads/ath-pdf-catalogs/ | Generated PDFs and companion HTML exports. | | wp-content/uploads/ath-pdf-catalogs/tmp/ | Temporary converted JPEG files. | | wp-content/uploads/ath-pdf-catalogs/templates/ | Uploaded or user-authored template packages. |

---

AJAX Endpoints

Catalog Admin Endpoints

| Action | Purpose | |---|---| | ath_ppc_search_products | Search WooCommerce products for the admin product selector. | | ath_ppc_catalog_status | Poll catalog generation status and generated file URL. | | ath_ppc_run_catalog | Runs queued/generating catalog generation during admin polling. |

Template Admin Endpoints

| Action | Purpose | |---|---| | ath_ppc_template_preview | Render saved template preview. | | ath_ppc_builder_preview | Render builder preview document from submitted builder payload. | | ath_ppc_builder_load | Load template payload into the admin builder. |

Shortcode Builder Endpoints

| Action | Purpose | |---|---| | ath_ppc_stb_render_preview | Render live shortcode-builder preview. | | ath_ppc_stb_load_template | Load a shortcode-builder template and its saved config. | | ath_ppc_stb_save_config | Save shortcode-builder catalog settings and section configuration. | | ath_ppc_stb_create_template | Save a shortcode-builder payload as a user template package. | | ath_ppc_stb_duplicate_template | Duplicate an existing shortcode-builder template. | | ath_ppc_stb_delete_template | Delete a user-created shortcode-builder template. | | ath_ppc_stb_products_for_category | Fetch product choices for a selected WooCommerce category. |

All admin and shortcode-builder AJAX routes require appropriate nonce validation. Administrative routes also require manage_woocommerce or manage_options capabilities.

---

Hooks and Extension Points

Actions

| Hook | Purpose | |---|---| | ath_ppc_generate_catalog | Background generation hook used by Action Scheduler or WP-Cron. |

Filters

| Filter | Purpose | |---|---| | ath_ppc_templates_v2 | Filter the discovered template list before display/use. | | ath_ppc_catalog_products | Filter the final collected WooCommerce product array before generation. | | ath_ppc_extra_meta_lines | Filter extra product meta lines rendered into product cards. |

These hooks make it possible to customize product inclusion, enrich product metadata, add template packages programmatically, or modify catalog output behavior without editing core plugin files.

---

Template System

Template Discovery

Template folders are scanned from plugin and uploads directories. Each template folder must contain a JSON manifest and may contain a CSS file and preview image.

Recognized manifest filenames:

template.json
manifest.json

The folder name must match the manifest id.

Built-In Template Note

The package includes a templates/list folder, but the current template scanner intentionally only exposes the newer shortcode_builder bundled template from the plugin template directory. Uploaded/user templates are also loaded and can override built-in templates.

This suggests the plugin has moved from older fixed layouts toward the JSON/shortcode-builder template workflow.

Template Manifest Concepts

Template manifests may define:

• Template ID.
• Template name.
• Description.
• Source.
• Schema version.
• Layout mode.
• Page dimensions.
• Fonts.
• Builder runtime.
• Global catalog settings.
• Sections.
• Section design types.
• Preview templates.

CSS Variables

The template scanner parses CSS variables from template CSS and can use those variables to drive PDF theming.

Supported color parsing includes:

• Hex colors such as #ec8639.
• Short hex colors such as #fff.
• rgb(r,g,b) values.
• var(--token) references where the referenced variable exists.

---

Rendering Flow

Shortcode-Builder PDF Flow

1. Load the selected template.
2. Load the selected saved config profile.
3. Merge saved catalog settings into the template global settings.
4. Merge saved sections into the template sections.
5. Apply product card width override.
6. Resolve PDF orientation.
7. Collect selected product IDs and category IDs.
8. Render standalone HTML from the template/runtime.
9. Write the companion .html export file.
10. Use Dompdf if available to generate PDF.
11. If Dompdf is unavailable, write a MiniPDF fallback/stub PDF.
12. Store the generated relative PDF path in catalog meta.

Product Collection Flow

1. Start with explicitly selected product IDs.
2. Add products from included categories using WC_Product_Query.
3. Remove any products assigned to excluded categories.
4. Load each product via wc_get_product().
5. Sort products alphabetically by product name.
6. Apply the ath_ppc_catalog_products filter.

Image Handling

The generator resolves WooCommerce product image paths using the selected image size. It attempts to use local upload paths when possible and falls back to the attachment file path. Non-JPEG images are converted to temporary JPEG files using GD functions when available.

Temporary JPEG files are stored under:

wp-content/uploads/ath-pdf-catalogs/tmp/

Old temporary JPEG files are cleaned up after a six-hour cutoff.

---

Security and Permissions

The plugin uses several WordPress security patterns:

• Exits when accessed outside WordPress.
• Requires WooCommerce to be active.
• Restricts admin pages to manage_woocommerce or manage_options users.
• Uses nonces for admin form actions.
• Uses AJAX nonce validation for admin and shortcode-builder endpoints.
• Sanitizes template IDs using sanitize_key().
• Sanitizes text fields, category/product IDs, meta keys, and numeric width values.
• Uses wp_safe_redirect() after admin actions.
• Uses wp_kses_post() for builder HTML where rich template markup is expected.
• Prevents deletion of built-in templates from the uploaded-template delete path.

---

Technical Observations

Strong Architecture

The plugin has a clean namespace, a simple autoloader, isolated admin pages, a job class, a PDF generator class, a template discovery layer, and a shortcode runtime. This makes the plugin relatively easy to extend compared with a single-file procedural implementation.

Template Direction Is Clear

Although legacy grid/list concepts remain in parts of the code, the current package clearly emphasizes the shortcode_builder runtime and JSON-backed template workflow. That is the most flexible direction for branded catalogs.

Dompdf Should Be Treated as a Production Dependency

For the current shortcode-builder layout path, Dompdf is the preferred PDF renderer. In production, this should likely be documented as a recommended or required dependency if the business expects exact HTML/CSS-to-PDF output.

Minor Legacy Persistence Mismatch

CatalogsPage uses _ath_ppc_group_by_cat as the canonical group-by-category key. The separate Admin\Persist helper stores _ath_ppc_group_by_category. Since the custom admin screen is the primary workflow and the generator reads _ath_ppc_group_by_cat, the current catalog workflow works from the custom screen. The Persist helper appears to be a legacy or fallback save-post helper and may need cleanup or key alignment in a future hardening pass.

Built-In List Template Is Present but Hidden

The ZIP contains a templates/list package, but Templates::list_templates() currently only exposes shortcode_builder from bundled plugin templates. This may be intentional, but if the list layout should be available in the UI, the scanner logic would need to be revised.

---

Implementation Snapshot

Main Files

| File | Purpose | |---|---| | athenian-pdf-product-catalogs.php | Plugin bootstrap and WooCommerce dependency check. | | includes/Plugin.php | Core initialization and CPT registration. | | includes/Admin/Admin.php | WooCommerce admin menu and asset loading. | | includes/Admin/Pages/CatalogsPage.php | Catalog list, edit, save, delete, generate, and AJAX status/search logic. | | includes/Admin/Pages/TemplatesPage.php | Template management, upload, duplicate, preview, and builder UI. | | includes/Admin/Persist.php | Legacy/fallback save-post persistence helper. | | includes/Jobs/GenerateCatalogJob.php | Action Scheduler / WP-Cron generation queue. | | includes/PDF/CatalogGenerator.php | Product collection, template resolution, HTML/PDF generation, and file output. | | includes/PDF/MiniPDF.php | Lightweight internal PDF writer. | | includes/Support/Templates.php | Template discovery, CSS variable parsing, template loading. | | includes/Support/TemplateBuilder.php | Template payloads, manifests, preview rendering, token resolution. | | includes/Support/ShortcodeTemplateRuntime.php | Shortcodes, preview runtime, saved config storage, product/category rendering. | | includes/Support/Util.php | Upload paths, timestamps, text sanitization, truncation helpers. |

Asset Files

| File | Purpose | |---|---| | assets/css/admin.css | Admin UI styling for catalog and template screens. | | assets/js/admin.js | Admin Select2 product search, template UI behavior, preview, and generation polling. | | assets/css/shortcode-template-builder.css | Frontend/shortcode builder styling. | | assets/js/shortcode-template-builder.js | Shortcode builder interaction, AJAX preview/save/load/create/duplicate/delete behavior. |

---