Cmash Connector — Marketing Overview

Personalized print products in Magento, from editor to order, in one flow

Cmash Connector brings the Cmash Web2Publish editor into your Magento store. Customers design business cards, flyers or any template-based product right on the product page, put the result into the cart and order it — while the shop keeps the exact artwork that was ordered.

The Problem It Solves

Selling personalized print products usually means juggling a separate design tool, e-mailed proofs and manual file handling. Designs get lost between editor and checkout, and if a customer keeps editing after ordering, nobody knows which version is the one that was actually bought.

Key Benefits

For Customers

• Design where you shop — open the editor in a modal or on its own page directly from the product, no extra account or tool needed.
• Only design what needs a design — for products with several variants, the editor appears only for variants that are personalized; all others go straight into the cart as usual.
• Pre-filled with your data — name, e-mail, address and other selected profile details are placed into the template automatically.
• Nothing gets lost — values typed right before "Add to Cart" are saved with the design.
• Edit from the cart — reopen and change a design that is already in the cart.
• Keep working safely — after ordering you can continue editing your design; the ordered version stays exactly as it was.
• Download your files — get the rendered output (single item or complete batch) from the order view.

For Store Operators

• Order-safe artwork — every order gets its own frozen copy of the design, so production always prints what was ordered.
• Flexible product setup — assign a design template to a whole product or to individual variants; mix personalized and standard variants in one product.
• No orders without a design — personalized products without a design cannot be checked out or ordered, in the shop or via API.
• Clean project housekeeping in Cmash — designs are automatically marked as draft when they go into the cart and as finished when they are ordered; abandoned checkout attempts leave no orphaned copies.
• Traceable designs — Cmash shows which shop, customer and cart or order a design belongs to; multi-shop setups are told apart by a configurable system name.
• Robust checkout — communication problems with Cmash are logged but never block cart or checkout.
• Control which data is shared — decide per product or customer attribute whether it is sent to the editor, kept private, or not shared at all.
• Downloads in the admin — fetch production files straight from the order view.

How It Works

1. The customer opens a product that is linked to a Cmash template (or selects a personalized variant) and clicks "Start Configuration".
2. The editor opens, pre-filled with product and customer data; the customer designs the product.
3. "Add to Cart" saves the design, places the product in the cart and marks the design as a draft.
4. At checkout the ordered design is frozen as a separate copy and marked as finished.
5. Customer and shop staff download the rendered files from the order.

Feature Highlights

Technical Highlights for Integrators

• No core overrides: plugins, observers and declarative schema only.
• Works with Luma and, together with the Hyvä companion module, with Hyvä themes.
• Compiled-DI safe; editor page excluded from full page cache.
• Dedicated log file for all Cmash API communication.
• Reusable project state service for companion modules (e.g. drafts and wishlists).

Requirements

• Magento Open Source / Adobe Commerce 2.4.x, PHP 8.2, 8.3 or 8.4
• Enobis Cmash Core module
• Access to a Cmash Web2Publish instance with API token (a version that supports project references; app.cmash.io does)

What's New in 1.0.37

• Know when a saved design is gone — the shop can now check whether a design still exists in Cmash, so saved drafts whose design was removed there can be flagged instead of failing when the customer opens them (used by the Cmash Drafts module).
• No false alarms — a design is only reported as missing when Cmash clearly says so; connection problems never mark a design as deleted.

What's New in 1.0.36

