@microsoft/fast-data-utilities-react
v1.5.1
Published
FAST data utilities for React
Downloads
16
Keywords
Readme
FAST Data utilities React
FAST Data utilities React has been deprecated. Use FAST Tooling React instead.
React data utilities are used to map data to components and perform other actions that may be necessary to pass data to other FAST-DNA libraries for manipulation, data validation, or storage. It relies on the creation of relevant JSON schemas for components, JSON schemas for the purposes of React use additional keyword of reactProperties
for React children with the "type" of "children".
Installation
npm i --save @microsoft/fast-data-utilities-react
Usage
mapDataToComponent
The mapDataToComponent
function can be used to map data to a React component. It uses JSON Schema, IDs, as well as data to create components from plain data.
An example of mapping data to a component from the @microsoft/fast-data-utilities-react
package:
import * as React from "react";
import * as ReactDOM from "react-dom";
import { Dialog } from "@microsoft/fast-components-react-msft";
import * as dialogSchema from "@microsoft/fast-components-react-base/dist/dialog/dialog.schema.json";
import * as headingSchema from "@microsoft/fast-components-react-msft/dist/heading/heading.schema.json";
import * as paragraphSchema from "@microsoft/fast-components-react-msft/dist/paragraph/paragraph.schema.json";
import { mapDataToComponent } from "@microsoft/fast-data-utilities-react";
const data = {
visible: true,
children: [
{
id: headingSchema.id,
props: {
children: "Heading 1"
}
},
{
id: paragraphSchema.id,
props: {
children: "Lorem ipsum."
}
}
]
};
const childOptions = [
{ component: Heading, schema: headingSchema },
{ component: Paragraph, schema: paragraphSchema },
];
const root = document.createElement("div");
root.setAttribute("id", "root");
document.body.appendChild(root);
function render() {
ReactDOM.render(
<Dialog {...mapDataToComponent(dialogSchema, data, childOptions)} />,
root
);
}
render();
Plugins
As an optional argument to mapDataToComponent
, plugins may be used. Plugins must be extended from the Plugin
class export and provide a resolver
method. In this way functional code can be mapped to a component.
React render prop plugin example:
import { mapDataToComponent, Plugin } from "@microsoft/fast-data-utilities-react";
class MyPlugin extends Plugin {
resolver(data, childOption) {
return (className) => {
return React.createElement(
childOption.component,
Object.assign({}, data.props, { className })
);
};
}
}
Schema example for the React render prop plugin example:
{
"$schema": "http://json-schema.org/schema#",
"title": "Component with custom properties",
"type": "object",
"id": "component-with-react-render-prop",
"reactProperties": {
"children": {
"title": "Children",
"type": "children",
"pluginId": "my-plugin"
}
}
}
/**
* The plugins take a configuration that includes a string or an array of strings
* mapping them to schema properties which also have a `pluginId`
*/
const plugins = [
new MyPlugin({
id: "my-plugin"
})
];
mapDataToComponent(schema, data, childOptions, plugins);
getChildOptionBySchemaId
The getChildOptionBySchemaId
accepts a list of child options and returns the one that matches the schema ID.
import { getChildOptionBySchemaId } from "@microsoft/fast-data-utilities-react";
import * as headingSchema from "@microsoft/fast-components-react-msft/dist/heading/heading.schema.json";
import * as paragraphSchema from "@microsoft/fast-components-react-msft/dist/paragraph/paragraph.schema.json";
const childOptions = [
{ component: Heading, schema: headingSchema },
{ component: Paragraph, schema: paragraphSchema },
];
const headingChildOption = getChildOptionBySchemaId(headingSchema.id, childOptions); // should be { component: Heading, schema: headingSchema }
getDataLocationsOfChildren
The getDataLocationsOfChildren
returns any data locations of react children. This assumes that the
import { getDataLocationsOfChildren } from "@microsoft/fast-data-utilities-react";
import * as headingSchema from "@microsoft/fast-components-react-msft/dist/heading/heading.schema.json";
const headingData = {
children: "Hello world"
};
const dataLocationsOfChildren = getDataLocationsOfChildren(headingSchema, headingData, []); // should be ["children"]
getPartialData
The getPartialData
function returns partial data based on a location path using the lodash
path syntax.
import { getPartialData } from "@microsoft/fast-data-utilities-react";
const data = {
foo: {
bar: [
{
bat: "Hello world"
}
]
}
}
const location = "foo.bar.0";
const partialData = getPartialData(location, data); // should be { bat: "Hello world" }
mapSchemaLocationFromDataLocation
The mapSchemaLocationFromDataLocation
takes a lodash
path to data, the data and the corresponding schema to determine the schemas path to that data.
import { mapSchemaLocationFromDataLocation } from "@microsoft/fast-data-utilities-react";
const dataLocation = "children";
const data = {
children: "Hello world"
};
const schema = {
type: "object",
reactProperties: {
children: {
type: "children"
}
}
}
const schemaLocation = mapSchemaLocationFromDataLocation(dataLocation, data, schema); // should be "reactProperties.children"
normalizeDataLocation
The normalizeDataLocation
converts all property locations to lodash
path dot notation and all array item references to bracket notation
import { normalizeDataLocation } from "@microsoft/fast-data-utilities-react";
const dataLocation = "foo.bar[0].bat";
const data = {
foo: {
bar: [
{
bat: "Hello world"
}
]
}
}
const normalizedDataLocation = normalizeDataLocation(dataLocation, data); // should be "foo.bar.0.bat"