Passing dynamic data when rendering Builder content with the HTML API

FAQs Technical FAQs
,
1

You can bind values to specific state keys, which will be available to blocks’ bindings and the Javascript code you add to your content. For example, if you add a text block, and bind its content to a state variable, like state.myCustomTextValue, the HTML API lets you alter the value of this parameter using query string parameters, like:

curl --request GET \
  --url 'https://builder.io/api/v1/html/page?=&apiKey=$API_KEY&url=%2Fdemo-page&data.textFromState=a%20string'
  • page in the URL path is the model’s name
  • The apiKey parameter is your public API key
  • The url parameter is the value of the “Url” field of the content

The interesting query parameter here is data.textFromState: it can be anything that can be deserialized using JSON/JSON5, or if deserialization fails, it will be kept as a string. Note that to be correctly transferred as part of a URL, this value has to be also URL-encoded. Then you should be able to access these values from your blocks’ bindings and your content’s JS code.

  • data.someField=a%20string :arrow_right: state.someField === "a string"
  • data.someField=%22a%20string%22 :arrow_right: state.someField === "a string"
  • data.someField=42 :arrow_right: state.someField === 42
  • data.someField=true :arrow_right: state.someField === true
  • data.someField=false :arrow_right: state.someField === false

Note that these example values have double quotes (and they are URL-encoded)

  • data.someField=%2242%22 :arrow_right: state.someField === "42"
  • data.someField=%22true%22 :arrow_right: state.someField === "true"
  • data.someField=%22false%22 :arrow_right: state.someField === "false"

Since these values can be arbitrary values as long as they are in JSON, you can use this to set more complex values, like array and objects:

  • data.someField=%7B%22name%22%3A%22Betty%22%2C%22engineer%22%3Atrue%7D :arrow_right: state.someField == { name: 'Betty', engineer: true }
  • data.someField=%5B-42%2C0%2C42%5D :arrow_right: state.someField == [ -42, 0, 42 ]

Generalizing, the value of all query string parameters that are prefixed with data. will be available in your bindings without the data. prefix and after being deserialized using the JSON5 parser. If any value fails to be deserialized it will be kept as a string.