• Every design knows where it belongs — Cmash projects now carry the shop, the customer and whether they are a draft, in a cart or ordered, plus the cart or order number, so designs can be matched with shop data in Cmash.
• Several shops, one Cmash account — give each shop its own system name in the configuration (default: the shop's host name) to tell them apart.
• Privacy-friendly — only the internal customer number is shared, no e-mail address; guests are simply left without a customer reference.
• Safe for checkout — if Cmash cannot be reached, the references are skipped and logged; cart and checkout keep working.

What's New in 1.0.35

• Personalized and standard variants in one product — each variant can have its own design template or none; customers see the editor only where it is needed and buy standard variants with the normal Add to Cart.
• Reliable variant switching — the editor always uses the design of the variant the customer just picked; changing a cart item to a variant with another design starts a fresh design.
• Safer cart — variants without a template can no longer be added as a design.
• No orders without a design (1.0.34) — personalized items without a design are sent back to the cart before checkout and cannot be ordered via storefront or API.
• Edit from cart and wishlist (1.0.34) — the existing design reopens reliably when editing an item.

Pricing & Licensing

For licensing information, pricing, and enterprise bundles, contact:

enobis GmbH www.enobis.de

Cmash Connector — Technical Documentation

Version 1.0.37. Keep this file in sync with the code; omit sections that do not apply.

Features

• Product page editor — "Start Configuration" opens the Cmash editor in a modal (cmash/editor/create) or on its own page (cmash/editor/index) for products with a template (cmash_document_uuid); requires cmash/general/enabled.
• Configurable products per variant (1.0.35) — the template is resolved per variant: the child's cmash_document_uuid wins, the parent's is the fallback. If every variant has a template, the standard Add to Cart box is hidden. For mixed configurables (some variants without template) the editor button appears only once a variant with a template is fully selected; otherwise the regular Add to Cart is shown.
• Add to Cart from the editor — the project is linked to the quote item (cmash_project_uuid custom option), editor values are synced to the project first. cmash/cart/add rejects variants/products without a template (1.0.35).
• Edit from cart / wishlist — the cart or wishlist configure page reopens the item's project (1.0.34: project UUID kept in the preconfigured values). When a configurable item is reconfigured to a variant with a different template, a new project is started instead (1.0.35).
• Project required for ordering (1.0.34) — checkout and multishipping redirect to the cart, order placement (storefront, REST, GraphQL) fails and wishlist-to-cart is blocked while a Cmash product has no project.
• Project state sync — forward-only temp → draft (cart) → finished (ordered), see below.
• Frozen order artwork — each Cmash order item gets its own project copy at checkout; the source UUID is kept in sales_order_item.cmash_source_project_uuid.
• Project references (1.0.36) — every Cmash project carries external reference fields (shop, customer, owner type, quote/order ID), see "Project references" below. Requires a Cmash version that supports them (app.cmash.io does). Writes are best effort: failures are logged to cmash.log and never break cart or checkout.
• Downloads — rendered output per order item or as batch ZIP, frontend (customer) and admin order view.
• Attribute data — product, customer, address and account-relation attributes flagged "Used For Cmash Document" are sent to the editor.
• No list add to cart — Cmash products are not added to the cart directly from category/search lists; the add URL points to the product page.
• CSP — the Cmash host is added to script-src and frame-src.

Module Dependencies

Database Schema

etc/db_schema.xml adds to sales_order_item:

Patches:

• Setup/Patch/Data/AddCmashDocumentUuidAttribute — product attribute cmash_document_uuid (varchar, store scope, group "Cmash Connector").
• Setup/Patch/Schema/AddUsedForCmashDocumentColumn — used_for_cmash_document (smallint) on catalog_eav_attribute and customer_eav_attribute.

etc/catalog_attributes.xml adds cmash_document_uuid to the quote_item group so cart validation can read it on quote item products (1.0.34).

Configuration Paths

ACL: Enobis_CmashConnector::config. Admin section: Stores > Configuration > Cmash > Cmash Connector (incl. module/composer version display).

Routes & Controllers

DI: Preferences, Plugins, Virtual Types

Note: ProjectState, CopyProjectUuidToOrderItem and DeleteOrderedProjectCopies log via the default Psr\Log\LoggerInterface (system.log/exception.log); only Model\Api\Client writes to cmash.log.

Events & Observers

Project state lifecycle (1.0.33)

States in Cmash: temp (default on create) → draft → finished. Model\ProjectState only moves forward: it reads the current state (GET embed/projects/{uuid}) and sends PUT embed/projects/{uuid} {"state": ...} only when the target ranks higher (Cmash answers 422 on downgrades of finished projects). Unknown states rank as temp. All errors are logged, never thrown.

Order cancellation does not change the state. Draft/wishlist states (save, finish) are handled by companion modules via Model\ProjectState.

Project references (1.0.36)

Model\ProjectReference builds and writes the external reference fields so Cmash can tell which shop, customer and owner a project belongs to. The existing reference (product-<id>) is unchanged.

For an owner type, reference2 and reference3 are always sent (null clears values inherited from a copy); reference_user is only sent when known, so an existing value is never cleared.

The cart project itself keeps its quote reference; only the frozen copy carries the order. Api\Client::createEmbedProject() forwards reference2, reference3, reference_system, reference_status and reference_user (null values are dropped). Updates and copies pass the fields through updateEmbedProject() / copyEmbedProject() overrides. Failures of ProjectReference::assign() are logged (cmash.log) and swallowed.

Layout Handles & Templates

Frontend JavaScript

• Enobis_CmashConnector/js/modal-editor — opens the editor in a modal (cmash/editor/create), reads editor values via the Cmash bridge and posts them as project_data with the cart form; dispatches cmash:toolbar on document.
  • Config (x-magento-init from CustomizeButton::getJsConfig(), 1.0.35): isConfigurable, alwaysCustomized, childDocumentUuids (child ID → template, parent fallback, '' for regular variants), existingDocumentUuid (template of the cart item being reconfigured).
  • super_attribute is read from the super_attribute[...] inputs of #product_addtocart_form (swatch data-option-selected attributes only as fallback; jQuery .data() returns stale cached swatch values).
  • Selected child: swatch widget .data('mage-SwatchRenderer').getProduct() or .data('mage-configurable').simpleProduct, only when all options are selected.
  • For mixed configurables it listens to change and swatch.initialized on #product_addtocart_form and switches between editor button and regular Add to Cart; the button does nothing for variants without template.
  • The existing project of a reconfigured cart item is only reused when the selected variant has the same template; the project UUID input is cleared before create and on close.
• Enobis_CmashConnector/js/editor — postMessage listener for the full-page editor iframe.
• Enobis_CmashConnector/js/download-modal — loads renderers (cmash/download/options) and posts file/batch downloads with form_key.
• External: <base_url>/vendor/cmash-embed/js/cmash-bridge.js.

Customer Data Sections

etc/frontend/sections.xml: cmash/cart/add invalidates cart.

Key Classes

Extension Points

• Model\ProjectState (public markDraft()/markFinished(), constants TEMP/DRAFT/FINISHED) for other modules that save or finish projects.
• Model\ProjectReference (public) for other modules that own a project: forDraft(draftId, customerId) / forQuote() / forOrder() build the fields (merge into create/copy options), assign(uuid, fields) writes them to an existing project without throwing. forDraft() is not used by this module itself (1.0.36).
• Model\Api\Client public methods incl. copyEmbedProject(uuid, overrides) (overrides: state, name, data, and the reference* fields since 1.0.36; without state the copy inherits the source state) and deleteEmbedProject(uuid).
• Model\Api\Client::embedProjectExists(uuid): ?bool (1.0.37) — GET embed/projects/{uuid}; true for 2xx, false only for HTTP 404 (project deleted or unknown in Cmash), null for any other status or an exception (exceptions are logged to cmash.log). Callers must treat null as "unknown", not as "missing". Not used by this module itself; enobis/module-cmash-draft 1.0.7 uses it to flag drafts whose Cmash project no longer exists.
• Block\Editor::isAddToCartVisible() and Block\Product\View\CustomizeButton::getExistingProjectUuid() are plugged by companion modules; CustomizeButton::getJsConfig()/isAlwaysCustomized() can be reused by theme adaptations.
• Model\Product\DocumentResolver (public, constant ATTRIBUTE) for any code that needs the template of a product or variant.
• Model\Cart\ProjectValidator::getItemsWithoutProject() / getErrorMessage() for further checkout guards.
• Observers can be disabled per name in events.xml (e.g. enobis_cmash_mark_project_draft, enobis_cmash_assign_quote_project_reference, enobis_cmash_mark_ordered_projects_finished, enobis_cmash_delete_ordered_project_copies, enobis_cmash_redirect_to_cart_without_project).

Translations

i18n/de_DE.csv contains the German storefront phrases, including the Hyvä-only phrases of Enobis_CmashConnectorHyva (e.g. "Checking…"). Phrases already translated by the core or the splendidinternet/mage2-locale-de-de language pack are not repeated. Backend labels are not translated yet. i18n/en_US.csv lists the same phrases 1:1 as a reference for translators; i18n/fr_FR.csv and i18n/it_IT.csv contain the same phrases in French and Italian.