NAV Navbar
Logo
Sample code

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:


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

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:



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:
  1. none - opens LiveArt without any predefined product. Can be used for creating Design Idea without a locking it to a product.
    1. Example: ?admin=true&product_id=none
    2. 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:
  1. [{quantity: 30}] - default quantity (total for products without sizes OR for first size)
  2. [{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:

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:

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:

/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.