Renderer

You have created a seating chart, you created an event for it. Great, you’re ready to show the seating chart to your users.

How to embed a floor plan

To show a floor plan to your user, you need to do the following:

  1. add an empty div to your page and give it an id (‘chart’ is a good choice)
  2. load https://app.seats.io/chart.js
  3. create a new seatsio.SeatingChart object, configure it and call its render() method

So in short: just copy & paste this code snippet and adapt it to your needs.

<div id="chart"></div>

<script src="https://app.seats.io/chart.js"></script>
<script>
    new seatsio.SeatingChart({
        divId: 'chart',
        publicKey: '[your public key]',
        event: '[your event key]'
    }).render();
</script>

Also, note that you can use our demo page to test your code.

Configuring your floor plan

The Renderer supports a long list of configuration options you can use to tweak your floor plan’s appearance and behaviour.

As a minimal configuration, you need to provide 3 options: divId, event and publicKey.

new seatsio.SeatingChart({
    divId: 'chart',
    event: '[your event key]',
    publicKey: '[your public key]'
}).render();

divId

Type: string

The id of the div on your page in which you want seats.io to render the seating chart. This is a required config option.

divId: 'chart'

event

Type: string

The key of the event for which you want to render the seating chart.

event: 'event1'

events

Type: array of strings

The key of the events for which you want to render the seating chart. Useful to implement season tickets functionality. If an object is booked for one (or more) events in the list, it will show up as booked for the ‘season’.
Cannot be used together with the ‘event’ parameter, which is obviously not a required parameter when ‘events’ is provided.

events: ['event1', 'event2', 'event3']

publicKey

Type: string
Your public key. You can find it on your Settings page.

pricing

Type: array of objects
Default: []

Pricing per category. Read more about pricing categories and ticket types here.

pricing: [
    {'category': 1, 'price': 30},
    {'category': 2, 'price': 40},
    {'category': 3, 'price': 50}
]

pricing: [
    {'category': 1, 'ticketTypes': [
        {'ticketType': 'student', 'price': 10},
        {'ticketType': 'normal', 'price': 20}
    ]},
    {'category': 2, 'ticketTypes': [
        {'ticketType': 'student', 'price': 20},
        {'ticketType': 'normal', 'price': 30}
    ]}
]

priceFormatter

Type: function(price)
Default implementation: the raw price (number or string)

A function that formats a price when it’s shown to an end user.
This function is executed in the context of your page, meaning you can use a library like accounting.js in your implementation.

priceFormatter: function(price) {
    return '$' + price;
}

selectedObjects

Type: array<string>
Default:[]

Select the specified objects. You can pass object UUIDs or labels inside the array.

tooltipsOffsetX

Type: number
Default: 15

Horizontal offset for the tooltip.

tooltipsOffsetY

Type: number
Default: 15

Vertical offset for the tooltip.

tooltipText

Type: function(object)
Default: the object id, with pricing info if provided.

A function whose result is the text that will be displayed in the tooltip for an object.

tooltipText: function(object) {
    if (object.status !== 'free') {
        return 'not free, sorry!';
     } else {
        return 'yep, can select it';
     }
}

tooltipStyle

Type: string

With this option you can override the default styling of the tooltips of a rendered chart. Just pass in a CSS string.

tooltipStyle: 'color: green; background-color: red'

language

Type: string
Default: en

The language for built-in tooltip texts in seats.io. Currently supported languages are English (“en”), Dutch (“nl”), French (“fr”), Spanish(“es”), Portuguese(“pt”), German (“de”), Danish (“da”) and Polish (“pl”).

There’s more information in our cookbook.

messages

Type: object

The messages parameter allows you to change all kinds of texts that are displayed on the chart: section labels, tooltip texts, static text objects …
you name it. Just pass in an object with the original texts as keys, and the translations as values.

There’s more information in our cookbook.

messages: {
    'STAGE': 'Podium',
    'ORGAN': 'Orgue'
}

priceLevelsTooltipMessage

Type: string

The message that’s shown above the price levels, when clicking on an object that has multiple price levels (e.g. child and adult).

maxSelectedObjects

Type: number or array of objects
Default: not set

Limit the number of objects a user can select.

When using a number X, the user will be able to select a max of X objects in general.

maxSelectedObjects: 5

You can also provide an array of objects, to limit the number of selectable objects per ticket type. For an explanation about ticket types, please refer to here.

maxSelectedObjects: [
    { ticketType: 'adult', quantity: 2 },
    { ticketType: 'child', quantity: 3 }
]

And you can also limit per category.

maxSelectedObjects: [
    { category: 'balcony', quantity: 4 },
    { category: 'stalls', quantity: 5 }
]

Important note: you should also validate this server side; a somewhat clever user can change this value right from the browser to bypass the validation.

