How do I configure the getSoapy Javascript plugin?

You can add getSoapy features to any website using the Javascript plugin.

Installing the plugin

Add the following Javascript tags to every page on your website, replacing {business-id} with your unique business ID. This should be added near the end of your HTML, just before the closing </html> tag.

You need to initialise the plugin using your unique Business ID. To get your Business ID, just ask Sid when you're signed into the app.

<script defer src="https://embed.getsoapy.com/embed.js"></script>
<script type="text/javascript">
    document.addEventListener('DOMContentLoaded', function() {
        getSoapy.init('{business-id}');
    });
</script>

Widget profiles

Most settings can be made in the app instead of in your code. Go to Website > Widget profiles, where each profile holds its own quote settings and style. Every business starts with one, your default profile, which your getSoapy website uses too.

Add another profile when a website or page needs to look or behave differently, then name it in your code:

getSoapy.init('{business-id}', {
    profile: '{profile-id}',
});

Choose Add to your website from a profile's menu for this code ready to copy, with your business ID and the profile filled in, plus the tag for each widget. Its Advanced tab gives each widget's tag with x-profile instead, for when only that widget should use the profile. Without a profile, the widgets use your default profile.

Anything you set in your code wins over the profile, so leave a setting out of your code if you want to change it from the app.

Settings

profile

The widget profile to use on this page. Defaults to your default profile.

termsDocumentId

The ID of the document customers agree to when they request a quote. Usually set in the widget profile instead.

defaultStyles

Override the default widget styles. See x-style below.

trackPageView

Default true. Allows disabling of page view tracking.

loadStyles

Default true. Allows disabling of all CSS styles. This will disable ALL plugin CSS and you'll need to style everything yourself.

quoteElement

Default getsoapy-quote. Allows changing the element ID where the quote widget is instantiated.

payElement

Default getsoapy-pay. Allows changing the element ID where the pay widget is instantiated.

documentsElement

Default getsoapy-documents. Allows changing the element ID where the documents widget is instantiated.

hideFields

Allows hiding certain fields in the quote widget. See x-hide-fields below.

completeInSections

Set this to true for the quote form to be split into pages. We recommend it. Your widget profile sets it if your code doesn't.

sectionTitles

Default false. Set this to true to show a title for each section when completeInSections is enabled.

floatingActionButton

Set this to true to enable the floating "request a quote" button. Your widget profile sets it if your code doesn't.

floatingTitle

Default Request a Quote. The label on the floating quote button.

scrollOffset

Default 0. Pixels added when scrolling to a widget. Use a negative number, such as -80, if your website has a fixed header.

onQuoteSubmitted

Optional function which will be called when a quote is submitted.

onQuoteNext

Optional function which will be called when the "next" button in the quote widget quote clicked.

prefill

Javascript object which allows prefilling of certain fields. Valid field names are: name, email, phoneNumber, address and amount. Amount is specified in pence.
For example: {name: 'John Doe', amount: 2000}

brandColor

Default #2965ad. Allows changing the brand color of the widgets. You can also set it in style, which wins if both are given.

style

How the widgets look. Every key is optional, and it applies to every widget on the page, including one with its own x-profile.

theme: Default light. Set to dark for a dark website, or auto to follow the visitor's device setting.

brandColor: Buttons, links and titles. Button text turns black when the colour is too light for white text. In the dark theme, titles and icons use a lighter shade if your colour would be hard to read.

backgroundColor: The widget's background colour, for example #0f172a. Fields and buttons are shaded a little towards the text colour so they stand out. Set it to transparent to let your page show through.

textColor: The main text colour. Labels, hints and borders are shaded from it.

titleColor: The colour of widget titles. Defaults to your brand colour.

titleFont: The font for titles and headings. Choose from montserrat, nunito, dosis, alata, righteous, croissant, permanentMarker, bangers, sonsie, sacramento, arial, georgia, palatino, times, verdana, courier, trebuchet or tahoma. Set it to inherit to use your website's font, or give any CSS font, for example 'Lobster', cursive, if your website already loads it.

