Introduction

Current version: 0.10.34

LiveArt HTML5 uses JSON format to transfer data, such as information about design, pricing and order, to backend. In order to prepare server-side application for work in pair with LiveArt component, backend services should be ready to receive and deliver valid data structures via HTTP queries. The detailed description of this queries and datatypes is given in the following article.

Each request is normally sent as POST request with the payload, contained in value parameter. Sometimes additional parameters may include design id or timestamp. Using Inspector properly, you will be able to notice all information that is being sent.

All endpoint URLs can be both relative or absolute. For correct operation of the tool we advise using relative URLs more as you may get into CORS issue if your users will be accessing tool with a different URL than provided in main configuration file. A common example is accessing site with or without the www.

API Endpoints

GetQuote - POST

Request example

{
  "colors": 4,
  "isFullColor": false,
  "colorsNum": 4,
  "colorsList": [
    "#FFFFFF",
    "#000000",
    "#F4EB21",
    "#FAA744"
  ],
  "product": {
    "id": "21",
    "productColors": [
      {
        "id": ".bg.fill",
        "name": "Aero",
        "value": "#9cb8d0"
      }
    ],
    "color": "#9cb8d0",
    "colorName": "Aero",
    "size": {
      "width": 3,
      "height": 10,
      "label": "3x10in"
    }
  },
  "locations": [
    {
      "name": "Front",
      "colors": 4,
      "isFullColor": false,
      "colorsNum": 4,
      "colorsList": [
        "#FFFFFF",
        "#000000",
        "#F4EB21",
        "#FAA744"
      ],
      "objectCount": 2,
      "letterings": 1,
      "images": 1,
      "designedArea": "9",
      "designedAreaRect": "9",
      "designedWidth": "3",
      "designedHeight": "3",
      "objects": [
        {
          "type": "txt",
          "text": "text",
          "designedArea": "1.80",
          "colorsNum": 1,
          "colors": 1,
          "colorsList": [
            "#ee6363"
          ]
        },
        {
          "type": "svg",
          "id": "42",
          "isUploaded": false,
          "designedArea": "7.20",
          "colorsList": [
            "#000000",
            "#F4EB21",
            "#FAA744"
          ],
          "colorsNum": 3,
          "colors": 3,
          "isFullColor": false
        }
      ]
    }
  ],
  "namesNumbers": [
    {
      "name": "forward",
      "numberText": "07",
      "size": "L"
    },
    {
      "name": "goalkeeper",
      "numberText": "02",
      "size": "L"
    }
  ],
  "quantities": [
    {
      "size": "S",
      "quantity": 1
    },
    {
      "size": "L",
      "quantity": 2
    },
    {
      "size": "XL",
      "quantity": 0
    }
  ]
}

Response example

{
  "prices": [{
    "label": "Item Price",
    "price": "$ 94.62"
   }, {
    "label": "Discount",
    "price": "$ -6.00"
   }, {
    "label": "Total",
    "price": "$ 904.20",
    "isTotal": true
  }]
}

This service is used to get the price of a current design. It is called every time when end user is making some changes to the design or product selection.

To bind LiveArt HTML5 to the server side GetQuote service, you will need to define the getQuoteUrl property in config JSON. The value has to be a link to a backend service. See example below:

Service definition in config.json

"getQuoteUrl": "services/getQuote.php"

Request fields description

Field	Description	Type
product.id	unique identifier of the product.	string
product.productColors	optional: product colorizable areas list (only for multicolor products).	array of colorizable area objects
product.color	hexadecimal value of product color. v0.10.6 change: optional; Added only if product has colors. In case of multicolor product - added only if product has one colorizable area only.	string
product.colorName	name of product color. v0.10.6 change: optional; Same behaviour as product.color.	string
product.size	optional configured product size in units. Available only if product.locations.editableAreaUnits is defined or product has property resizable = true Attributes: width (number) height (number) label(optional, string) — only if product.editableAreaSizes is defined	object
colorsList	legacy list of hexadecimal values of the colors which are used on all product locations (array of strings). If any of locations has full color print - “processColors” (string).	mix
colors	legacy amount of colors used on all locations (number). If any of locations has full color print - “processColors” (string). v0.10.13 change: adding to amount not-specified colors from graphics config (i.e. graphic.colors = “7”);	mix
colorsNum	amount of the colors which are used on all locations added in v0.10.13	number
isFullColor	bool to indicate full colors at least on one location added in v0.10.13	bool
namesNumbers	list of names and numbers. Empty if current product does not support names/numbers.	array
quantities	quantity of the sizes. Also includes entered size values from names/numbers list.	number
location.name	name of product location	string
location.isFullColor	full color print flag added in v0.10.4	bool
location.colors	legacy amount of the colors which are used at the current location (number) or string “processColors” in case of full print	mixed
location.colorsNum	amount of the colors which are used at the current location added in v0.10.4	number
location.colorsList	list of hexadecimal values of the colors which are used at the current location.	array of strings
location.designedArea	total area of all decoration objects at the current location (square units). Example. v0.10.6 change: optional; Present only if location has proper design area sizes configration.	string
location.designedAreaRect	area of rectangle, containing all objects in location (square units). Example. v0.10.6 change: optional; Present only if location has proper design area sizes configration.	string
location.designedWidth	v0.10.6 added optional attribute Width of designed area rect in units. Example. Present only if location has proper design area sizes configration.	string
location.designedHeight	v0.10.6 added optional attribute Height of designed area rect in units. Example. Present only if location has proper design area sizes configration.	string
location.objectCount	total count of all decoration objects at the current location.	number
location.letterings	total count of all text objects at the current location.	number
location.images	total count of all graphic objects at the current location.	number
location.objects	list of decoration objects which are present at the current location.	array
location.objects.type	type of decoration object. Possible values: "txt", "svg" and "image"	string
location.objects.text	optional: only for type="text" objects - text value	string
location.objects.id	optional: only for gallery graphic objects - graphics id value	string
location.objects.designedArea	area occupied by the object (in square units). v0.10.6 change: optional; Same behaviour as location.designedArea.	number
location.objects.colors	legacy amount of colors used to colorize the object. See more in location.colors	mix
location.objects.colorsList	list of RGB colors used to colorize the object.	array of strings
location.objects.colorsNum	amount of colors used to colorize the object added in v0.10.4	number
location.objects.isFullColor	object full color print flag added in v0.10.4	bool
location.objects.isUploaded	optional: only for objects type="svg / image". Indicates that object was uploaded by user added in v0.10.19	bool

