Placements Guide

Placements are globally unique designated third-party add-on extension points within the application (e.g Square Seller Dashboard).

Rendering

Rendering of third party Add-Ons into placements is unique to most traditional web development due to security concerns. It might be helpful to take a quick peek at how Add-Ons render for a general idea.

APIs

Upon render every placement is injected with an API. This is the handle third parties may use to communicate with the backing application. Providing contextual information and performing actions on the page. The placement APIs injected are composed of Global and Contextual APIs.

export default render<typeof ItemView>(({ api: itemViewApi }) => {
    ...
});

Global Placement APIs

Global placement APIs are APIs which are not contextual to any specific page extension point. They live at the application scope and are injected into all placements. These APIs will carry properties such as logged in Merchant and have actions for opening modals and blades.

Contextual Placement APIs

Contextual placement APIs are APIs which are contextual to specific page extension point.

React API Hooks

Receiving the placement API at the Add-On render level is not ideal as this requires prop drilling the instance down into rendering views and components. For that reason the React SDK supplies placement API hooks for delivery. For some placements there are helper hooks as well which provide a lot of nice functionality and remove boiler plate code.

Placement Widgets

Some placements have specific components which are required to be leveraged for the Add-On to integrate properly into the backing page. For example the item view placement requires the use of the ItemViewWidget component.

Square Seller Dashboard Supported Placements

The Square Seller Dashboard supports specific placements for extension. Its suggested to look them through to identify the needed use case prior to scaffolding things out with the CLI.

Customer Details

The customer details blade placement is located within the customer directory page under the details of a selected customer. Upon selection of a customer the right blade will open showing a list of cards. You placement will show as a card in this list. See the example URL.

Item View

The item view placement is located within the item library page item sheet. This placement is shown upon creation and update of an item. Once looking at the item sheet your placement will show as the last section on the sheet. See the example URL.

Home Widgets

The home widgets placement is located on the Dashboard Home page. Once looking at the home page your placement will show as the last widget on the page. See the example URL.