@financial-times/dotcom-ui-data-embed
v11.2.1
Published
This package provides methods for putting data into your server-side rendered pages and safely retrieving it again in the browser.
Downloads
2,214
Maintainers
robgodfrey
robertboulton
seraph2000
hamza.samih
notlee
emmalewis
aendra
the-ft
rowanmanning
chee
alexwilsonKeywords
Readme
@financial-times/dotcom-ui-data-embed
This package provides methods for putting data into your server-side rendered pages and safely retrieving it again in the browser.
Getting started
This package is compatible with Node 12+ and is distributed on npm.
npm install --save @financial-times/dotcom-ui-data-embedAfter installing the package you can use it to embed data into your pages on the server-side. This data can then be retrieved and used in your client-side code.
Server-side integration
If you are using React to render your app you can use the DataEmbed component to integrate the data embed data with your pages:
import { DataEmbed } from '@financial-times/dotcom-ui-data-embed'
const DATA_EMBED_ID = 'data-embed'
const data = { property: 'value', secondProperty: 'second-value' }
export default (props) => (
<html>
<head>
<meta charSet="utf-8" />
<title>My Amazing Website</title>
</head>
<body>
...
<DataEmbed id={DATA_EMBED_ID} data={data} />
</body>
</html>
)Otherwise you can insert a JSON formatted string into a <script> element with an ID of data-embed.
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<title>My Amazing Website</title>
</head>
<body>
...
<script type="application/json" id="data-embed">
{"property":"value","secondProperty":"second-value"}
</script>
</body>
</html>Client-side integration
Once you have data embedded in your page you can use the data embed client in your client-side code. The client provides methods for safely retrieving data.
import * as dataEmbed from '@financial-times/dotcom-ui-data-embed'
const dataEmbedClient = dataEmbed.init({ id: 'data-embed' })
if (dataEmbedClient.get('property')) {
...
}Client-side API
init({ id }:{ id: string })
Initialises and returns a new data embed client which can be used to safely access the data.
This method requires an id parameter within an options object.
This id should match the id attribute on the embed element within the page.
Data Embed Client API
get(property: string)
Returns the value of the requested property. If the property is not found this will return undefined.
getAll()
Returns all data embed data.
Please note that the data returned is frozen so it cannot be modified.