1build Widget Reference

Use the 1build widget to allow your users to browse our Cost Data database.

This integration is using a previously-generated test API key, which modifies the prices by random percentages. Get your own API key to start getting real live cost data.

Introduction

The 1build widget is the client-side component that your users will interact with in order to get our Cost Data into their projects.

The widget will handle authentication, pagination, location and search for you.

Getting Started

Are you looking to use an external API key? Click here to get started with the API reference.

Include the 1build widget script on your app.

Note: If you need to include the script in the head component, be sure to add the async and defer attributes, since our widget depends on the body to fully load.

<script src="https://cdn.1build.com/widget.js"></script>

After including the script, a global object named onebuild will be available for you to manage the widget (see the API reference).

Keep in mind our widget uses lazy-loading for the queries that fetch the categories and the items, meaning, the widget won’t trigger any of those request unless you open the containing dropdown.

Authentication

Access to the widget is authenticated by your API key which will need to be passed in the init method. API keys are unique to your organization and they come in two types:

EXTERNAL - for use with backend integrations.
EMBEDDED - for use with client-side integrations.

Because the EMBEDDED key must be included in your client-side code it cannot be kept secret. For this reason you must configure referrers in your 1build organization preferences to match the domain name of the website hosting the code which will call the API. For example, if your application is hosted at https://constructionmagic.com/parts/lookup, you would put https://constructionmagic.com/ in your referrers list.

Be sure to use the widget with an EMBEDDED API key. If you need an API key or for help using one please contact help@1build.com.

API reference

Init

The init method is used to initialize the widget with your own particular configuration. Ideally you would call this method right after your application loads, and only once for the lifetime of your app.

Usage

`key`

The API key provided by 1build.

`theme`

An object to set the color palette and typography configuration.

The 1build widget uses Material UI component library to power its components and styles and this theme property is a sub-set of MUI’s own theme.

We know it’s difficult to understand the properties you can use without proper typing, we’re working on giving you the most up-to-date type definitions. We’ll keep this page updated with our progress.

You can also use this tool to play with your theme configuration.

Types reference

init(params: WidgetInitParams) ⇒ void

interface WidgetInitParams {
    // The API key provided by 1build.
    key: string
    // An object to set the color palette and typography configuration.
    theme?: {
        palette?: Record<string, unknown>
        typography?: Record<string, unknown>
    }
}

Identify

The identify method allows you to pass a string that uniquely identifies the user who is performing the search. This is attached to the logged metrics and can improve usage analysis.

Usage

onebuild.identify({ userId: "YOUR_USER_ID" })

`userId`

An arbitrary string that you use to identify the user of your system. This could be an email address, a UUID or any other unique identifier.

Types reference

identify(params: WidgetIdentifyParams) ⇒ void

interface WidgetIdentifyParams {
    userId: string
}

Open

The open method allows you to open the widget when the user is ready to search the cost data.

Usage

`closeOnRateSelected`

A boolean indicating if the widget should close when a rate is selected. Defaults to true.

`disableTypeahead`

A boolean indicating if the search should use ‘typeahead’ or not. In case of true a ‘search’ button will be shown and the search will be performed only when that button is clicked. Defaults to false.

`filter`

A type of item to filter by inside the widget. Defaults to ‘all items’.

The possible values are:

ALL.
MATERIAL.
SCOPE.
EQUIPMENT.
ASSEMBLY.
LABOR.

`location`

A pre-defined search location in state and county or coordinates or zipcode.

The 1build data is county-based, so the coordinate and zipcode inputs are used to find the closest county.

`onRateSelected`

A callback that is executed when a rate is successfully selected.

This callback is called with an object containing 3 properties:

A source which is the object containing all the data about the item that the user selected.
A selectedRate which is the object containing all the data about the rate the user selected for the source. Keep in mind one item has multiple rates based on a given unit of measure.
A flag named includeLaborRate which allows you to know if the user selected the rate with our without labor included. In case the labor rate is included you want to take into consideration the laborRateUsdCents porperty from the selectedRate.
A selectedLaborRateType which allows you to know if the user selected the rate with our without labor included.
- undefined - the labor rate was not included.
- BASE - the base labor rate was included.
- BURDENED - the burdened labor rate was included (Burdened Labor Rate reflects the base hourly rate for one (1) laborer with an additional 33% added, to account for costs of assumed benefits like Paid Leave, Supplemental Pay, Insurance, Workers Comp, and other Legally Required Benefits).