Response fields description

The only expected node is designated as prices, type array each elements of which may contain the following fields.

Field	Description	Type
label	title of price line, e.g. Item Price, Discount, etc.	string
price	the actual price of the price line	string
isTotal	defines whether this price line designates total and will be bolded in LiveArt	boolean, optional

SaveDesign - POST

Request Example

{
  "data": {
    "product": {
      "id": "11",
      "name": "Cool Tee 1"
    },
    "locations": [{
      "name": "Front",
      "svg": "<svg><!-- svg content is omitted here due to its large size --></svg>"
    }, {
      "name": "Back",
      "svg": "<svg><!-- svg content is omitted here due to its large size --></svg>"
    }],
    "quantities": [{
      "size": "XS",
      "quantity": 1
    }],
    "prices": [{
      "label": "Item Price",
      "price": "$ 12.01"
    }, {
      "label": "Discount",
      "price": "$ -3.00"
    }, {
      "label": "Total",
      "price": "$ 324.30",
      "isTotal": true
    }]
  }
}

Response Example

{
  "design": {
    "id": "20130514-131710-50632", "title": "Lorem Ipsum"
  }
}

SaveDesign service is called in the following cases:

• User is placing order;
• User is saving design for later use using Save for Later link;
• User is sharing design. In this case design is saved anonymously if user is not authenticated;

SERVICE DEFINITION IN CONFIG.JSON

"saveDesignUrl": "services/saveDesign.php"

POST REQUEST FIELDS DESCRIPTION

Request fields

Field	Description	Type
data	main object — see detailed description below	object
title	optional: title for saved design (input by user). For shared desgins - empty string. For ordered designs - not included	string
email	optional: only if user entered email before (e.g. for saving design)	string
type	saved for saved designs (including ordered) and shared for shared designs added 0.10.21: ordered for ordered designs (before - saved type was used)	string
quote	optional: quote objects. Only for ordered designs	object
id	optional: only for saved (and ordered) designs, if design was previously saved/loaded	string
design	optional, added 0.10.21: object for shorthand descrion {title?: string, type: string (saved/shared/ordered)}	object

DATA FIELD DESCRIPTION

Request contains JSON metadata with enclosed SVG which should be extracted with the parsing script and saved. Developers can additionally process SVG to embed images, prepare for conversion into other formats or add additional elements.

Field	Description	Type
product.id	unique identifier of the product.	string
product.name	name of product.	string
product.template	based template id	string
product.productColors	optional: product colorizable areas list (only for multicolor products) v0.10.14 change: always presented for m-color products (previous: only for 1-color m-color products)	array of colorizable area objects
product.color	hexadecimal value of product color. v0.10.14 change: also used for m-color products(1st color)	string
product.colorName	name of product color. v0.10.14 change: also used for m-color products(1st color)	string
product.size	optional configured product size in units. Available only if product.locations.editableAreaUnits is defined or product has property resizable = true Attributes: width (number) height (number) label(optional, string) — only if product.editableAreaSizes is defined	object
locations	list of product locations (sides) for each printable side	array
location.name	name of location.	string
location.svg	XML representation of an SVG image which contains the whole design (including product background).	string
location.editableArea	location editable area; Not resizable products: same value as configured; Resizable products: actual value of resized area in coordinate system of canvas Format: "X1 Y1 X2 Y2"	string
quantities	list of selected sizes and their quantities.	array
prices	list of objects which are related to pricing. The structure is exact to the one you compile for GetQuote service	array
namesNumbers	list for team names and numbers. Actual only if product.namesNumbersEnabled = true, otherwise — empty array	array of objects
notes	added in v0.10.19 Design notes entered by user	string
selectedUnit	added in v0.10.30 optional: Possible value: defaultUnit or secondaryUnit. See more details config.option.defaultUnit.	string
templateId	added in v0.10.30 optional: ID of the base template (product template/ the latest added design idea)	string
strict	added in v0.10.30 True - if there is at least one object with constrains.	boolean

RESPONSE FIELDS DESCRIPTION

Field	Description	Type
id	unique design identifier, it is your responsibility to generate it and keep it’s consistency.	string
title	design title which is given by end user. In cases of placing order or sharing design it is generated automatically by LiveArt	string

UploadImage - POST/Multipart

Response example

{
  "url":"files\/uploads\/some_image.jpg"
}

In case of error

{
  "error": { "message":"Incorrect image type!" }
}

This service is used to upload user image from local file or URL. After uploading process image is shown on preview area and ready to be moved or resized. Allowed file extensions by default: *.jpg, *.png, *.gif, *.svg.

SERVICE DEFINITION IN CONFIG.JSON

To bind LiveArt HTML5 to the server side Upload Image service, you will need to define the uploadImageUrl property in config JSON. The value has to be a link to a backend service.
See example below: "uploadImageUrl": "services/uploadImage.php"

SERVICE FUNCTIONS

• regular file upload: POST method (multipart/form-data). Variable name: image - file uploaded by user
• file upload by URL: POST method (application/x-www-form-urlencoded). Variable name: fileurl - absolute file URL (entered by user or response from 3rd party API (e.g. Social Networks))
  Note: v0.10.19 changes: fileurl is encoded string (usage: urldecode($POST['fileurl']))

GetDesigns - GET

Response Example

{
  "designs": [
    {"id": "20130419-175034-29813", "title": "My First Design", "date": "2013.04.19 17:50"},
    {"id": "20130419-175828-96476", "title": "My Second Design", "date": "2013.04.19 17:58"}
  ]
}

This service is called to get the list of saved designs for certain email. The backend service should use the email (and product as option) from GET parameter as key(s) to filter designs for particular account.

SERVICE DEFINITION IN CONFIG.JSON

Tokens Description: - ${email} - mandatory token. It will be replaced in request with actual email, provided by the user. - ${product_id} (added in 0.10.24) - optional token for filtering designs list by current product

"getDesignsUrl": "services/loadDesigns.php?email=${email}&product_id=${product_id}"

RESPONSE FIELDS DESCRIPTION

Field	Description	Type
id	unique design identifier, should be unique per design.	string
title	design title which is given by end user.	string
date	date when design was saved.	string

LoadDesign - GET

