Below is the detailed configuration options that can be done using Mason.
The root node has a little different structure than rest of the nodes. It has two properties as page and config which basically represents the page or route of your web app you're trying to configure the UI for. That said, mason is not limited to page levels only. You can use it to created nested UI as well.
Note: The config property can be an array of nodes as well striaght-away if you don't want to wrap them in an uber level layout element.
id field represents the element id used to uniquely identify the current state and updations for a given element. Make sure to keep it unique since this drives any updations during prop change of a given component
type field will help render the corresponding component during the render phase. It'll get matched against the components mapping that's passed while creating the renderer during usage.
const homePageRenderer = new ReactConfigRenderer(
config,
{
PAGE_LAYOUT: HomePageLayout,
SEARCH_INPUT: SearchInput,
RECIPES_LIST_GROUP: RecipesListGroup,
FOO: () => <p>foo</p>
}
);
meta field can be used to pass any properties to an UI Component that'll be added as inline props to the component being rendered. You can pass component props or normal HTML element props in it.
Note: Setting up value property in meta is helpful when you want to make your component controllable to avoid React warnings
show property will completely unmount or not render the component in the first place if it evaluated to falsy. It can accept either a boolean or a boolean confguration as
{
"operator": "!=",
"leftOperand": "<%statesDropdown%>",
"rightOperand": "[]",
"type": "ATOMIC"
}
Here, it'll evaluate the boolean operation as <Value of statesDropdown> != [] and determine the value of show.
The detailed sturcture of BooleanConfig can be understood as the TS type below:
type BooleanConfig = {
type: OperationType;
operator: ComparisonOperators | CompoundOperators;
leftOperand: string | BooleanConfig;
rightOperand: string | BooleanConfig;
};
ComparisonOperators and CompoundOperators are discussed in detail further.
style property simply represents inline styles object passed in the Component.
data property will work as onMount fetching of data. You can specify a remote data source to fetch data asynchronously or set it statically.
AJAX_CALL: The most common scenario is of loading data on mount of a given component. type attribute set to AJAX_CALL is meant to handle the same. On successful ajax call, it'll set the datasource prop on the component. Also, when the Ajax call starts, a loading prop is set to true on the component and set as false on promise settling (either resolved or caught).
{
"type": "AJAX_CALL",
"meta": {
"endpoint": "https://api.edamam.com/search",
"queryParams": {
"q": "egg",
"app_id": "<app id>",
"app_key": "<app key>",
"foo": "<%fieldId%>",
},
"credentials": "include",
"fieldId": "recipesListComponent",
"dataProcessor": "recipeDataSourceProcessor"
}
}
SET_DATASOURCE: To statically set the datasource of the current component or some other component by specifying the optional fieldId.
{
"type": "SET_DATASOURCE",
"meta": {
"data": ["foo", "bar"],
"fieldId": "<fieldIdToSetDataSourceFor>"
}
}
SET_VALUE: In case you want to set the value of the current component or some other component on mount of current component.
{
"type": "SET_VALUE",
"meta": {
"value": "foo",
"fieldId": "<fieldIdToSetValueFor>"
}
}
CUSTOM: When you want to execute a custom function on mount of the component.
{
"type": "CUSTOM",
"meta": {
"name": "<nameOfTheCustomFunction>"
}
}
The Custom function needs to be passed in the resolvers map while creating the renderer. It'll be called with one parameter as ({ event, value, id }) from which the values can be destructured during invocation.
events property can either accept a map of event name vs their handlers configuration. Each event could have multiple handlers, hence both the array config and object config is supported. Below is the TypeScript typing for the same.
events?: {
[eventName: string]: Array<IEventsConfig> | IEventsConfig;
}
Eg:
"events": {
"onChange": [
{
"type": "SET_VALUE"
},
{
"type": "AJAX_CALL",
"meta": {
"endpoint": "https://api.edamam.com/search",
"queryParams": {
"q": "<%SELF%>",
"app_id": "<APP_ID>"
},
"dataProcessor": "recipeDataSourceProcessor",
"fieldId": "recipesListGroup"
},
"when": {
"operator": "=",
"leftOperand": "<%secondSearchInput%>",
"rightOperand": "",
"type": "ATOMIC"
}
}
],
"onFocus": {
"type": "SET_VALUE",
"meta": {
"value": [],
"fieldId": "<fieldIdToSetValueFor>"
}
},
"onClick": [
{
"type": "SET_DATASOURCE",
"meta": {
"data": [],
"fieldId": "<fieldIdToSetDataSourceFor>"
}
},
{
"type": "CUSTOM",
"meta": {
"name": "<customFunctionNameHere>"
}
}
]
}
Here, the onChange event of the component will execute two event handlers viz set value of itself (required for controlled components - same as setState the value), and the other one makes an ajax call to a remote api to fetch data of a listing component based on the query text entered in the current/self component.
Note how the query param is able to take <%SELF%> as it's value. It's a special value to get the current value of the current component in consideration. You could pass the id of the self component here as well, but it'll give a stale value since this is the event handler which will change it in the end.
The when clause is a conditional clause which is discussed in detail further.
Next, the onFocus event is executing a single handler to set the datasource property of the given fieldId. No need to pass an array form here.
And, the onClick event is useful in case of a button component wherein you want to execute a custom event handler by matching it's name against what was passed in the dataProcessors property while creating the Renderer.
validations can be used to configure the form validations on a given component. It's very useful in case of rendering forms. Here's a sample configuration for a simple Login Form.
{
"page": "FORM",
"config": [
{
"id": "email",
"type": "TEXTFIELD",
"meta": {
"placeholder": "Enter your email",
"type": "email",
"value": "",
"autoComplete": "off"
},
"validations": [
{
"type": "REQUIRED"
},
{
"type": "LENGTH",
"meta": {
"min": 3,
"max": 50
}
},
{
"type": "REGEX",
"meta": {
"pattern": "^\\w+([\\.-]?\\w+)*@\\w+([\\.-]?\\w+)*(\\.\\w{2,3})+quot;
}
}
],
"events": {
"onChange": [
{
"type": "SET_VALUE"
}
]
},
"style": {
"marginBottom": 10
}
},
{
"id": "password",
"type": "TEXTFIELD",
"meta": {
"value": "Password@123",
"type": "password",
"placeholder": "Enter your password"
},
"events": {
"onChange": {
"type": "SET_VALUE"
}
},
"style": {
"marginBottom": 10
},
"validations": [
{
"type": "REGEX",
"meta": {
"pattern": "^(?=.*\\d)(?=.*[!@#$%^&*])(?=.*[a-z])(?=.*[A-Z]).{8,}quot;
}
}
]
}
]
}
The validations property expects an array of validation configuration to be supplied. Each configuration has a type field which can take either of the following values.
REQUIRED : It'll guard against any value which is a blank string '', undefined or null (and not blank array or objects).
{
"type": "REQUIRED"
}
REGEX : You can specify a Regular Expression for pattern matching the current value of the component against it.
{
"type": "REGEX",
"meta": {
"pattern": "^(?=.*\\d)(?=.*[!@#$%^&*])(?=.*[a-z])(?=.*[A-Z]).{8,}quot;
}
}
RANGE : To check if the value falls in the numeric range between min and max in meta.
{
"type": "RANGE",
"meta": {
"min": 3,
"max": 10
}
}
LENGTH : Can work on both string and array values by checking value.length property between the min and max values specified in meta.
{
"type": "LENGTH",
"meta": {
"min": 3,
"max": 10
}
}
JSON : To validate the JSON value fed to a component. It'll try to parse it and set a validation error if the parsing fails.
{
"type": "JSON"
}
CUSTOM : In order to write a custom validator for custom needs.
{
"type": "CUSTOM",
"meta": {
"name": "myCustomValidator"
}
}
The corresponding validator function has to be specified in the caller environment by passing a validators object containing these custom validator functions as
validators: {
myCustomEmailValidator(value: string) {
return !value.includes("swiggy") ? "Not a valid swiggy email" : undefined;
}
}
A validator function takes value as input and returns either a string in case of an invalid value or undefined otherwise. undefined means there was no error and the value was valid.
disabled clause can be use to pass disabled property to the component. It can either take a boolean straight-forwardly or a Conditional config which has the following structure.
type ConditionalConfig = {
type: OperationType;
operator: ComparisonOperators | CompoundOperators;
leftOperand: string | ConditionalConfig;
rightOperand: string | ConditionalConfig;
};
The OperationType can be
ATOMIC: It's like a one level condition. A single expression like x === trueCOMPOUND: Compound condition can have multiple expressions joined via Compound operators like && or ||
The operators could be either compound operators as mentioned above or comparison operators like =, !=, <, <=, >, >=
Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.
Distributed under the MIT License. See LICENSE for more information.
