--- title: "Input | Customer's Canvas Hub" canonical: "https://customerscanvas.com/docs/hub/admin-guide/workflows/workflow-elements/handy-editor/input/" --- # Input > The [`input`](https://customerscanvas.com/docs/hub/admin-guide/workflows/workflow-elements/handy-editor.md#configuration-format) object contains product properties for loading the editor. These properties allow you to retrieve products defined in Customer's Canvas in various ways. Let's take a look at them. Conceptually, all types of inputs can be divided into the following: - For opening designs without PIM - For initialization using PIM data - For recovery scenarios :::note If data in the `input` object is sufficient to initialize two or more scenarios, the first available scenario will be applied. At the same time, a warning will be logged to the console. ::: ## Working without PIM ### Public template and mockup Use this scenario when PIM integration is unnecessary. That is, when you need to work directly with templates and mockups to group them into products or you may not implement an e-commerce scenario at all. You can load an editor based on public data stored in your tenant. If needed, upload only a design template by its `designTemplateId`. You can also specify preview mockups in this definition. 3D mockups will be displayed in the viewer, and 2D mockups will appear on the approval screen. Depending on the mockup type, pass `mockup3dId` with a single ID or `previewMockups` with an array of IDs. These mockups must be saved in public storage. The `input` object for providing public designs and mockups has the following properties: - `designTemplateId` is the ID of a template stored in **Assets** > **Designs**. It's mandatory. - `previewMockups` is an array of mockup IDs for the approval screen from **Assets** > **Images**. - `mockup3dId` is a 3D mockup for the viewer from **Assets** > **Mockups**. It's passed only to ``, and if not specified, the 3D viewer will not be initialized. A sample `input` of the Handy Editor with 2D preview mockups for the approval screen: ```js { // ID of a template stored in assets, mandatory. "designTemplateId": "61cd31a43056bcc33e919927", // Array of mockup IDs for the approval screen from Images. "previewMockups": [ { "surfaceIndex": 0, "mockupId": "643d05f7c121897df4598271" }, { "surfaceIndex": 1, "mockupId": "643d05fbc121897df4598277" } ] } ``` A sample `input` of the Handy Editor 3D with mockups for the viewer: ```js { // ID of a template stored in assets, mandatory. "designTemplateId": "61cd31a43056bcc33e919927", // 3D mockup for the viewer from Mockups. "mockup3dId": "6527afc63507abfadd355226" } ``` ### Private design and mockup When the user has already edited a design template, the customized design is saved in this user's private storage. If a design was generated through the Asset Generator service (parametric design use cases), it's also saved in private storage. To access private storage, you will need the ID of the user who created the design and [that user's token](https://customerscanvas.com/docs/hub/dev-center/api/storefront/register-customers.md). Then, you can open the editor using the design ID. You can also specify preview mockups in this definition. 3D mockups will be displayed in the viewer, and 2D mockups will appear on the approval screen. Depending on the mockup type, pass `mockup3dId` or `previewMockups`. We assume that these mockups are private. The `input` object for providing private designs and mockups has the following properties: - `designId` is the ID of a design customized by a user. - `mockup3dId` is a private 3D mockup generated for the viewer through the [Asset Generator API](https://customerscanvas.com/docs/hub/dev-center/api/asset-generator.md). - `previewMockups` is an array of mockup IDs for the approval screen. This is how the `input` object may look like: ```js { "designId": "66bcc31cd39271a43cc3e919", // ID of a design customized by a user. "mockup3dId": "6527afc63507abfadd355226" // Private 3D mockup generated for the viewer. } ``` ## Working with PIM ### Product reference If you integrate Customer's Canvas with a standard e-commerce platform, like Shopify, you can load the editor based on a product ID from that system. In this scenario, Customer's Canvas uses the external product ID to link the product, as described in the [Product links](https://customerscanvas.com/docs/hub/admin-guide/pim/products-links.md) article. To load an editor, pass the `productReferenceId` to the `input`: - `productReferenceId` is a product ID in an e-commerce system. - `designVariantFilter` applies [additional filtering](#filtering-designs) to designs, for example, by file name or by SKU. This is how you can define the `input` object to bind external products from a standard e-commerce system to Customer's Canvas products: ```js { "productReferenceId": "8255218868440", // External product ID. "productId": "414" // Customer's Canvas product ID. } ``` ### PIM data Use this approach with custom e-commerce integrations, when an external system knows the product ID from Customer's Canvas PIM module. In this case, you create products in Customer's Canvas and receive a list of products in the admin panel of your store. No product link is required here. The `input` object has the following properties: - `productId` is a product ID in Customer's Canvas. - `productVersionId` is a number of the saved product instance. - `productVariantId` is a product variant ID. If skipped, all the variants will be obtained for managing in your application. - `variantDesignId` is the ID of the original design that preselects a design variant within `productVariantId`. It works only when `productVariantId` is specified. If skipped, the editor uses the first design variant. If the ID is invalid, the editor raises an error event. - `productFilterId` is a filter ID to apply to the obtained product variant list. - `designVariantFilter` applies [additional filtering](#filtering-designs) to designs, for example, by file name or by SKU. To load an editor, pass the `productId` and `productVariantId` to the `input`. Optionally, pass `variantDesignId` to preselect a design variant. ```js { "productId": 114, // Product ID in Customer's Canvas. "productVersionId": 1011, // Number of the saved product instance. "productVariantId": 22698, // Product variant ID. "variantDesignId": "66bcc31cd39271a43cc3e919" // Original design ID to preselect a design variant. } ``` ### Batch order Use this scenario for mass ordering, when a customer orders several variants of the same product in a single editor session. To learn how to configure this input, refer to the [Batch order](https://customerscanvas.com/docs/hub/dev-center/frontend-integration/workflow-elements/handy-editor/input.md#batch-order) topic in the developer documentation. ### Filtering designs You can apply additional filtering to designs, for example, by file name, by folder, or by SKU. The `designVariantFilter` used in the `input` supports the following filter types: - `search` is a file name substring. - `designCustomFields` is an object with key-value pairs defining a custom field with a required value. - `designPath` is a substring of the folder path in asset store. - `options` is an object with key-value pairs defining an option ID with an option value ID `{ opt_id: opt_value_id }`. - `sku` is the product variant SKU. This is how you can filter designs for a product variant by name and by custom fields. ```js { "productId": 114, "productVariantId": 22698, "designVariantFilter": { "search": "card", // Filter by file name containing "card". "designCustomFields": {"public": "true"} // Filter by custom fields. } } ``` ## Recovery strategies Recovery scenarios are necessary when you need to restore the state of selected PIM options, design, and changes made to that design. This may be required in cases such as: - Returning to editing from the cart. - Complex scenarios where a template is edited in multiple editors sequentially. - When a design was created using the API from variant resources. Recovery scenarios are necessary if you need to open a design in the editor that was created in an external system based on PIM data or to reopen a design previously created in it. :::note In recovery scenarios, the `productVersionId` field is always mandatory. If missing, the editor will open the latest version of the product, which may not match the version in which the design was created. ::: ### Recovery using SKU Recovery interface: ```js { "sku": "product-sku", // SKU of the product variant. "designId": "private-design-id", // Private design ID. "productId": 123, // Product ID. "productVersionId": 456, // Product version ID. "productLinkId": 789, // Optional: Product link ID. "designVariantTemplateId": "public-design-id" // Optional: Public design ID from which the Design Variant was created. } ``` :::note This scenario is not suitable for cases where different PIM variants reference the same SKU in the external system. ::: ### Recovery using variant ID Recovery interface: ```js { "productVariantId": 123, // Product variant ID. "designId": "private-design-id", // Private design ID. "productId": 456, // Product ID. "productVersionId": 789, // Product version ID. "productLinkId": 1011, // Optional: Product link ID. "designVariantTemplateId": "public-design-id" // Optional: Public design ID from which the Design Variant was created. } ``` ### Note on the designVariantTemplateId field The optional field `designVariantTemplateId` is used to indicate to the editor from which design variant the provided `designId` was created. Currently, the Handy Editor does not use this information, but it may be necessary to indicate the selected design variant in the user interface, similar to the Simple Editor. If you initialize the editor with a template previously created in the Handy Editor, you can pass the `event.detail.designVariantTemplateId` field from the `addtocart` event. If you created the design via the API, you can use the information from the `/api/storefront/v1/products/{id}/variant-designs` endpoint. The `designId` field of the variant you need is what you require for this case.