This service is called to load the Design JSON of a previously saved design. The service is called in the following cases:

• To load the previously saved design for certain email;
• To preload the shared design from a previously saved link;
• To preload LiveArt with design using a design_id in the URL;

SERVICE DEFINITION IN CONFIG.JSON

The token will automatically replaced with an associated design_id fetched either from URL design_id parameter or selected design from list of designs, after user clicked to load a previously saved design. “loadDesignUrl”: “services/loadDesign.php?design_id=${design_id}”

RESPONSE DESCRIPTION

The provided response should correspond the request example from SaveDesign service.

SaveTemplate - POST

Request Example

{
  "data": {
    "product": {
      "id": "11",
      "name": "Cool Tee 1"
    },
    "locations": [{
      "name": "Front",
      "svg": "<svg><!--
      svg content is omitted here due to its large size
      --></svg>"
    }, {
      "name": "Back",
      "svg": "<svg><!--
      svg content is omitted here due to its large size
      --></svg>"
    }],
    "quantities": [{
      "size": "XS",
      "quantity": 1
    }],
    "prices": [{
      "label": "Item Price",
      "price": "$ 12.01"
    }, {
      "label": "Total",
      "price": "$ 324.30",
      "isTotal": true
    }]
  },
  "name": "Simple Template",
  "type": "template",
  "productId": "11"
}

Response Example

{
  "template": {
    "id": "template-20171020-120454-10506",
    "name": "Simple Template"
  }
}

Added in version: 0.10.27.
Save Template is service to save (or update) “Design Ideas” templates list. Used only in “Admin mode”.
Read more on Templates KB

SERVICE DEFINITION IN CONFIG.JSON

"saveTemplateUrl": "services/saveTemplate.php"

POST REQUEST FIELDS DESCRIPTION

Request fields

Field	Description	Type
data	main object — see detailed description in SaveDesign - POST data field description	object
name	title for saved template (input by user)	string
type	template for design which is set upped by admin. Objects in such design can contains additional restrictions. If product contains at least one template - template is opened instead of clear product. design idea for design which has no product, can be added to products which have no templates	string
productId	optional: for template type only	string

RESPONSE FIELDS DESCRIPTION

Field	Description	Type
id	unique design identifier, should be unique per template.	string
name	template title	string

GetTemplates - GET

Response Example ( If template list contains categories/subcategories )

{
  "templatesCategoriesList": [
    {
      "id": "hipster",
      "name": "Hipster Logos",
      "thumb": "files/template-id/design_preview.png",
      "templatesList": [
        {
          "id": "template-20170928-152458-17800",
          "type": "design idea",
          "date": "2017.09.28 15:24",
          "thumb": "files/template-id/design_preview.png",
          "name": "Thinking"
        }
      ],
      "categories": []
    },
    {
      "id": "simple",
      "name": "Simple",
      "thumb": "files/template-id/design_preview.png",
      "templatesList": [
        {  
          "id":"template-20171002-162505-89535",
          "type":"template",
          "date":"2017.10.02 16:25",
          "thumb":"files/template-20171002-162505-89535/design_preview.png",
          "productId":"11t",
          "name":"Gentleman"
        }
      ],
      "categories": []
    }
  ]
}

Response Example ( If template list has no categories/subcategories (plain template list) )

{
 "templatesList": [
   {
     "id": "template-20170921-141139-10609",
     "type": "design idea",
     "date": "2017.09.21 14:11",
     "thumb": "files/template-id/design_preview.png",
     "name": "LiveArt"
   }
 ]
}

Added in version: 0.10.27.
Called to get list of “Design Ideas”. Response structure similar to graphics or products list.
Read more on Templates KB

SERVICE DEFINITION IN CONFIG.JSON

"getTemplatesUrl": "services/getTemplates.php?product_id=${product_id}"

Tokens Description: - ${product_id} -
If product_id is empty - service should return complex art design ideas
if product_id is not empty - service should return templates for provided product.

REQUEST FIELDS DESCRIPTION

Field	Description	Type
product_id	optional: will be provided as replaced ${product_id} token in getTemplatesUrl	string

RESPONSE FIELDS DESCRIPTION

Field	Description	Type
templatesCategoriesList	optional: list of templates categories objects(see description below). Can not exists with templatesList on the same level	array/objects
templatesList	list of templates objects(see description below). Can not exists with templatesCategoriesList on the same level	array/objects

TEMPLATE CATEGORIES FIELDS DESCRIPTION

Field	Description	Type
id	unique template category identifier, should be unique.	string
name	template category title	string
templatesList	list of templates objects(see description below)	array/objects
thumb	url to thumbnail image (allowed file extensions: *.jpg, *.png, *.gif, *.svg, dimensions: 110px x 110px) which will be shown in the templates catalog.	string
categories	optional: can not exists with templatesList on the same level	array/objects

TEMPLATE FIELDS DESCRIPTION

Field	Description	Type
id	unique template identifier, should be unique.	string
type	template for design which is set upped by admin. Objects in such design can contains additional restrictions. If product contains at least one template - template is opened instead of clear product. design idea for design which has no product, can be added to products which have no templates	string
date	create/update date	string
thumb	url to thumbnail image (allowed file extensions: *.jpg, *.png, *.gif, *.svg, dimensions: 110px x 110px) which will be shown in the templates catalog.	string
productId	optional: for type template only	string
name	template title	string

Configuration

LiveArt Configuration has 2 entry points: - config/config.json - set of properties in JSON format; by default - static file, but often is generated by server-side to serve current needs; - LA.config.js (added 0.10.5) - set of pure js objects with options. Usually requires one-time setup during integration, and designed for more deep customization by integrator.

config.json

Sample configuration

