Back to index
Developer documentation

JavaScript Widget Configuration Guide

With the SuperSaaS JavaScript widget you can integrate a schedule into a web page in a way that makes it appear to be part of it. You can generate a snippet that loads the widget on the widget configurator page. This page explains advanced options not available in the configurator.

custom_cssCustomize colors and styling
domainUse a custom domain
selectPreselect a specific slot, resource or service
day, month, yearOpen the widget on a specific date
containerSpecify where to place the widget
colorOnly display slots of one color (Capacity schedule type)
res_layoutSet display format for resources (Resource schedule type)
modal_widthAdjust the size of the frame and the popup
widget_typeDetermine behavior upon initialization
prefillPrefill appointment information
supersaas_api_userAutomatically create or log in a user
If you are using an HTML link instead of the JavaScript widget then you can use these options by adding them as query parameters at the end of the link. For example:­view=widget&custom_css=h1{color:red}

Customize colors and styling

The colors used by the widget can be customized on the Configure > Layout page inside your account. If you want to apply your own styling you can pass CSS into the widget that will be added in between style tags in each frame. Alternatively, you can provide a link to an external style sheet. Please be aware the markup used in the widget may change occasionally as we roll out improvements, so you can not rely on identifiers or page structure remaining the same.

var supersaas = new SuperSaaS("demo", "Therapist", {"custom_css": "h1 {color:red}"})
var supersaas = new SuperSaaS("demo", "Therapist", {"custom_css": "https://….css"})

Use a custom domain

Because the widget is loaded inside a frame on the host page, the URL from which the widget is loaded will typically not be visible to the user. However, if your booking process involves payment then the widget needs to forward the browser to a page outside the frame and this reveals the domain. Payment providers do not allow the payment process to run inside a third party frame for security reasons, so payment would fail if we did not forward the browser. By default this domain is, but you can change this to your own domain as explained in the custom domain documentation.

var supersaas = new SuperSaaS("demo", "Therapist", {domain: ""})

It’s important to note that this will only work on domains that accept https connections. Therefore, just setting a DNS record that points to SuperSaaS will not work, a proxy server needs to be used.

Preselect a specific slot, resource or service

It can be convenient to keep multiple things in one schedule, while only showing a subset to a specific group of users. This works slightly differently depending on the schedule type you use.

Preselecting a slot on a Capacity-type schedule

When you want a user to sign up for a specific event, like a workshop, it would be cumbersome to ask them to select a date if there is only a single slot on the schedule. The option Show simplified if only one slot on the Configure > Layout page makes sure that the slot automatically gets preselected, and this also works with the widget.

If you offer multiple workshops you can keep them all in a single schedule, while still having a widget that shows a specific one. You can achieve that by specifying the slot ID which you can find on the Supervise page of the schedule by clicking the spyglass icon on the slot. By adding view: "free" we ensure the widget also opens the slot.

	Link that shows a specific slot
	Idem for widget new SuperSaaS("demo","Cupcake_Workshop",{view:"free", select:12320083})

Preselecting a resource on a Resource-type schedule

On a resource type schedule you can pass in the resource name to only show the available space for that specific resource. The user can still change the resource when on the final booking screen.

	Link to a specific resource
	Idem for widget new SuperSaaS("demo","Meeting_Rooms",{select:"Meeting Room 1"})

Preselecting a service on a Service-type schedule

On a service type schedule you can preselect the service that will be visible when the user enters the view. The user can still change to a different service.

	Link to a specific service
	Idem for widget new SuperSaaS("demo","Therapist_2",{select:"Long treatment"})

Open the widget on a specific date

Normally the calendar will open on the first available date. This is calculated by adding the minimum time that users are allowed to book in advance to the current date. If this falls before the “Closed before” date set on the Opening Hours tab, then that date will take precedence. By specifying day, month, year or week you can force the calendar to open on a particular day. Furthermore, you can add "today": 1 to open on the current date, rather than the first available date.

	Link to a specific date
	Idem for widget new SuperSaaS("demo","Therapist",{month:12,day:24})

Specify where to place the widget

By default, the widget places itself in the page right after the script tag that instantiated it (unless the script is in the head section, in which case it attaches to the body). You can override this behavior by specifying a container parameter. When present, it will insert itself as a child of this element. This can be useful if you want to separate out the JavaScript to a separate file.

<div id="container"></div>
new SuperSaaS("demo","Meeting_Rooms",{container:"#container"})

Only display slots of one color (Capacity schedule type)

On a capacity type schedule, you can create slots with different colors, for example to indicate different lesson types (intermediate, advanced, etc). You may want to show only slots of one color to a specific user, while keeping all slots visible in the same calendar for yourself.

	Link that shows all classes
	Link that shows only blue classes
	Widget that shows only blue classesnew SuperSaaS("demo","Fitness_Club",{color: 0})

You can set the color while editing a slot, by clicking the colored box in the lower right corner. Colors are numbered 0 to 15, from top left to bottom right.

Set display format for resources (Resource schedule type)

If a resource schedule contains many resources, the default view where each resource occupies a single may be too cluttered. The system automatically shows a different “accordion” view where each column is collapsed into a row if there are more than ten resources. Depending on the space available to the widget you may want to override this behavior to force a particular view. You can do this by passing in the res_layout parameter.

	Regular column view
	Idem via JavaScript new SuperSaaS("demo","Meeting_Rooms",{"res_layout":"simple"})
	Accordion view
	Idem via JavaScript new SuperSaaS("demo","Meeting_Rooms",{res_layout:"accordion"})

There are several parameters you can pass when instantiating a widget to determine the size of the frame for the widget, and the size of the “modal” frame, which is popup where the appointment details can be filled out.

height, width, max_widthOverride the default size of the widget frame
modal_width, modal_max_widthOverride the default size of modal frame
z_indexOverride the default z-index of the gray overlay beneath the popup

Determine behavior upon initialization

The widget_type parameter determines the behavior when the widget is instantiated. It can take one of three values:

  • closed: (default): The widget remains inactive until its show() method is called.
  • frame: The widget creates an iframe and opens inside the frame.
  • button: The widget generates a button element with the content passed into btn_label and an optional style applied via the parameter btn_style. It attaches an onclick handler to the button that calls its show() method.
new SuperSaaS("demo","Exams",{"widget_type":"button",btn_label:'Book',btn_style:'color:red'}

Prefill appointment information

Your website may have collected information from the user that you would also like to capture during the booking process. To avoid asking the user to fill out this information twice, you can pass it into the widget so it will be prefilled.

	Prefill on a schedule[full_name]=UserName
	Prefill on a widget new SuperSaaS("demo","Therapist",{prefill:{full_name:"UserName"}})

The field names available to pass in to the prefill object differ based on the schedule type and depend on which fields are enabled. The easiest way to find them is by using the “Inspect” functionality on the browser when you are creating an appointment. The field name will have the format reservation[email] or booking[address], the field name will be the part between brackets. Note that users will still be able to modify the prefilled information.

Automatically create or log in a user

If users are already logged into your own website then you can automatically log them into your widget as well. This avoids having to ask the user to sign up and log in twice. If you happen to use WordPress, Drupal or Joomla then we provide a plugin to do this automatically. For other cases you can use the User API to do this. Note that using that API directly requires some server side programming.

Here is an example snippet, with appropriate values filled in for your account, that shows how to log a user into a widget using the API.