bodyFont: The font for everything else. It takes the same choices as titleFont.

padding: 0 to 5. Space inside the widget's edge.

border: true or false. A border around the widget.

rounded: true or false. Rounded corners.

shadow: none, sm, md or lg. A shadow under the widget.

padding, border, rounded and shadow replace the matching part of defaultStyles. A widget with its own x-style keeps that instead.

Pick the theme closest to your website first, then set colours only where it still doesn't match. For a dark website:

getSoapy.init('{business-id}', {
    style: {
        theme: 'dark',
        backgroundColor: 'transparent',
        bodyFont: 'inherit',
        titleFont: 'inherit',
        shadow: 'none',
    },
});

Placing the widgets

Quote

Add the following HTML tag wherever you'd like to show the quote widget:

<div class="getsoapy" id="getsoapy-quote">
  Loading getSoapy quote widget. You must have javascript enabled to use this.
</div>

Payment

Add the following HTML tag wherever you'd like to show the payment widget:

<div class="getsoapy" id="getsoapy-pay">
  Loading getSoapy payment widget. You must have javascript enabled to use this.
</div>

Customer Portal

Add the following HTML tag wherever you'd like to show the customer portal widget:

<div class="getsoapy" id="getsoapy-portal">
  Loading getSoapy customer portal widget. You must have javascript enabled to use this.
</div>

Combined

The combined widget allows you to show the quote and either the payment or customer portal widgets in one place.

Add the following HTML tag wherever you'd like to show the combined widget:

<div class="getsoapy" id="getsoapy-combined">
  Loading getSoapy combined widget. You must have javascript enabled to use this.
</div>

Documents

Add the following HTML tag wherever you'd like to show the documents widget:

<div class="getsoapy" id="getsoapy-documents">
  Loading getSoapy documents widget. You must have javascript enabled to use this.
</div>

The documents widget will not be displayed if no documents have Share on website enabled.

Customising

These options can be added to each widget tag and allow you to customise each widget separately.

x-title

You may replace the title of the widgets using this attribute. If you set it to a blank string (x-title="") no title will be shown.

x-form-id

Show one of your own quote forms in this quote widget, by its ID.

x-hide-fields

You may specify a comma separated list of field names to hide.
The following fields can be hidden: availability, frequency, buildingType, bedrooms, consent, note, or attachments.

x-profile

Use a different widget profile for this widget alone, for example x-profile="{profile-id}". Its quote settings and style replace the page's, though anything set in your code still wins.

x-style

There are a number of styling options you can specify. If no style tag is specified the default is equivalent to: x-style="bg-light shadow rounded border p-3"

Padding: p-1 to p-5, Higher numbers add more padding.

Border: border adds a border to the widget.

Rounded: rounded rounds the corners of the widget.

Shadow: shadow-lg, shadow and shadow-sm add a shadow of different sizes.

Background: bg-light sets a light grey background and bg-white sets a white background. With the dark theme or a backgroundColor, they follow those instead.

You can put the same widget on a page more than once. Repeat its tag, and give each one its own x-profile or x-form-id if they should differ. Links like #quote scroll to the first one.

<div class="getsoapy" id="getsoapy-quote" x-profile="{profile-id}"></div>
<div class="getsoapy" id="getsoapy-quote" x-form-id="{quote-form-id}"></div>

Invoking the widgets

You can invoke a widget manually using the methods below. This will cause the widget to scroll into view if needed, and if appropriate the quote widget to open in a modal view, or the combined widget to switch to the requested widget.

Using anchor links

These anchor tags do not really exist, but the javascript will listen for them and invoke the appropriate widget.

<a href="#quote">Request a quote</a>
<a href="#pay">Make a payment</a>
<a href="#portal">Log into the customer portal</a>

Using Javascript

<button onClick="getSoapy.startQuote()">Request a quote</button>
<button onClick="getSoapy.startPay()">Make a payment</button>
<button onClick="getSoapy.startPortal()">Log into the customer portal</button>
<button onClick="getSoapy.startDocuments()">View our documents</button>