{
    "productsList": {
        "url": "config/products.json"
    },
    "defaultProductId": "11",
    "fonts": {
        "url": "config/fonts.json"
    },
    "colors": {
        "url": "config/colors.json",
        "pantones_url": "config/pantones.json"
    },
    "graphicsList": {
        "url": "config/graphics.json"
    },
    "social": {
        "url": "config/social.json"
    },
    "options": {
        "deleteOnDoubleClick": false,
        "includeProductInDesign": true,
        "includePrintingAreaInDesign": true,
        "includeMaskInDesign": true,
        "fontsCSSUrl": "fonts/fonts.css",
        "zoomEnabled": true,
        "minZoom": 50,
        "maxZoom": 150,
        "checkeredBackground": true,
        "unit": "in",
        "unit2": "ft",
        "unitConversionMult": 12,
        "showProductSelector": true,
        "checkTextFXThrottle": 400,
        "minDPU": 300,
        "showUploadedColorsDialog": true,
        "fitProductImage" : true,
        "fitEditableArea": true,
        "enableSnapGuides": true,
        "showSuitableProductColorize": true,
        "mergeDesignIdeas": false
    },
    "textEffects": {
        "config": "config/textEffects.json"

    },
    "defaultNameObjectText": "NAMES HERE",
    "defaultNumberObjectText": "00",
    "assetsUrl": "assets/",
    "galleryBaseUrl": "",
    "getQuoteUrl": "services/getQuote.php",
    "getDesignsUrl": "services/getDesigns.php?email=${email}",
    "saveDesignUrl": "services/saveDesign.php",
    "loadDesignUrl": "services/loadDesign.php?design_id=${design_id}",
    "redirectUrl": "services/order.php?design_id=${design_id}",
    "uploadImageUrl": "services/uploadImage.php",
    "shareLinkUrl": "index.html?design_id=${design_id}",
    "saveTemplateUrl": "services/saveTemplate.php",
    "getTemplatesUrl": "services/getTemplates.php?product_id=${product_id}",
    "redirectWindow": "parent"
}

LiveArt JS uses JSON format for its main configuration file and data configuration files for resources such as products and gallery images. The primary configuration file contains all the necessary options, as well as REST-like endpoints for server-side integration.

Properties description

Property	Description	Type
productsList	indicates a URL returning a Product JSON structure	URL
defaultProductId	id of a product should be loaded upon start of LiveArt.	string, optional
defaultProductSize	deprecated in v0.10.24 Highly recommended to use laOptions.defaultProductAttributes.sizeUnits if default product is resizable, this attribute sets default size (Note: has lower priority to product.locations.editableAreaUnits) in units, set by configuration.	array of numbers, optional
fonts	indicates a URL returning Fonts JSON structure	URL
colors	indicates a URL returning Colors JSON structure. These are the colors for fonts and colorizable artwork	URL
colors.pantones_url	added in v0.10.4 Colors JSON with Pantones. Available for fonts and colorizable artwork, and in color picker appears in separate tab. To disable this feature — remove the field. Note: for colorizing multicolor products refer to Product List configuration	URL
graphicsList	indicates a URL returning Gallery JSON structure.	URL
social	indicates a URL returning social networks configuration for uploading photos Added to v0.10.10	URL
options	contains the list of options which control visual appearance and behaviour of the designer area. See detailed description below.	object
textEffects	location for text effects configuration file and URL to service to obtain image of the text effect with certain parameters. See Data Structures section for details on using the text effects. To disable text effects completely, leave both fields empty.	URL
defaultNameObjectText, defaultNumberObjectText	a default text/number text, rendered in placeholder for Names or Numbers list respectively.	string
assetsUrl	relative or absolute URL to the assets folder. Assets folder contains necessary css, images and javascript libraries that make LiveArt HTML5 component work.	URL
galleryBaseUrl	an absolute URL to the folder where artwork gallery is located. This could be useful if you’d like the gallery to reside on different server or folder rather than default one.	URL
getQuoteUrl	a link to a backend service which gets a record with a current design and returns the information about pricing, such as a price per item, discount amount, total price and so on in JSON format.	URL
getDesignsUrl	a link to a backend service which returns the list of saved designs in JSON format.	URL
saveDesignUrl	a link to a backend service which gets the description of design in JSON format, saves it and returns its unique identifier, url, etc.	URL
loadDesignUrl	a link to a backend service which returns a single design using its unique identifier.	URL
redirectUrl	a link to a backend service which places order and redirects user to some another page, for example, shopping cart.	URL
uploadImageUrl	a link to a backend service which uploads user image from local file or URL. After uploading process image is shown on preview area and ready to be moved or resized. Allowed file extensions: *.jpg, *.png, *.gif, *.svg.	URL
shareLinkUrl	this parameter defines the template of the shared link url. Sharing a design calls a saveDesign service that should return an identifier under which design was saved. This id will be replaced in ${design_id} token and presented to user that may copy it and load the design later.	URL
saveTemplateUrl	added in v0.10.27 a link to a backend service which gets the description of template design in JSON format, saves it and returns its unique identifier, url, etc. Used only in “Admin Mode”.	URL
getTemplatesUrl	added in v0.10.27 a link to a backend service which returns the list of available templates (global OR if setuped - for current product only) in JSON format. All templates are preparing in “Admin Mode”.	URL
redirectWindow	window target whne redirecting to redirectUrl. Used for LiveArt inside the iframe. Possible values: “”(default), “parent”, or “top” (same logic as links inside iframe)	string

Options Description

