Creating your own configuration

Great, installed cardkit and are ready to create your first configuration object.

A configuration object consists of two main properties, card and layers.

card (Object)

card.width (number)

The width of your image

card.height (number)

The height of your image

card.fill (string)

The base background colour

layers (object)

The layers object consists of other objects that define individual layers to render on the image (e.g. text, shapes, lines and images). Each layer object is made up of standard SVG properties, however there are also a number of custom properties.

As well as the values defined below, you can also use a JavaScript getter or a function to return the value of the property. If using a getter, this will be other properties in the layer, which can be useful if you want to change the line height based on its font size. If using a function, the first argument will be all of the defined layers, allowing you to change a value based on the value of a property of another layer. This can be helpful if you need to change the position of one layer based on the size of another.

Below is a list of the most common properties, along with CardKit's custom properties:

name (string)

The name of the property, used when building the UI

type (string)

The type of element this should be. Options: text, image, rectangle, circle, ellipse, line and path

hidden (boolean)

Whether or not the element should be visible on the image (this will also hide it in the UI if using CardKitDOM)

height (int)

The height of the element

width (int)

The width of the element

x (int or string)

The x position, can be an integer (measured in pixels) or a string (e.g. '20%')

y (int, string or object)

The y position, can be an integer (measured in pixels) or a string (e.g. '20%'). Alternatively, you can provide an object to attach it to another layer (that must have been defined prior to this one). See below for details of y as an object.

y (object)

Attaches this element to another element on the Y axis

y.attach (string)

The name of the element to attach to

y.offset (integer)

The Y offset value of the attachment (e.g. -10 or 100)

draggable (bool)

Whether this element should be draggable

editable (object)

Tells CardKit which attributes to make editable, defining the UI for this element if CardKitDOM is used. The property names for this object should correlate to the properties that define the element, and their values should be true if you want that property to be editable. There are a number of unique cases where you can provide other values to alter the UI output.

Element specific attributes

Text: fontSize (integer)

The font size to use for this layer.

Text: lineHeight (integer)

The line height of the text, defaults to the value of fontSize.

Text: fontWeight (string)

Either the numeric value of the font weight (e.g. '400') or the string representation (e.g. 'bold')

Text: useAsFilename (bool)

Uses the text value of this element as the filename when downloading.

Text: smartQuotes (bool)

Renders smart / curly quotes instead of straight quotes when set to true.

Image: preserveAspectRatio (string)

Describes the aspect ratio of images, see MDN for more details on this SVG property

Templates, Themes and Layouts

CardKit 2 introduces the concepts of Templates, Themes and Layouts, each of which serve a different purpose, but are passed into CardKit when you initialise it, as follows:

new CardKit(configuration, {
  templates: {}, // Templates typically change the overall contents of the image, allowing you to create different types of images
  themes: {}, // Themes typically change colours and fonts, presentational attributes
  layouts: {} // Layouts typically change the size and shape of an image (e.g. Facebook, Twitter and Instagram)
});

Each of these are an object of other objects that override properties defined in your layers object. Overrides happen in the order defined above, first templates get merged onto the base configuration, then themes get merged onto the output of that, and layouts finally onto the output of that.

Below is an example that changes the size of the images.

new CardKit({
  card: {
    fill: '#333333'
  },
  layers: {}
}, {
  layouts: {
    Twitter: {
      card: {
        width: 1000,
        height: 400
      }
    },
    Facebook: {
      card: {
        width: 1000,
        height: 600
      }
    },
    Instagram: {
      card: {
        width: 1000,
        height: 1000
      }
    }
  }
});

To use this, when using CardKit.getConfiguration() the first argument is an object optionally containing a template, theme and layout to render with, as follows:

cardkit.getConfiguration({
  layout: 'Instagram'
});

The above would produce a configuration object with a width of 1000, and a height of 1000.