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.
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.
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.
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.
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.
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.
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>
}
}
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.
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.
The open method allows you to open the widget when the user is ready to search the cost data.
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:
source
.
Keep in mind one item has multiple rates based on a given unit of
measure.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.
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:
{: SourceRequestConfigType
searchPage: SourceRequestConfigType
detailsPage }
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.
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:
The on method will create an event listener. You can create as many listeners as you want.
Currently it supports these events:
request
.// file1.js
onebuild.on("request", (args) => calculation1(args))
// file2.js
onebuild.on("request", (args) => calculation2(args))
on(eventName: ListenerEventName, callback: (args: unknown) => unknown) ⇒ void
enum ListenerEventName {
Request = "request",
}
The off method will remove a previously-created event listener.
The close method will close the widget.