@aurigma/ui-framework/docs/reference/classes/auwidgetcanvas.md

A platform which allows building print product personalization editors based on Aurigma's Customer's Canvas.

# Class: AuWidgetCanvas

A widget that is used to integrate Customer's Canvas 4 to the editor.

_Deprecated._ Instead, you can use the [Design Editor widget](https://customerscanvas.com/dev/editors/ui-framework/widgets/design-editor.html).

```
{
  "widgets": [
    {
      "name": "editor",
      "type": "canvas",
      "title": "Personalize your flyer",
      "params": {
        "initial": {
          "productDefinition": {
            "surfaces": [{
              "width": 436.6,
              "height": 612.2
            }]
          },
          "editorConfig": { "initialMode": "Advanced" }
        }
      }
    },
    {
      "name": "preview",
      "type": "image-carousel",
      "params": {
        "containerColor": "#ccc",
        "images": [{ "url": "{{$['editor'].proofImageUrls[0][0]}}" }]
      }
    }
  ],
  "steps": [
    {
      "name": "design",
      "title": "1. Design",
      "mainPanel": { "name":"editor" }
    },
    {
      "name": "approve",
      "title": "2. Preview",
      "mainPanel": {"name":"preview"},
      "onActivate": "{{#function $['editor'].getHiResImages(800,800)}}"
    }
  ]
}
```

## Hierarchy

  ↳ [AuCanvas](aucanvas.md)

  ↳ **AuWidgetCanvas**

## Implements

* [IWidget](../interfaces/iwidget.md)
* [IRestorableWidget](../interfaces/irestorablewidget.md)

## Index

### Properties

* [actionsFinished](auwidgetcanvas.md#actionsfinished)
* [itemsData](auwidgetcanvas.md#itemsdata)
* [modifiedItem](auwidgetcanvas.md#optional-modifieditem)
* [params](auwidgetcanvas.md#params)

### Accessors

* [allItems](auwidgetcanvas.md#allitems)
* [boundsData](auwidgetcanvas.md#boundsdata)
* [currentSurfaceName](auwidgetcanvas.md#currentsurfacename)
* [depositPhotos](auwidgetcanvas.md#depositphotos)
* [hiResUrls](auwidgetcanvas.md#hiresurls)
* [proofImageUrls](auwidgetcanvas.md#proofimageurls)
* [stateId](auwidgetcanvas.md#stateid)
* [tags](auwidgetcanvas.md#tags)
* [userChanges](auwidgetcanvas.md#userchanges)
* [userId](auwidgetcanvas.md#userid)
* [variableData](auwidgetcanvas.md#variabledata)
* [violationWarningData](auwidgetcanvas.md#violationwarningdata)

### Methods

* [addSurface](auwidgetcanvas.md#addsurface)
* [addSurfaces](auwidgetcanvas.md#addsurfaces)
* [applyViewerSettings](auwidgetcanvas.md#applyviewersettings)
* [checkInitDependenciesWidgets](auwidgetcanvas.md#checkinitdependencieswidgets)
* [exportWidgetData](auwidgetcanvas.md#exportwidgetdata)
* [getAllItems](auwidgetcanvas.md#getallitems)
* [getCanvasItemModel](auwidgetcanvas.md#getcanvasitemmodel)
* [getDepositPhotos](auwidgetcanvas.md#getdepositphotos)
* [getHiResImages](auwidgetcanvas.md#gethiresimages)
* [getItemText](auwidgetcanvas.md#getitemtext)
* [getProofImages](auwidgetcanvas.md#getproofimages)
* [getTags](auwidgetcanvas.md#gettags)
* [getVariableData](auwidgetcanvas.md#getvariabledata)
* [openAssetManagerFor](auwidgetcanvas.md#openassetmanagerfor)
* [removeSurface](auwidgetcanvas.md#removesurface)
* [resetPreloaderState](auwidgetcanvas.md#resetpreloaderstate)
* [restoreWidgetFromData](auwidgetcanvas.md#restorewidgetfromdata)
* [saveProduct](auwidgetcanvas.md#saveproduct)
* [setTags](auwidgetcanvas.md#settags)
* [showPreloader](auwidgetcanvas.md#showpreloader)
* [showToast](auwidgetcanvas.md#showtoast)
* [switchSurfaceTo](auwidgetcanvas.md#switchsurfaceto)
* [toggleObjectInspector](auwidgetcanvas.md#toggleobjectinspector)
* [updateSurfaces](auwidgetcanvas.md#updatesurfaces)

## Properties

###  actionsFinished

• **actionsFinished**: *boolean* = false

This property is set to `true` when the editor enters the idle state.

___

###  itemsData

• **itemsData**: *kvObject‹string, [CanvasItemData](canvasitemdata.md)›*

Personalization data for design elements.

___

### `Optional` modifiedItem

• **modifiedItem**? : *[CanvasItemChanges](canvasitemchanges.md)* =  null

Last modified item on the canvas.

___

###  params

• **params**: *[ICanvasDefinitionParams](../interfaces/icanvasdefinitionparams.md)*

*Implementation of [IWidget](../interfaces/iwidget.md).[params](../interfaces/iwidget.md#optional-params)*

*Overrides [AuBaseWidget](aubasewidget.md).[params](aubasewidget.md#params)*

Properties of the canvas.

## Accessors

###  allItems

• **get allItems**(): *CustomersCanvas.IframeApi.ObjectModel.Item[]*

Gets all design elements in the product.

**Returns:** *CustomersCanvas.IframeApi.ObjectModel.Item[]*

An array of [`ObjectModel.Item`](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/item.html) elements.

___

###  boundsData

• **get boundsData**(): *Object*

Gets CC boundsData

**Returns:** *Object*

___

###  currentSurfaceName

• **get currentSurfaceName**(): *string*

Gets the name of the current surface.

**Returns:** *string*

___

###  depositPhotos

• **get depositPhotos**(): *[IDepositPhotosItem](../interfaces/idepositphotositem.md)[]*

Gets all images added from DepositPhotos.

**Returns:** *[IDepositPhotosItem](../interfaces/idepositphotositem.md)[]*

___

###  hiResUrls

• **get hiResUrls**(): *string[]*

Gets URLs that link to high-resolution print files.

**Returns:** *string[]*

___

###  proofImageUrls

• **get proofImageUrls**(): *string[][]*

Gets temporary URLs that link to proof images.

**Returns:** *string[][]*

___

###  stateId

• **get stateId**(): *string*

Gets the identifier of the last saved state file.

**Returns:** *string*

___

###  tags

• **get tags**(): *CustomersCanvas.IframeApi.ObjectModel.ITagsDictionary*

Gets product tags.

**Returns:** *CustomersCanvas.IframeApi.ObjectModel.ITagsDictionary*

An [`ObjectModel.ITagsDictionary`](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/itagsdictionary.html).

___

###  userChanges

• **get userChanges**(): *any*

Gets an object containing all changes made by the user when personalizing the product.

**Returns:** *any*

An object representing [`IUserChanges`](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/editor.iuserchanges.html).

___

###  userId

• **get userId**(): *string*

Gets the identifier of the user who currently works with the editor.

**Returns:** *string*

___

###  variableData

• **get variableData**(): *CustomersCanvas.IframeApi.ObjectModel.IVariable[]*

Gets all variable items in the product.

**Returns:** *CustomersCanvas.IframeApi.ObjectModel.IVariable[]*

An array of `ObjectModel.IVariable` elements.

___

###  violationWarningData

• **get violationWarningData**(): *CustomersCanvas.IframeApi.Editor.IViolationWarningData[]*

Gets violation warnings

**Returns:** *CustomersCanvas.IframeApi.Editor.IViolationWarningData[]*

## Methods

###  addSurface

▸ **addSurface**(`surface`: CustomersCanvas.IframeApi.ObjectModel.SurfaceTypes | CustomersCanvas.IframeApi.ObjectModel.IStateSurface, `position?`: number): *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*

Adds a product surface.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`surface` | CustomersCanvas.IframeApi.ObjectModel.SurfaceTypes | CustomersCanvas.IframeApi.ObjectModel.IStateSurface | A surface (page) to add. |
`position?` | number | Surface position (zero-based, optional). By default, this method adds pages to the end of the surface array.  |

**Returns:** *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*

___

###  addSurfaces

▸ **addSurfaces**(`surfaces`: CustomersCanvas.IframeApi.ObjectModel.SurfaceTypes[] | CustomersCanvas.IframeApi.ObjectModel.IStateSurface, `position?`: number): *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*

Adds several product surfaces.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`surfaces` | CustomersCanvas.IframeApi.ObjectModel.SurfaceTypes[] | CustomersCanvas.IframeApi.ObjectModel.IStateSurface | Surfaces (pages) as an array of surface definitions or a . |
`position?` | number | The position from which new pages will be inserted. (zero-based, optional).  |

**Returns:** *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*

___

###  applyViewerSettings

▸ **applyViewerSettings**(`params`: [ICanvasDefinitionSetViewerSettings](../interfaces/icanvasdefinitionsetviewersettings.md)): *Promise‹any›*

Executes the `setViewerSettings` command.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`params` | [ICanvasDefinitionSetViewerSettings](../interfaces/icanvasdefinitionsetviewersettings.md) | The settings of the zoom level in the editor.  |

**Returns:** *Promise‹any›*

___

###  checkInitDependenciesWidgets

▸ **checkInitDependenciesWidgets**(): *string[]*

*Inherited from [AuBaseWidget](aubasewidget.md).[checkInitDependenciesWidgets](aubasewidget.md#checkinitdependencieswidgets)*

Returns an array of widget names, due to which the current widget cannot receive parameters.

**Returns:** *string[]*

___

###  exportWidgetData

▸ **exportWidgetData**(`force`: boolean): *Promise‹CanvasData›*

*Implementation of [IRestorableWidget](../interfaces/irestorablewidget.md)*

Serializes the `canvas` widget.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`force` | boolean | If `true`, saves the product to a state file and returns its ID. If `false`, only returns the identifier of a previously saved state. |

**Returns:** *Promise‹CanvasData›*

A promise with the `stateId` property.
```
{ stateId: string }
```

___

###  getAllItems

▸ **getAllItems**(): *Promise‹CustomersCanvas.IframeApi.ObjectModel.Item[]›*

Gets all design elements in the product.

**Returns:** *Promise‹CustomersCanvas.IframeApi.ObjectModel.Item[]›*

A promise with an array of [`ObjectModel.Item`](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/item.html) elements.

___

###  getCanvasItemModel

▸ **getCanvasItemModel**(`changeObject`: [ItemChangeObject](../interfaces/itemchangeobject.md)): *Promise‹[CanvasItemChanges](canvasitemchanges.md)›*

*Inherited from [AuCanvas](aucanvas.md).[getCanvasItemModel](aucanvas.md#getcanvasitemmodel)*

Gets the object model of the elements on the canvas.
 @ignore

**Parameters:**

Name | Type |
------ | ------ |
`changeObject` | [ItemChangeObject](../interfaces/itemchangeobject.md) |

**Returns:** *Promise‹[CanvasItemChanges](canvasitemchanges.md)›*

___

###  getDepositPhotos

▸ **getDepositPhotos**(): *Promise‹[IDepositPhotosItem](../interfaces/idepositphotositem.md)[]›*

Gets info about images added from DepositPhotos.

For more details, you can refer to the topic describing how Customers's Canvas works with [Depositphotos Assets](https://customerscanvas.com/dev/editors/iframe-api/howto/asset-sources/depositphotos.html).

**Returns:** *Promise‹[IDepositPhotosItem](../interfaces/idepositphotositem.md)[]›*

A promise with an array of names and values of the variable fields.

___

###  getHiResImages

▸ **getHiResImages**(`width`: number, `height`: number, `stateId?`: string, `filename?`: string): *Promise‹string[]›*

Saves a state, renders print files and proof images, and returns links to the print files.

This method is equivalent to [editor.finishProductDesign](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/editor.ifinishdesignresult.html) from the IFrame API.

**Parameters:**

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
`width` | number | 800 | The maximum width of proof images. |
`height` | number | 800 | The maximum height of proof images. |
`stateId?` | string | - | A custom state file name without an extension, up to 36 symbols length. |
`filename?` | string | - | The name of the downloaded file. |

**Returns:** *Promise‹string[]›*

A promise with an array of URLs that link to the rendered print files.

___

###  getItemText

▸ **getItemText**(`itemName`: string): *Promise‹string›*

Returns the content of text items.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`itemName` | string | The name of a text item from which you want to get the content. |

**Returns:** *Promise‹string›*

A promise with a string.

___

###  getProofImages

▸ **getProofImages**(`width`: number, `height`: number): *Promise‹string[]›*

Renders proof images and returns URLs that link to these images.

This method is equivalent to [editor.getProofImages](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/editor.iproofresult.html) in the IFrame API.

**Parameters:**

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
`width` | number | 800 | The maximum width of proof images. |
`height` | number | 800 | The maximum height of proof images. |

**Returns:** *Promise‹string[]›*

A promise with an array of temporary links to proof images.

___

###  getTags

▸ **getTags**(): *Promise‹CustomersCanvas.IframeApi.ObjectModel.ITagsDictionary›*

Gets product tags.

**Returns:** *Promise‹CustomersCanvas.IframeApi.ObjectModel.ITagsDictionary›*

A promise with an [`ObjectModel.ITagsDictionary`](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/itagsdictionary.html).

___

###  getVariableData

▸ **getVariableData**(): *Promise‹CustomersCanvas.IframeApi.ObjectModel.IVariable[]›*

Detects what particular variable fields are used in the design and returns an array of such fields.

This method is equivalent to [product.getVariableItems](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/product.html#methods) from the IFrame API.

**Returns:** *Promise‹CustomersCanvas.IframeApi.ObjectModel.IVariable[]›*

A promise with an array of names and values of the variable fields.

___

###  openAssetManagerFor

▸ **openAssetManagerFor**(`itemName`: string): *void*

Opens the Asset Manager for image items.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`itemName` | string | The name of an image item or a placeholder item for which you want to open the Asset Manager.  |

**Returns:** *void*

___

###  removeSurface

▸ **removeSurface**(`surfaceIndex`: number): *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*

Removes a product surface.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`surfaceIndex` | number | A zero-based index of the surface that you want to remove.  |

**Returns:** *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*

___

###  resetPreloaderState

▸ **resetPreloaderState**(): *void*

*Inherited from [AuBaseWidget](aubasewidget.md).[resetPreloaderState](aubasewidget.md#resetpreloaderstate)*

**Returns:** *void*

___

###  restoreWidgetFromData

▸ **restoreWidgetFromData**(`widgetData`: CanvasData, `force`: boolean): *Promise‹void›*

Deserializes the `canvas` widget.

In a common scenario, the multistep editor restores a canvas when it is initialized.

**Parameters:**

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
`widgetData` | CanvasData | - | An object containing the `stateId` property. |
`force` | boolean | false | If `true`, gets a product definition from the state file and then executes the `initial` command. If `false`, it does nothing.  |

**Returns:** *Promise‹void›*

___

###  saveProduct

▸ **saveProduct**(`stateId?`: string): *Promise‹CustomersCanvas.IframeApi.Editor.ISaveProductResult›*

Saves a product.

This method is equivalent to [editor.saveProduct](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/editor.isaveproductresult.html) from the IFrame API.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`stateId?` | string | A custom state file name without an extension, up to 36 symbols length. |

**Returns:** *Promise‹CustomersCanvas.IframeApi.Editor.ISaveProductResult›*

A promise with [identifiers](https://customerscanvas.com/dev/editors/iframe-api/reference/design-editor-iframe/editor.isaveproductresult.html) of the user and the saved state file.

___

###  setTags

▸ **setTags**(`newTags`: any): *Promise‹void›*

Sets product tags.

This method is equivalent to [product.setTags](https://customerscanvas.com/dev/editors/iframe-api/howto/tags.html) from the IFrame API.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`newTags` | any | The tags that you want to specify for the product. These tags will reset existing product tags.  |

**Returns:** *Promise‹void›*

___

###  showPreloader

▸ **showPreloader**(`isPreload`: boolean, `message`: string | string[], `timeout`: number): *void*

*Inherited from [AuBaseWidget](aubasewidget.md).[showPreloader](aubasewidget.md#showpreloader)*

Shows a preloader.

```
"onClick": [
  "{{#function main.showPreloader(true, 'Creating print files...')}}",
  "{{#function $['editor'].getHiResImages(800,800)}}",
  "{{#function main.showPreloader(false)}}"
]
```

**Parameters:**

Name | Type | Default | Description |
------ | ------ | ------ | ------ |
`isPreload` | boolean | - | If `true`, enables the preloader. |
`message` | string | string[] |  [""] | A text message that appears next to the preloader.  |
`timeout` | number | 5 | - |

**Returns:** *void*

___

###  showToast

▸ **showToast**(`data?`: string, `duration?`: number): *void*

*Inherited from [AuBaseWidget](aubasewidget.md).[showToast](aubasewidget.md#showtoast)*

Shows a toast.

```
return editor.loadUserInfo(data)
    .catch(err => {
        this.widget.showToast("Error: Invalid data");
        console.log(err);
    });
```

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`data?` | string | A string message to display in the toast. |
`duration?` | number | Defines how long to show the toast for.  |

**Returns:** *void*

___

###  switchSurfaceTo

▸ **switchSurfaceTo**(`surfaceIndex`: number): *Promise‹any›*

Changes product pages in the Design Editor.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`surfaceIndex` | number | A zero-based index of the surface on which you want to switch.  |

**Returns:** *Promise‹any›*

___

###  toggleObjectInspector

▸ **toggleObjectInspector**(): *void*

Enables or disables the Object Inspector in the editor.

**Returns:** *void*

___

###  updateSurfaces

▸ **updateSurfaces**(`mode`: string, `update`: CustomersCanvas.IframeApi.ObjectModel.SurfaceTypes | CustomersCanvas.IframeApi.ObjectModel.IStateSurface | number): *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*

Add or remove surface.

**Parameters:**

Name | Type | Description |
------ | ------ | ------ |
`mode` | string | Update mode - 'add' or 'remove'. |
`update` | CustomersCanvas.IframeApi.ObjectModel.SurfaceTypes | CustomersCanvas.IframeApi.ObjectModel.IStateSurface | number | Update value - index of surface to remove or surface to add (depends on mode).  |

**Returns:** *Promise‹CustomersCanvas.IframeApi.ObjectModel.Product›*