Property	Description	Default
deleteOnDoubleClick	boolean value which defines whether user can remove any object from working area by simple double-click or double tap (for mobile devices).	false
includeProductInDesign	boolean value which defines whether product background image is included into output mockup of the design. Warning: recomended value - true, othervise image will be hidden (display="none"), but some software (e.g. ImageMagic) will ignore this fact. Alternate way — remove manually node with id="productImage"	false
includePrintingAreaInDesign	boolean value which defines whether constraints of area available for printing are included in output mockup of design.	false
includeMaskInDesign	boolean value which defines whether product locations mask are included in output mockup of design. Warning: recomended value - true, othervise image will be hidden (display="none"), but some software (e.g. ImageMagic) will ignore this fact. Alternate way — remove manually node with id="productMask"	false
fontsCSSUrl	URL to the location of fonts CSS definitions that will be available for the user. In default package URL — "/fonts/fonts.css" Used for stand-alone SVG preview (for proper text fonts rendering in browser)	“”
zoomEnabled	boolean value, defines whether zoom tool will be enabled inside designer.
minZoom, maxZoom, zoomStep (optional)	numeric values, defining min, max, and step values for the zoom control respectively, in percents.	50, 150, 10
checkeredBackground	If enabled, shows checkered background where no product background is rendered. The asset for background is located in assets/img/bg-fill.png	true
unit, unit2, unitConversionMult	deprecated in v0.10.30 (but still working solution) Prease refer to Units switcher migration guide units, shown for custom sizes products. Possible values are "in", "ft", and 12 or "cm", "m", and 10 and so on. Use unitConversionMult to indicate respective multiplier for proper conversion of unit to unit2.	“”, “”, 10
defaultUnit optional	added in v0.10.30 units, shown for custom sizes products. Possible values are in, ft, cm, mm, m. All calculations and requests will be in selected units, if not specified in px. Read more on How to configure units switcher?
secondaryUnit optional	added in v0.10.30 possible second units, show only if defaultUnit are set. Possible values are similar to defaultUnit. Read more on How to configure units switcher?
showProductSelector	possible values: true/false. Defines whether Select Product form is shown. If false, make sure you indicate the defaultProductId to preload the product.	true
checkTextFXThrottle	type: milliseconds. A delay in events for typing text, before LiveArt will trigger the server script to obtain new image for certain raster effect.	400
minDPU	Set this property to show warning message if user will size raster image more than safe dimensions to meet suggested print quality standarts. Also this feature requires editableArea and editableAreaUnits (see Product Location Object) for each product location to use this feature (for correct unit/pixel ratio). Warning message is configured in html (‘#dpu-exceeded-popup’). If user ignores such warning and continues design editing - on Place Order will be fired additional pop-up. Also may be re-defined for certain products (see Product Object).	0
showUploadedColorsDialog	Defines whether to show after image upload pop-up with colors choises for uploaded image (default palette and ‘Process Colors’ checkbox). If value == false uploaded images are treated as ‘Process Colors’	true
fitProductImage	If true — product images are fitted and centered in the canvas. Small product images are only centered. Note: also please take into account fitEditableArea property. Added to v0.10.5	false
fitEditableArea	If true — process product.location.editableArea and product.location.clipRect in coordinate system of product image Before v0.10.27: Editable Area coordinates were always binded to canvas dimensions (not product image). Added to v0.10.27	false
enableSnapGuides	If true — enabling snapping objects while dragging to another objects, editable area center or sides. Also helps to set object’s rotation angle to 0°, 90°, 180°, and 270° Added to v0.10.17	true
showSuitableProductColorize	If true — show only actual Current Locations colorizable areas. (e.g. on “Back” location - show only colors from this location) If false — on each location show all colorizable areas list. Works only with multicolor product Added to v0.10.25	false
mergeDesignIdeas	If true — the design ideas and product templates will be merged and all shown under Design Ideas tab for a product If false — the design ideas and product templates will not be merged (same logic as before) Added to v0.10.32	false

LA.config.js

Sample configuration

liveArt.init(document.getElementById('canvas-container'),
    configFile,
    controlsUpdateHandler,
    laOptions);

Default init values

Main purpose of this file - initialization of LiveArt with parameters:

Property	Description	Required
canvas	HTMLElement as placeholder for designer canvases. Strongly recommended to use default value	true
configFile	string URL of config.json; usually depends on backend/admin area configuration	true
controlsUpdateHandler	js function for API callbacks to UI. Strongly recommended to use default value	true
laOptions	object with default init parameters. See more info below	false

Sample configuration

var laOptions = {
    dimensions: [587, 543]
};

laOptions.adminMode = true;
laOptions.defaultDesignId = "design_id_1";
laOptions.defaultProductId = "product_id_1";
laOptions.defaultGraphicId = "graphics_id_1";

laOptions.defaultProductAttributes = {};
laOptions.defaultProductAttributes.sizeUnits = [5, 4];
laOptions.defaultProductAttributes.quantities = [ {size: "XL", quantity: 10} ];
laOptions.defaultProductAttributes.selectedUnit = "in";

laOptions.placeOrderHandler = null;
laOptions.translation = laTranslation.dictionary;

laOptions attributes :

All attributes are optional and provided with their default values

Property	Type	Description
dimensions	array of 2 numbers	default canvas dimensions: [width, height] Default values: [587, 543] See /setup/README.txt in package for information how to change default canvas dimension
adminMode	boolean	Enable “Admin Mode” for preparing templates (both global and product-based)
defaultDesignId	string	Default design to be loaded; usually parsed from GET var
defaultProductId	string	Default product ID to be loaded; usually parsed from GET var Admin Mode Values: none - opens LiveArt without any predefined product. Can be used for creating Design Idea without a locking it to a product. Example: ?admin=true&product_id=none Added in v0.10.33 Note: recommended to use this value instead of config.defaultProductId
defaultGraphicId	string	Default graphics ID to be added after load; usually parsed from GET var
defaultProductAttributes .sizeUnits	array of 2 numbers	default dimensions for resizable products (e.g. Sign 5"x4") in default units. Added to v0.10.25
defaultProductAttributes .quantities	array of objects	Set default quantities for Order; Higher priority over product.minQuantity; Syntax: [{quantity: 30}] - default quantity (total for products without sizes OR for first size) [{size: "S", quantity: 5}, {size: "XL", quantity: 12}] - default quantities for product with sizes list Added to v0.10.5
defaultProductAttributes .selectedUnit	string	Select current unit for resizable products. See defaultUnit and secondaryUnit in config.options Added to v0.10.31
placeOrderHandler	function	optional for overriding default Place Order process function. Default value: null Syntax: function (ordered_design_id: string) { /*custom code here*/ }; Default behavior: Redirect to config.redirectUrl using config.redirectWindow;
translation	object	optional translation dictionary; by default - English. See more at How to add translations to LiveArt Added to v0.10.5
caaMode	boolean	If true - forces Complex Artwork Mode. This attribute is processed only if laOptions.adminMode  === true Syntax: ?admin=true&caa_mode=true Depreated in v0.10.33

All options named defaultNNN (e.g. defaultProductId, defaultProductAttributes, etc.) could be also obtained from GET vars (easiest setup) via build-in helper function getQueryParam(param, type).

Notes:

• objects/arrays (e.g. defaultProductAttributes) should be stringified and URL-encoded
  • ?product_id=41&pa_size_units=%5B30%2C40%5D instead of ?product_id=41&pa_size_units=[30,40]
• browsers may have URI limits (e.g. 2k chars limit in most browsers), ensure you not exceeding it

Data Structures

This section describes JSON data structures of LiveArt resources, such as products, fonts, colors, graphics and text effects.

Products List

Sample mini Products JSON file
(product - not resizable, multicolor, with defined limited colors for color area)

{
  "productCategoriesList": [
    {
      "id": "r1",
      "name": "Clothing",
      "thumb": "products/cool-t-shirt/thumbs/t-shirt-blue.png",
      "categories": [
        {
          "id": "1",
          "name": "Apparel",
          "thumb": "products/cool-t-shirt/thumbs/apparel_cat.jpg",
          "products": [
            {
              "id": "11",
              "categoryId": "1",
              "name": "T-shirt",
              "description": "Sample Colorizable Product with limited colors, and editable area as units values",
              "data": {
                "price": "29",
                "material": "Cotton"
              },
              "thumb": "products/cool-t-shirt/thumbs/t-shirt-blue.png",
              "namesNumbersEnabled": true,
              "multicolor": true,
              "minDPU": 150,
              "minQuantity": 1,
              "locations": [
                {
                  "name": "Front",
                  "image": "products/cool-t-shirt/t-shirt_front.svg",
                  "editableArea": [170,75,410,485],
                  "editableAreaUnits": [4.8,8.2],
                  "clipRect": [170,75,410,485]
                },
                {
                  "name": "Back",
                  "image": "products/cool-t-shirt/t-shirt_back.svg",
                  "editableArea": [170,55,410,485],
                  "editableAreaUnits": [4.8,8.6],
                  "clipRect": [170,75,410,485]
                }
              ],
              "colorizableElements": [
                {
                  "name": "Color",
                  "id": ".bg.fill",
                  "colors": [
                    {
                      "name": "White",
                      "value": "#FFF"
                    },
                    {
                      "name": "Black",
                      "value": "#000"
                    },
                    {
                      "name": "Steel Blue",
                      "value": "#4682B4"
                    }
                  ]
                }
              ],
              "sizes": ["XS","S","M","L","XL","XXL","XXXL"]
            }
          ]
        }
      ]
    }
  ]
}

The JSON object that is returned by this link should have the following tree-like structure. The root node of this tree is productCategoriesList — the array of category objects. See description of a category object below.

Category

A category may be nested if necessary and thus include either child categories or products.

Attribute	Description	Type	Required
id	unique identifier of category object, used for internal needs.	string	yes
name	name of category, visible to the end user.	string	yes
thumbUrl	deprecated in 0.10.27	string	no
thumb	added in 0.10.27 path or URL of the category thumbnail	string	no
categories	a nested list of categories, if present	string	no
products	list of product objects (see description below).	array	no

Product

Product is perhaps one of the most complex objects in LiveArt, presenting numerous options of usage that can be combined. The child objects like Locations, Colors and ColorizableElements are described later in this section.

Attribute	Description	Type	Required
categoryId	unique identifier of category to which belongs the product.	string	yes
colorizableElements	indicates list of elements of the product that can be colorized, e.g. uniform or multiple panel products. Works same as colorizableElements for artwork gallery.	structure	no
colors	list of available colors for the product. See description of color object below. If the list is not indicated, the product is considered as non-colorizable.	array of color objects	no
data	arbitrary object with additional product fields to pass to front-end, e.g. material, cost, etc.	object	no
description	description of product, visible to the end user.	string	no
hideEditableAreaBord​er	If true, the printable area border is not rendered.	boolean	no
id	unique identifier of product object, used for internal needs.	string	yes
locations	list of available locations for the products (for example, front, back and so forth). See description of location object below.	array	yes
minDPU	overrides general config property for certain product. Refer to config option description for more information	number	no
minQuantity	set the minimal order quantity for current product. Default value is 1. If total quantity is less — Order button is blocked with informational tooltip.	number	no
multicolor	whether product can be colorizable. This requires special SVG image of product to be prepared in a same way as multicolor artwork and colorizableElements to be indicated	boolean	no
name	name of product, visible to the end user.	string	yes
namesNumbersEnabled	enable tab for adding names and/or numbers placeholders to design, and fill appropriate table	boolean	no
pantones	added in v0.10.14 object to override default pantones setting from config. Sample: { "useForDecoration": false, "useForProduct": false } (useForDecoration — enabling/disabling pantones for the art, useForProduct — enabling/disabling pantones for colorizing multicolor product )	object	no
resizable	defines whether the product dimensions can be changed by user. Setting this to true is typical for products like business cards, signs or banners. Available in 2 modes: User input mode (see details below) Predefined values - see option editableAreaSizes description User input mode has some peculiar properties: editableAreaUnits — is an optional location attribute, but for resizable products becomes required; default size will be taken from editableAreaUnits; one may additionally setup default product size via defaultProductSize attribute in main configuration file; all product location should have same size; if resizable product has more than one location object, editableAreaUnits are required only for first location in list; other loation’s editableAreaUnits will be ignored.	boolean	no
editableAreaSizes	defines preselected possible sizes for user, works only if resizable attribute is true. Sample definition: "editableAreaSizes":[{"label":"2x2in", "width":2, "height":2}] Note: this option ignores editableAreaUnits, editableAreaUnitsRan​ge, and editableAreaUnitsRestrictRotation options in product.location	object	no
showRuler	indicates whether ruler should be shown. Depends on editableAreaUnits values for each location (becomes obligatory attribute). Default value: false.	boolean	no
sizes	list of available sizes for certain product. Type: array. If not indicated, only Quantity field will be rendered on the checkout panel.	array	no
template	deprecated in v0.10.30 See migration guide in Product Templates KB article.	string	no
thumbUrl	deprecated in v0.10.27 Use thumb instead.	string	no
thumb	added in 0.10.27 URL to thumbnail image (allowed file extensions: *.jpg, *.png, *.gif, *.svg, dimensions: 110px x 110px) which will be shown in the products catalog.	string	yes
defaultTemplateId	added in v0.10.30 ID of the template to be loaded by default	string	no

Location

JSON representation of product location which contains the following properties:

Attribute	Description	Type	Required
name	name of location, visible to the end user.	string	yes
image	url to background image (allowed file extensions: *.jpg, *.png, *.gif, *.svg) of the product for the current location.	string	yes
mask	url to the mask image, that will be applied to the product background image. If config option includeMaskInDesign is true — included into output design svg file.	string	no
overlayInfo	url to the image with additional location graphical markup (safe, trim, print areas, additional comments). This image is not included into svg design output.	string	no
editableArea	list of 4 number that represent coordinates of top left (first two numbers) and bottom right points (last two). On design is rendered as rectangle; if config option includePrintingAreaInDesign is true, editable area is included into output design svg file. Default values: canvas width and height.	array	no
editableAreaUnits	list of 2 number that represent width and height of editable area in real-life units, e.g. millimeters or inches. NOTE: Is required for product with "resizable": true attribute. If such product has more than one location, editableAreaUnits of not first location are ignored.	array/numbers	no
editableAreaUnitsRan​ge	this sets min/max ranges and steps for dimensions of resizable product. Example:"editableAreaUnitsRan​ge": [[5, 150, 1],[5, 100, 1]], where [min, max, step (optional, default = 1)]. Note: By default max value is used for longer side, not width only	array	no
editableAreaUnitsRestrictRotation	If true set product max width value from first array and height — value from second array respectively from editableAreaUnitsRan​ge. Default value: false	boolean	no
clipRect	list of 2 coordinates for top left and bottom right corners of clipped area. It is very handy to copy these from editableArea if the design should be cropped at the sides of editableArea.	array	no

Color

JSON representation of product color which contains the following properties:

Attribute	Description	Type	Required
name	name of color, visible to the end user.	string	yes
value	hexadecimal value of color.	string	yes
location	list of locations for which this color is available. Used only for products with "multicolor": false attribute Each object in location array consist of properties:	array	no

	name	name of location for which current color is available. If name is invalid — image will be used for product location with the same index	string	yes
	image	url to background image (allowed file extensions: *.jpg, *.png, *.gif, *.svg) for current location and color	string	yes
	mask	optional url to mask image (allowed file extensions: *.jpg, *.png, *.gif, *.svg) for current location and color	string	no

Fonts List

Fonts JSON structure example

{
    "fonts": [
        { "name": "Action", "fontFamily": "Action Man", "ascent": 22, "vector": "fonts/Action-Man/Action_Man.font.js" },
        { "name": "Arial", "fontFamily": "Arial", "ascent": 23, "vector": "fonts/Arial/Arial.font.js" },
        { "name": "Bebas Neue", "fontFamily": "Bebas Neue", "ascent": 23, "boldAllowed": false, "italicAllowed": false, "vector": "fonts/Bebas-Neue/Bebas_Neue.font.js"},      
        { "name": "Capture It", "fontFamily": "Capture it", "ascent": 23, "boldAllowed": false, "italicAllowed": false, "vector": "fonts/Capture-It/Capture_It.font.js"},
    ]
}

The JSON object that is returned by fonts service should have main fonts node with the following properties:

Attribute	Description	Type	Required
name	name of font, visible to the end user. The name will be automatically written with the font.	string	yes
fontFamily	name of typeface that is used by this font.	string	yes
ascent	should be indicated, as height in pixels for 32pt font size. This parameter is essential for calculating correct measurements in resizable products and size-sensitive price calculations. Normal values are 22-29.	number	no
boldAllowed, italicAllowed	if false, disables respective control. Usable if font does not have bold or italic typefaces.	boolean	no
vector	vector representation of the font glyphs for vector text effects. Can be obtained by running the font through http://cufon.shoqolate.com/generate/ tool.	path,URL	no

Colors List

Colors JSON example

{
  "colors": [
      { "name": "Black", "value": "#000000" },
      { "name": "Dim Gray", "value": "#696969" },
      { "name": "Gray", "value": "#808080" },
      { "name": "Silver", "value": "#C0C0C0" },
      { "name": "White", "value": "#FFFFFF" }
    ]
}

The JSON object that is returned by this link should have the following properties:

Attribute	Description	Type	Required
name	name of color, visible to the end user.	string	yes
value	hexadecimal value of color.	string	yes

Graphics List

Graphics JSON example

{
  "graphicsCategoriesList": [{
      "id": "r1",
      "name": "Animals",
      "thumb": "gallery/raster/thumbs/crab.png",
      "categories": [{
          "id": "1",
          "name": "Raster",
          "thumb": "gallery/raster/thumbs/crab.png",
          "graphicsList": [{
              "id": "11",
              "categoryId": "1",
              "name": "Crab",
              "description": "crab",
              "colors": "-1",
              "thumb": "gallery/raster/thumbs/crab.png",
              "image": "gallery/raster/crab.png"
          }]
        }, {
          "id": "4",
          "name": "Multicolor",
          "thumb": "gallery/Icons/multicolor/png/butterfly.png",
          "graphicsList": [{
              "id": "42",
              "categoryId": "4",
              "name": "Lion",
              "description": "lion",
              "multicolor": true,
              "thumb": "gallery/Icons/multicolor/png/lion.png",
              "image": "gallery/Icons/multicolor/svg/lion.svg",
              "colorizableElements": [{
                  "name": "Muzzle",
                  "id": ".muzzle.fill",
                  "colors": [
                    { "name": "Yellow", "value": "#F4EB21" },
                    { "name": "Green", "value": "#69F946" }
                  ]
                },
                {
                  "name": "Mane",
                  "id": ".mane.fill",
                  "colors": [
                    { "name": "Orange", "value": "#FAA744" },
                    { "name": "Dark Red", "value": "#600308" }
                  ]
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

The JSON object that is returned by this link should have the following tree-like structure. The root node of this tree is graphicsCategoriesList — the array of root graphic category objects. Each category has its categories list or graphics list, represented by Graphic Object.

Graphic Object

The artwork can be in the following web formats: JPG, GIF, PNG or SVG. For best vector representation we recommend using SVG format. You can easily export your vector grahics into SVG from Adobe Illustrator or CorelDraw.

JSON representation of graphics, contains the following properties:

Attribute	Description	Type	Required
id	unique identifier of product object, used for internal needs.	string	yes
categoryId	unique identifier of category to which belongs the image.	string	yes
colors	number of colors, present in the image. This will be used for correct get quote request if decoration price depends on number of colors (e.g. screenprinting). Type: string or array of strings. Possible values: "-1" — process colors is required, e.g. if the graphic is photo; "0" — default value (need graphic to be "colorize": true and get colors information from selected fill color/outline/multicolor layers); integer (e.g. "5") — number of unique graphic colors; array of hex web colors (e.g. ["#FFFFFF", "#000000"]) — list of colors for accurate counting (in case of "multicolor" : true - added to colors list)	mixed (string, array of strings)	no
colorize	acceptable values: true, false. This optional attribute tells designer whether the image can be colorized by user. Please note that this option works with SVG images only. Default value: false.	boolean	no
colorizableElements	list of colorizable layers inside the SVG image. Please look for applicable samples of such SVG images inside your development package.	array of objects	no
description	short description of the image, visible to the end user.	string	no
multicolor	acceptable values: true, false. Optional attribute for indicating whether artwork can be colorized in multiple layers. Works in conjunction with colorizableElements attribute and mutually exclusive with colorize. Default value: false.	boolean	no
thumb	url to thumbnail image (allowed file extensions: *.jpg, *.png, *.gif, *.svg, dimensions: 110px x 110px) which will be shown in the graphics catalog.	string	no
image	url to the full size image (allowed file extensions: *.jpg, *.png, *.gif, *.svg) which will be shown at the preview area.	string	yes

Text Effects List

Example

{
  "textEffects": [
    { "name": "curveUp", "label": "Curve Up", "fxName": "arc", "paramName": "Angle", "paramValName": "a", "min": 10, "max": 360, "step": 5},
    { "name": "curveDown", "label": "Curve Down", "fxName": "arc", "paramName": "Angle", "paramValName": "a", "min": -10, "max": -360, "step": 5},
    { "name": "archUp", "label": "Arch Up", "fxName": "vectorArchUp", "paramName": "Angle", "paramValName": "a", "min": 0, "max": 1, "step": 0.1},
    { "name": "archDown", "label": "Arch Down", "fxName": "vectorArchDown", "paramName": "Angle", "paramValName": "a", "min": 0, "max": 1, "step": 0.1},
    { "name": "simpleWave", "label": "Simple Wave", "paramName": "Wave", "paramValName": "d", "min": 0.1, "max": 1, "step": 0.1},
    { "name": "widen", "label": "Widen", "paramName": "Distort Level", "paramValName": "d", "min": 0, "max": 1, "step": 0.1},
    { "name": "wedge", "label": "Wedge", "paramName": "Distort Level", "paramValName": "d", "min": 1, "max": 2, "step": 0.1},
    { "name": "pinch", "label": "Pinch", "paramName": "Pinch Level", "paramValName": "d", "min": 0, "max": 1, "step": 0.1},
    { "name": "bulge", "label": "Bulge", "paramName": "Bulge Level", "paramValName": "d", "min": 1, "max": 2, "step": 0.1},
    { "name": "slantLeft", "label": "Slant Left", "paramName": "Slant Level", "paramValName": "d", "min": 0, "max": 1, "step": 0.1},
    { "name": "slantRight", "label": "Slant Right", "paramName": "Slant Level", "paramValName": "d", "min": 1, "max": 2, "step": 0.1},
    { "name": "slantUp", "label": "Slant Up", "paramName": "Slant Level", "paramValName": "d", "min": 1, "max": 2, "step": 0.1},
    { "name": "slantDown", "label": "Slant Down", "paramName": "Slant Level", "paramValName": "d", "min": 0, "max": 1, "step": 0.1}
  ]
}

Text FX is an experimental flexible feature that was added to LiveArt HTML5 allowing users to apply a number of effects on the text. Default effects are vector and not require ImageMagick (starting 0.10.24).

Attribute	Description	Type	Required
name	unique identifier of the effect	string	yes
label	label for the effect as it will appear to the user.	string	no
fxName(optional)	working name of the effect if different to name or label. Is used in the script	string	no
paramName	title of the effect parameter as it will appear for user, e.g. “Distort”, “Angle”	string	yes
paramValName	working name of the effect parameter, used if different to paramName.	string	yes
min/max	numeric values for respective min and max of the effect parameter. The parameter will be rendered to user as slider control.	number	yes
step	numeric step value for effect parameter control.	number	yes

Effects List:

• Vector effects:
  • Curve Up/Down
  • Arch Up/Down (added in 0.10.25)
  • Wave
  • Widen/Wedge (added in 0.10.25)
  • Pinch/Bulge (added in 0.10.25)
  • Slant Left/Right/Up/Down (added in 0.10.25)
• Raster effects (deprecated in 0.10.24)
  • Arch Up/Down
  • Inflate
  • Perspective
  • Wave

Package Structure

LiveArt JS (HTML5) is a Javascript application which uses allows user add text or image objects to stage and manipulate them with mouse or gestures on tablets. A number of Javascript technologies are used and part of the code is open to modifications.

Please note that a particular package which may be released to you may differ in its files or features if you have also ordered custom modifications to original software. Contact LiveArt team to obtain specific details pertaining your package.

Once unpacked, the LiveArt JS package consists of the following structure (subject to change).

/index.html

Main page containing the designer. This can be used as base or embedded with an iframe into your website or ecommerce application.

/LiveArtJS.js

The core LiveArt JS code, copyrighted and protected from unauthorised access. This particular library is locked to your website domain for protection when launched on production.

/LA.js

The Knockout controlling scripts for the designer page. You can edit these scripts (but not recommended to do so) to amend the logic of specific designer elements or behavior by yourself. Please note that since the code is copyrighted you cannot redistribute it withouth LiveArt consent.

/LA.config.js

version: 0.10.5+
Seperated from LA.js configuration for more easier LA.js support. Used to:

• override canvas dimension (see /setup/README.txt for more details)
• default product/design/graphic parsing from GET vars
• custom place order handler
• added in v0.10.10 core translation dictionary (see usage manual on KB: How to add translations to LiveArt)

/assets

The folder contains Bootstrap files, required for designer running, images and additional libraries.

/config

Main LiveArt JS configuration files. The format of the files is JSON.

/fonts

The folder with fonts, which you can add to designer along with fonts.css fonts declaration file.

/files

version: 0.10.27+
Default folder for saving designs. Package contains sample design templates (global and product-related) — also called “Design Ideas”.

/gallery

Artwork graphics gallery. Please note that graphics added here should be also referred in respective JSON configuration file.

/lib

Additional low-level core Javascript libraries handling designer. This folder also contains standard libraries such as Knockout and JQuery.

/products

Demo products images and thumbnails.

/setup

version: 0.10.2+
LiveArt setup scripts. Read README.txt inside for more information.

Errors and Debugging

Developing a backend integration for LiveArt HTML5 will always require debugging and looking for errors. Below are brief recommendations that will facilitate the development process.

• Use Net/Network tab of your favorite browser extensively to monitor what requests and responds are going through your integration;
• Use Fiddler to capture and manipulate sessions and measure performance;
• Look into Console each time you encounter a missing functionality;