SimplicityBlocks™ Documentation

Overview

SimplicityBlocks™ is a service that allows you to easily create a universally distributable web widget using any front-end/back-end framework of your choice. Whether you use React, Angular, VueJS, vanilla JS, JQUERY, etc. your widget can be embedded in any web page that supports modern browsers.

Throughout our site and this documentation, we use a simple rating widget in order to demonstrate the various concepts involved with creating an embeddable widget and communicating with the widget via attributes and events. This rating widget is a simple vanilla JS app. It has two parameters that need to be set when loaded: one is for the main heading and the other is for the subheading above the text box.

Getting Started

To start with SimplicityBlocks™ you need to first sign up for a test account. A test account does not require you to enter any credit card information. You can build as many blocks as you like, but monthly requests are limited to 1,000 and a watermark is shown over your widget when it displays. When you are ready to launch your embeddable widget you need to upgrade your account to a pro account. The watermark is then removed and your account is billed by metered usage based on the pricing in our pricing table.

Signup

You can sign up for a SimplicityBlocks™ test account from the &lquot;Get Free Test Account&rquot; button on the home page or by clicking the “Sign Up” link in the top right of the site’s header.


No credit card information is required to set up a test account. An email address is required and needs to be verified before being able to log into your account. You will also need to agree to the terms of service.

The email will be from support@simplicityblocks.com so you may need to whitelist this address / domain in your email client.

Once your email is verified you can log in and start creating blocks.

Upgrade Account

Once you have created blocks in your test account and want to distribute your widget you will want to upgrade your account to a pro account.

To upgrade your account click on Account in the main menu.

The main account page will show the status of your account. In the section that shows “Your account is a test account” there is a link to “Upgrade Account Page”.

In the Upgrade Account Page you enter your credit card information. Once that information is successfully processed your account will be switched to a pro account.

Billing is metered. When you initially upgrade your account your first bill is one month from the day you signed up and is based on your usage as shown in the pricing page.

After upgrading your account your widget will display wothout a watermark and you will not have a limit on the number of requests.

Creating Blocks

List Blocks

From the main menu select “Manage Blocks”. Depending on whether or not you have created any blocks yet you will see one of the following two screens. The “Add Block” button is always there to create a new block.

If there is a list of existing blocks, you have the option of modifying or deleting the block.

OR

Add New Block

When you add a new block the initial screen will show “New Block” next to the Block ID heading and a blank description. You can add any description you like. It is used for sorting the list in the display blocks page.

The block configuration screen consists of three parts: Block identification and status; Block configuration; Preview

Block Identification and Status

Once you click on the “Add New” button a block id is assigned to the block and the ‘Add New” button changes to an update button.

As you are working on configuring a new block it is a good idea to regularly click on the “Update” button ibn order to save your work.

Preview

The preview section shows the preview of the launcher in real time as you make changes. Please note that it does not activate your widget, it is just a visual preview of the launcher.

The “Browser Preview” button will display your widget in a sample web page. Depending on how you configure your widget is how you determine which preview version to select.

  • Overlay
  • Inline
  • Inline Bottom

Preview page samples:

Overlay

Inline

NOTE: The browser preview function is just a quick check of your widget embedded in a page. The best test is for you to use your own test page that best represents the audience that will use your widget and test it there.

Block Configuration

The block configuration section is divided into 6 separate tabs:

  • Launcher Body
  • Launcher Text
  • Launcher Icon
  • Launcher Hover
  • Widget
  • Embed Code

Launcher Body

The launcher body is the overall shape, size and color of your launcher.

Launcher Body Settings

Overlay/Inline/None

This setting determines how the launcher body is rendered on the host page.

Overlay

When set as overlay the launcher appears over the web page content. A typical example of this would be a chat widget that shows in the lower right-hand side of a page. When set as overlay the Launcher Position setting below will define where on the page the launcher will be displayed.

Inline

When set as inline the widget will appear as a child of a container element in the web page. In this mode the individual in control of the page that is using your widget has control of where the widget will appear. If the widget size isn’t matched to the parent container, the Launcher Position setting will set the position within the parent container.

None

Setting to none will simply not use a launcher. Your widget will be immediately displayed.

Shadow

Shadow sets the shadow settings of the launcher body. This is CSS for the box-shadow setting.

Example values to enter here:

  • none (or blank)
  • 60px -16px teal
  • 10px 5px 5px black
  • 2px 2px 2px 1px rgba(0, 0, 0, 0.2)
Height

Height sets the height of the launcher body. This is a CSS value for height.

Example values to enter here:

  • 150px
  • 10em
  • 30%
  • auto
Width

Width sets the width of the launcher body. This is a CSS value for width.