selectedObjectsInputName

Type: string
Default: not set

The name of the hidden input field that contains the IDs of the selected objects. It will be created automatically - you should not create the input field yourself. That way, you can retrieve the selected objects on the server side after the ticket buyer’s form was submitted.

selectedObjectsInputName: 'chosenTickets'

unavailableCategories

Type: array of strings
Default: []

An array of category keys (e.g. [‘1’, ‘2’]). Use this if you want to disable selection of seats per category.

Important note: you should also validate this server side; a somewhat clever user can change this value right from the browser to bypass the validation.

objectColor

Type: function(object, defaultColor, extraConfig)
Default: Grey if the object is not available for selection, the category color otherwise.

A function that determines the object color. Can be based on object.status, object.category, object.isSelectable() or on other criteria. By default, selectable objects are shown in their category color, and other objects are rendered grey. objectColor must return a CSS string (e.g. ‘red’ or ‘#ccc’).

The parameters that are passed to objectColor are:

Warning: this function is called for each object on the chart; make sure it’s fast, or chart rendering times will suffer.

objectColor: function(object, defaultColor, extraConfig) {
    if(object.category.label === 'Ground Floor') {
        return 'red';
    }
    return defaultColor;
}

sectionColor

Type: function(section, defaultColor, extraConfig)
Default: The category color of the section, or grey if no category has been assigned.

A function that determines the section color. Must return a CSS string (e.g. ‘red’ or ‘#ccc’).

The parameters that are passed to sectionColor are:

sectionColor: function(section, defaultColor, extraConfig) {
    if(section.label === 'Section 1') {
        return 'red';
    }
    return defaultColor;
}

objectLabel

Type: function(object, defaultLabel, extraConfig)
Default: no label

A function that determines the label that’s rendered inside an object on the chart. Can be based on object.status, object.category, object.isSelectable() or on other criteria. By default, no label is shown.

The size of an object label is calculated automatically, based on the size of the object. For tables and booths, there usually is more than enough space. For seats, however, you’ll probably want to limit the label to 3 characters max, or else the label will become too small to read without zooming in.

Multi-line labels are not supported.

The parameters that are passed to objectLabel are:

Warning: this function is called for each object on the chart; make sure it’s fast, or chart rendering times will suffer.

objectLabel: function(object, defaultLabel, extraConfig) {
    return object.label;
}

objectIcon

Type: function(object, defaultIcon, extraConfig)
Default: no icon

Allows you to show an icon within a seat or other object.

We’re using FontAwesome (version 4.7.0). objectIcon should be a function that returns the name of an icon, check the full list of available icons.

objectIcon can be based on object.status, object.category, object.isSelectable() or on other criteria.

The size of the icon is calculated automatically, based on the size of the object.

The parameters that are passed to objectIcon are:

Warning: this function is called for each object on the chart; make sure it’s fast, or chart rendering times will suffer.

objectIcon: function(object) {
    if(object.category.label === 'Wheelchair') {
        return 'wheelchair'; // use any icon name from fontawesome v 4.7.0
    }
    return null;
}

isObjectSelectable

Type: function(object, defaultValue, extraConfig)

A function that should return true if an object is selectable, and false otherwise. Can be based on object.status, object.category, or on other criteria.

Whether an object can be selected by the user is determined as follows:

  1. if the category of the object is inside the unavailableCategories array, the object is not selectable
  2. else, if an isObjectSelectable function is passed to the chart, the return value of that function determines if the object is selectable
  3. else, the object is selectable if it’s status is free or if it’s reserved by the current user.
  4. else, the object is not selectable

The parameters that are passed to isObjectSelectable are:

Warning: this function is called for each object on the chart; make sure it’s fast, or chart rendering times will suffer.

isObjectSelectable: function(object, defaultValue, extraConfig) {
    if(object.category.label === 'Ground Floor') {
        return true;
    }
    return defaultValue;
}

isObjectVisible

Type: function(object, extraConfig)

A function that should return true if an object is visible, and false otherwise. When an object is invisible, it can’t be selected or interacted with. Can be based on object.type, object.status, object.category, or on other criteria.

The object types that can be made invisible are: ‘seat’, ‘table’, ‘booth’, ‘generalAdmission’ and ‘section’. By default, all objects are visible.

The parameters that are passed to isObjectVisible are:

Warning: this function is called for each object on the chart; make sure it’s fast, or chart rendering times will suffer.

isObjectVisible: function(object, extraConfig) {
    if(object.category.label === 'Ground Floor') {
        return true;
    }
    return false;
}

selectBestAvailable

Type: object

Automatically pre-select the best available objects (and deselect already selected objects).

The object you pass in must contain the number of objects to select, and can have an optional category key or label, to auto select only objects in that category.

This works for seats in rows, seats of tables and for whole tables (if ‘book whole tables’ is enabled for the event). For now, general admission areas or booths are not included.

selectBestAvailable: {
    number: 2,
    category: 'Stalls' // optional
}

showRowLines

Type: boolean
Default: true

Set to false to avoid the connector lines between seats of the same row being drawn.

reserveOnSelect

Type: boolean
Default: false

Set this to true to enable temporarily reservation upon object selection.

If set to true, the user’s browser issues a call to seats.io to reserve the selected object for 15 minutes (or whatever you set on your settings page). Other users won’t be able to book the same object within that period.

If the object is not booked (e.g. payment has never been received) within those 15 minutes, it’s automatically released again.

Note that it’s also possible to call our API directly to reserve objects.

regenerateReservationToken

Type: boolean
Default: false

When reserveOnSelect is enabled, a reservation token is generated and saved in the session storage of the browser. The token is passed to seats.io when reserving or unreserving objects - to prevent other users from reserving or unreserving the same objects.

If ‘regenerateReservationToken’ is false, a new token will be generated only once, when the chart is loaded for the first time. If the form containing the chart is submitted, and it’s shown again (e.g. due to validation errors) the same reservation token stays in session storage.
If ‘regenerateReservationToken’ is true however, a new token will be generated when the chart is shown, even if a token already exists. This is the case when starting a new registration flow. Read more here.

reservationTokenInputName

Type: string
Default : empty

The name of the hidden input field that contains the reservation token. Only makes sense when ‘reserveOnSelect’ is enabled. It will be created automatically - you should not create the input field yourself.
The reservation token is needed to definitively book seats that were temporarily reserved. It must be supplied as a parameter to /book, /release and /changeStatus requests for reserved objects.

Alternatively, you can get hold of the reservation token from your javascript: chart.reservationToken also contains the generated reservation token - so you don’t need the hidden form field generated by supplying reservationTokenInputName.

reservationToken

Type: string
Default: empty

Safari private mode does not allow data to be saved in session storage. That means that the reservation token, which is normally saved in the session storage, is gone after a page refresh. Typically this is when the ticket buying form is submitted but there are validation errors.
So if your users are using Safari in private mode, you have to provide the submitted reservation token yourself when rendering the chart after a page refresh. The reservationToken configuration parameter is meant for that.

useObjectUuidsInsteadOfLabels

Type: boolean
Default: false

Set to true to get UUIDS instead of labels in the hidden form field that contains the selected seats.
When booking and releasing objects, you have two options to identify those objects: by their label or by their object UUID.

You can set the label yourself in the chart designer; for seats, it’s composed of the row label and the seat label, e.g. B-45. For other kinds of objects, there’s no row label, but only an object label.

The big disadvantage of labels is that they sometimes change. Suppose for example that a customer booked seat B-45. If you later rename that seat to BB-45, the seat will appear free again on the chart.

To avoid those situations, you can instead use a UUID when booking. The UUID never changes, even when renaming objects.

showLegend

Type:’boolean’
Default:’false’

If true, a legend with the category names and colors is rendered at the top of the chart.

multiSelectEnabled

Type:’boolean’
Default:’false’

If true, users can select multiple seats at once by holding shift, clicking and dragging.

multiSelectEnabled works together with multilevel pricing:

showMinimap

Type:’boolean’
Default:’true’

When zoomed in on a chart with sections, a minimap is shown so ticket buyers have a better sense which seats they’re looking at. You can hide this minimap by passing showMinimap: false.

allowOrphanSeats

Type:’boolean’
Default:’true’

By default, ticket buyers are allowed to leave empty spaces between selected seats. allowOrphanSeats: false prevents this from happening. Ticket buyers will only be able to select seats next to already selected or booked seats.

objectCategory

Type: function
Default: not implemented

The objectCategory function allows the default category of an object to be overridden. It takes a number of parameters:

objectCategory must return a category object, either one retrieved from categories, or the defaultCategory.

objectCategory: function(object, categories, defaultCategory, extraConfig) {
    if(object.label === 'A-1') {
        return categories.get('Stalls');
    }
    return defaultCategory;
}

extraConfig

Type: object
Default: {}

The objectColor, sectionColor, isObjectSelectable, objectCategory and isObjectVisible callbacks do not have access to variables defined in your web page. That’s because they’re executed inside the seats.io iFrame.
With extraConfig, you can pass in an object to which the callbacks do have access. It’s passed to them as the last parameter.

mode

Type: string
Default: ‘normal’

This parameter supports three values:

loading

Type: string
Default: ‘normal’

This parameter allows you to override the default seats.io spinner that is shown while the floor plan is being loaded. The value can contain (valid) html, like so:

var chart = new seatsio.SeatingChart({
        divId: "chart",
        ...
        loading: "<div class='loader'>Loading...</div>"
});

Note that the loader css class in the above example can be defined in the styling of your own page.

React to Events

When integrating an objecting chart in your page, you can react to certain events that get fired by chart.js (e.g. when a user clicks on an object). This is useful when you want to do things like update a shopping cart or do custom validation.

To react to these events, just implement a js function and pass it as an option to seatsio.SeatingChart(), exactly like the options described earlier.

new seatsio.SeatingChart({
    divId: 'chart',
    publicKey: '[your public key]',
    event: '[your event key]',
    onObjectSelected: function(object){
        console.dir(object);
    }
}).render();

onChartRendered()

Fired after the seating chart is fully rendered. The rendered chart is passed in as a parameter.

onObjectClicked(object)

Fired when the user clicks on an object, even if that object is not selectable.

onObjectSelected(object, selectedTicketType)

Fired when the user selects an object. selectedTicketType is only passed when using multi-level pricing. The object contains a price and a ticketType property.

onObjectDeselected(object, selectedTicketType)

Fired when the user de-selects an object. selectedTicketType is only passed when using multi-level pricing. The object contains a price and a ticketType property.

onObjectMouseOver(object)

Fired when the user hovers an object.

onObjectMouseOut(object)

Fired when the user unhovers an object.

onSelectedObjectBooked(object)

Fired when the user has selected an object that gets booked by another user.
You can use this to pop up a warning to your user.

onBestAvailableSelected(array_of_objects)

Fired when best available objects are successfully selected

onBestAvailableSelectionFailed()

Fired when no best available objects could be found (because there are not enough objects selectable)

onScrolledOutOfBoundsVertically(amount)

By default, when users try to scroll a chart out of bounds vertically, seats.io scrolls the host page instead. This is especially useful on mobile devices.

There are some edge cases in which this scrolling does not work out of the box. Suppose that you include the seats.io iFrame inside another iFrame. Then seats.io will try to scroll the iFrame instead of the host page, which obviously does not work.

To solve this, you can implement an onScrolledOutOfBoundsVertically callback, an take care of the host page scrolling yourself. The amount that’s passed in is the number of pixels the user scrolled out of bounds. Positive means down, negative means up.

Note: the default implementation that we use is
window.scrollBy(0, amount)

onScrolledOutOfBoundsVertically: function(amount) {
    window.parent.postMessage({
        type: 'seatsioScrolledOutOfBoundsVertically',
        amount: amount
    }, '*');
}

Object Properties

Most event handling functions take an object as parameter (e.g. the object the user moved her mouse over). The properties available on these objects are:

Rendered chart properties

A rendered chart has some properties you can access. Well, one for now:

var chart = new seatsio.SeatingChart({...}).render();
// ... user selects objects ...
console.log(chart.selectedObjects);

Rendered chart functions

You have a number of functions you can use to interact with a rendered seating chart. You can invoke these functions in two ways:

var chart = new seatsio.SeatingChart({...}).render();
$('#myButton').on('click', function(){
   chart.selectBestAvailable({'number': 2});
});
new seatsio.SeatingChart({
    ...,
    onChartRendered: function(chart) {
        chart.selectBestAvailable({'number': 2});
    },
    ...
}).render();

Note that these functions will only work after a chart is fully rendered. That means this won’t work, because the render() method may still be doing a number of async operations in the background:

var chart = new seatsio.SeatingChart({...}).render();
// <-- chart may not be fully rendered...
chart.selectBestAvailable({'number': 2}); // <-- so this won't work

chart.selectBestAvailable(config)

Selects best available objects (and deselects any already selected objects). The config parameter should be a javascript object that looks like this:

chart.selectBestAvailable({
    'number': 2,
    'category': 1 // optional
});

chart.clearSelection()

Deselects the currently selected objects.

chart.clearSelection();

chart.selectObjects(objectUuidsOrLabels)

Selects the specified objects. The parameter must be an array of strings.

chart.selectObjects(['A-1', 'A-2']);

chart.deselectObjects(objectUuidsOrLabels)

Deselects the specified objects. The parameter must be an array of strings.

chart.deselectObjects(['A-1', 'A-2']);

chart.selectCategories(categoryIds)

Selects all the objects in the categories. The parameter must be an array of strings, and the strings must be valid category IDs.

chart.selectCategories(['1', '2']);

chart.changeConfig(config)

Change the configuration of the chart. Currently supported parameters are objectColor, isObjectSelectable, objectLabel and maxSelectedObjects. The chart is re-rendered after configuration changes.

chart.changeConfig({
    isObjectSelectable: function() {
        return false;
    },
    maxSelectedObjects: 3
});