`pageLimit`

The maximum number of sources per category to be returned in every search. For the top results the default value is 5, for the categories the default value is 20.

`readOnlyLocation`

A boolean indicating if the search location is read-only or not. Defaults to false.

`requestBrowserLocation`

A boolean indicating if the widget will request the location from the browser. Defaults to false.

`searchTerm`

A pre-defined search term.

`sourceRequestConfig`

A type of configuration based on which sources will be retrieved from our cost data database. You can specify one general configuration or one configuration per page.

Note: this configuration may affect your billed rate.

BASE - Source is going to be returned with no rate information. With this configuration, the selectedRate and selectedLaborRateType properties on the onRateSelected callback will be undefined.
PREVIEW - Source is going to be returned with the calculatedUnitRateUsdCents property.
DETAIL - Source is going to be returned with the full rate information (burdenedLaborRateUsdCents, knownUoms, productionRate, laborRateUsdCents and materialRateUsdCents).

As mentioned, you can also pass an object with the following shape:

{
    searchPage: SourceRequestConfigType
    detailsPage: SourceRequestConfigType
}

`topResultsBehavior`

OPEN - The top results are going to be open.
CLOSED - The top results are going to be closed.
HIDDEN - The top results are going to be hidden.

`typeaheadDelay`

Time in milliseconds before another search gets triggered by the search input.

Types reference

open(params: WidgetOpenParams) ⇒ void

interface WidgetOpenParams {
    // closeOnRateSelected defaults to true
    closeOnRateSelected?: boolean
    // disableTypeahead defaults to false
    disableTypeahead?: boolean
    // filter defaults to `ALL`
    filter?: SourceType
    location?:
        | {
              lat: string
              lng: string
              state: never
              county: never
              zipcode: never
          }
        | {
              lat: never
              lng: never
              state: string
              county: string
              zipcode: never
          }
        | {
              lat: never
              lng: never
              state: never
              county: never
              zipcode: string
          }

    onRateSelected?: (args: OnRateSelectedArgs) => void
    pageLimit?: number
    // readOnlyLocation defaults to false
    readOnlyLocation?: boolean
    // requestBrowserLocation defaults to false
    requestBrowserLocation?: boolean
    searchTerm?: string
    // sourceRequestConfig defaults to SourceRequestConfigType.DETAIL
    sourceRequestConfig?:
        | SourceRequestConfigType
        | {
              searchPage: SourceRequestConfigType
              detailsPage: SourceRequestConfigType
          }
    // topResultsBehavior defaults to "OPEN"
    topResultsBehavior?: "OPEN" | "CLOSED" | "HIDDEN"
}

enum SourceRequestConfigType {
    BASE = "BASE",
    PREVIEW = "PREVIEW",
    DETAIL = "DETAIL",
}

interface OnRateSelectedArgs {
    // This type will change based on the `sourceRequestConfig` value
    source: Source
    // selectedRate.calculatedUnitRateUsdCents has the rate selected by user in the widget
    // selectedRate.uom has the unit of measure the selected by user in the widget
    selectedRate: KnownUom
    selectedLaborRateType: "BASE" | "BURDENED" | undefined
}

Please refer to the 1build API reference for the following types:

On

The on method will create an event listener. You can create as many listeners as you want.

Currently it supports these events:

request.

Usage

// file1.js
onebuild.on("request", (args) => calculation1(args))

// file2.js
onebuild.on("request", (args) => calculation2(args))

Types reference

on(eventName: ListenerEventName, callback: (args: unknown) => unknown) ⇒ void

enum ListenerEventName {
    Request = "request",
}

Off

The off method will remove a previously-created event listener.

Usage

onebuild.off("request")

Types reference

off(eventName: ListenerEventName) ⇒ void

enum ListenerEventName {
    Request = "request",
}

Close

The close method will close the widget.

Usage

onebuild.close()

Types reference

close() ⇒ void