Example values to enter here:

  • 150px
  • 10em
  • 30%
  • auto
Background Color

Background color sets the background color of the launcher body. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Launcher Position

The launcher position setting defines where the launcher body is positioned in relation to the viewport (for overlay) or within the parent (for inline). The 9 radio button setting choices are top left, top center, top right, middle left, middle center, middle right, bottom left, bottom center and bottom right.

Border Width

The launcher border width sets the width of the launcher body border.

Example values to enter here:

  • 0px
  • 3px
  • .2em
  • thick
  • 0 4px 8px 12px
Border Color

Border color sets the border color of the launcher body’s border. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Border Radius

The border radius setting sets the CSS border-radius of the launcher body’s border (if there is a border).

Example values to enter here:

  • 0 (or leave empty)
  • 20px
  • 10% 30% 50% 70%
  • 50%
Launcher Margin

The launcher margin sets the CSS margin of the launcher body in relation to the view port (for overlay) or the parent element (for inline).

Example values to enter here:

  • 16px
  • 1em
  • 5%
  • 10px 50px 20px

Launcher Text

The launcher text is the text that appears within the launcher body. This can be left blank if for example your launcher only contains an icon or image.

Text

This is the text that shows up in your launcher.

Text Position

This is the position of the text within the launcher body. The 9 radio button setting choices are top left, top center, top right, middle left, middle center, middle right, bottom left, bottom center and bottom right.

Text Margin

This is the margin of the text in relation to the inside of the body of the launcher.

Example values to enter here:

  • 16px
  • 1em
  • 5%
  • 10px 50px 20px
Font

The dropdown box for the font selects the browser-safe font family for the text.

The choices are:

  • default
  • Garamond Serif
  • Georgia Serif
  • Helvetica-Arial Sans-Serif
  • Impact Sans-Serif
  • Monospace
  • System
  • Times Serif
  • Trebuchet Sans-Serif
  • Verdana Sans-Serif
Font Size

The font size setting defines the CSS font size of the text.

Example values to enter here:

  • 14px
  • 1.2em
  • x-small
  • smaller
Font Style

The font style setting lets you add a bold or italic style to the font.

The choices are:

  • default
  • bold
  • italic
  • bold and italic
Font Color

Font color sets the font color of the text. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)

Launcher Icon

The launcher icon (if you choose to have one) can be an svg, jpg, png or gif file.

Icon Height

The icon height is a CSS height value that sets the height of the icon. PLEASE NOTE: If you choose an SVG image as your icon, there may be limits on the effects of the height settings.

Example values to enter here:

  • 150px
  • 10em
  • 30%
  • auto
Icon Width

The icon width is a CSS width value that sets the width of the icon. PLEASE NOTE: If you choose an SVG image as your icon, there may be limits on the effects of the width settings.

Example values to enter here:

  • 150px
  • 10em
  • 30%
  • auto
Icon Margin

This is the margin of the icon in relation to the text and the inside of the body of the launcher.

Example values to enter here:

  • 16px
  • 1em
  • 5%
  • 10px 50px 20px
Remove Icon

If you have set up an icon and wish to remove it simply click on the Remove Icon button.

Icon Line Color (SVG Only)

Icon line color sets the line color value of the SVG image. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Icon Background Color(SVG Only)

Icon background color sets the background color value of the SVG image. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Icon to Text Position

This setting defines the position of the icon in relation to the text. The options are top, right, bottom or left.

Launcher Hover

The launcher hover settings allow you to create desired effects for when a user places their cursor over the launcher.

Hover Cursor

This dropdown list allows you to select the type of cursor you want to display when the user hovers over the launcher.

Hover Background Color

The hover background color sets the background color of the launcher body for when the cursor is placed over the launcher body.. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Hover Border Color

The hover border color sets the border color of the launcher body for when the cursor is placed over the launcher body.. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Hover Text Color

The hover text color sets the color of the launcher text for when the cursor is placed over the launcher body.. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Hover Icon Line Color (SVG ONLY)

The Hover Icon line color sets the line color value of the SVG image when the cursor is placed over the launcher body. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Hover Icon Background Color (SVG Only)

The Hover Icon background color sets the background color value of the SVG image when the cursor is placed over the launcher body. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color. PLEASE NOTE: Not all SVG images will support this setting.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Hover Shadow

The Hover Shadow sets the shadow settings of the launcher body for when the cursor is over the launcher body. This is CSS for the box-shadow setting.

Example values to enter here:

  • none (or blank)
  • 60px -16px teal
  • 10px 5px 5px black
  • 2px 2px 2px 1px rgba(0, 0, 0, 0.2)
Hover Margin

The hover launcher margin sets the CSS margin of the launcher body in relation to the view port (for overlay) or the parent element (for inline) for when the cursor is over the launcher body.

Example values to enter here:

  • 16px
  • 1em
  • 5%
  • 10px 50px 20px

Widget

The widget tab lets you configure your widget that displays with the block either when the launcher is activated or immediately when configured as inline with no launcher.

Overlay/Inline

Overlay

When set as overlay the widget appears over the web page content. A typical example of this would be a chat widget that shows in the lower right-hand side of a page. When set as overlay the Widget Position setting below will define where on the page the widget will be displayed.

Inline

When set as inline the widget will appear as a child of a container element in the web page. In this mode the individual in control of the page that is using your widget has control of where the widget will appear. If the widget size isn'’'t matched to

Modal/Nonmodal

Modal

When modal is selected the overlay widget and its background will not let click events flow through to the page below.

Nonmodal

When nonmodal is selected click events will go through to the background page.

Widget Position

The widget position setting defines where the widget is positioned in relation to the viewport (for overlay) or within the parent (for inline). The 9 radio button setting choices are top left, top center, top right, middle left, middle center, middle right, bottom left, bottom center and bottom right.

Height

Height sets the height of the widget body. This is a CSS value for height.

Example values to enter here:

  • 400px
  • 10em
  • 30%
  • 80vh
Width

Width sets the width of the widget body. This is a CSS value for width.

Example values to enter here:

  • 400px
  • 10em
  • 30%
  • 80vw
Widget Margin

The widget margin sets the CSS margin of the widget body in relation to the view port (for overlay) or the parent element (for inline).

Example values to enter here:

  • 16px
  • 1em
  • 5%
  • 10px 50px 20px
Background Color

Background color sets the background color of the widget overlay background. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Close Icon Width

The close icon width is the diameter of the close icon circle that shows on the top right of the widget. If you do not want to use the pre-defined close icon you can put 0px for a value here. See the Widget Communication section below to see how to send a close command from within your widget.

Example values to enter here:

  • 16px
  • 1em
Close Icon Color

Close Icon color sets the color of the round close button that shows on the top right of the widget. Color values can be set in the text box by the setting or clicking on the color icon will pop up a color picker widget that you can use to set the color.

Example values to enter here:

  • red
  • #00ff00
  • rgb(214, 122, 127)
  • rgba(57,96,61,0.43)
Close Icon Offset Top

This setting positions the close button over the top edge of the widget. Using an offset can place the close button icon over the edge of the corner.

Example values to enter here:

  • 16px
  • 1em
Close Icon Offset Right

This setting positions the close button over the right edge of the widget. Using an offset can place the close button icon over the edge of the corner.

Example values to enter here:

  • 16px
  • 1em
Widget URL

This is the fully qualified URL of where your widget is hosted.

It is recommended to use a secure URL (i.e., https).

You will need to make sure that your response allows your widget to be loaded in an iframe. This is typically accomplished by removing the X-Frame-Options header from the response.

Widget Attributes

You can define as many widget attributes as you like. Enter each attribute name separated by commas.

When your widget is loaded in the Simplicity Block the attributes and the values that your user placed in them will get passed to your widget as URL parameters. You can then read those parameters and take appropriate action.

If the user of your Simplicity Block programmatically sets an attribute value, that will cause an event and the Simplicity Block will reload he widget with the new value in the URL parameters.

Allowed Domains

If you want all domains to be allowed to use your Simplicity Block, enter an * for the value here.

If you wish to restrict access to your Simplicity Block to select domains, enter the domain names here. You can use * as the subdomain. For example: *.mydomain.com. Multiple entries need to be separated by commas.

If you have restricted the access to your Simplicity Block to specific domains, requests from domains that are not allowed will simply not display. These unallowed requests will also NOT COUNT toward your monthly usage.

Preview Attributes

The preview attributes are simply values you can define that will get passed to your widget when using our preview functionality. These need to be separated by commas. For example:

rh=Rate This Page,ch=Leave a Comment

Embed Code

Once you are done configuring your block you can get your embed code.

In the Embed Code tab click on the ‘Get Embed Code’ button and the text box will display the component tag with the required Simplicity Block ID (sbid) as well as any attributes you have defined (with empty values).

There are two lines of script code that also need to be include on any page that uses your Simplicity Block.

Widget Communication with Host

The page hosting your SimplicityBlocks™ widget can communicate via attributes, the sendMessage method and events.

We have a separate page that describes and demonstrates the various ways to communicate with your widget. That page is here.

Getting Help

If you need help getting things working, send a support message at https://www.simplicityblocks.com/ManageBlocks/support