Testing locally

• Run npm link within the root directory of render-chan.
• This will create a global symlink link {prefix}/lib/node_modules/<package> {prefix} is an npm variable that will depend on your operating system. To know the current value for your specific case, you can run npm prefix –g.
• You can use this package now anywhere in your system locally.
• Run npm link render-chan in your project where you want to test render-chan.
• Note: It is crucial to build the package whenever you make changes, as we are currently referencing the build file.

Render-Chan

Render-Chan Form is a React component designed to facilitate the creation of dynamic forms. Leveraging the Ant Design library for styling and its Form components for form structure, Render-Chan Form streamlines the process of building dynamic form hierarchies. By simply providing a JSON file containing form properties, Render-Chan Form generates the corresponding dynamic form structure with ease.

Main Features

• ⌛️ Easy to style and customize.
• 📡 Utilizes the Ant Design (ant-d) library for forms and styling.
• 📃 Supports JSON files for effortless form creation. Refer to Creating a JSON File.
• 📂 You can seamlessly incorporate form components from Render-Chan. Explore the Exported Components.

Installation

npm install render-chan

Example

Live demo on Sandbox

Render Chan accepts three props:

• jsonType: This prop takes JSON data that represents the form configuration. You can use it to dynamically generate forms based on the provided JSON structure, refer to the Creating a JSON File.

• currentProfileType: The currentProfileType prop indicates the current user's profile type, which can be utilized to customize form behavior based on user roles. For more information, refer to the User Role Reference.

• formProperties: The formProperties prop is an object containing multiple form properties used for rendering forms. It offers various configuration options to tailor form behavior. To learn more Form Properties Reference.

In your index.js, import the RenderChan and use it as shown below:

import { RenderChan } from "render-chan";
import { Form } from "antd";
import jsonData from "./jsonData";
import {
	filterQuestionBasedOnUserRole,
	getQuestionLabelFromUserRole,
} from "./utils";

export default function App() {
	const userRole = "Student";
	const [form] = Form.useForm();

	const formProperties = {
		form: form,
		formName: "CustomForm",
		formErrors: [],
		formSubmitText: "Submit",
		useDefaultFormSubmit: true,
		useFormListErrors: true,
		onFinish: () =>
			console.log("Submitted the form", form.getFieldsValue()),
		filterQuestionBasedOnUserRole: filterQuestionBasedOnUserRole,
		getQuestionLabelFromUserRole: getQuestionLabelFromUserRole,
	};

	return (
		<div className="App">
			<h1>Render Chan Form</h1>
			<RenderChan
				jsonType={jsonData}
				currentProfileType={userRole}
				formProperties={formProperties}
			/>
		</div>
	);
}

jsonData.json

{
	"data": [
		{
			"id": "first_name",
			"text": "What is your first name?",
			"order": 1,
			"type": "TextInput",
			"renderingType": "static",
			"isRequired": true,
			"placeholder_text": "enter your first name",
			"help_text": "This is a required field please enter your name in the box.",
			"options": [],
			"is_required_teacher": true,
			"is_required_student": true,
			"text_for_teacher": "7b. If \"Yes,\" select the type(s) of disability that applies to you.",
			"text_for_student": "7b. If \"Yes,\" select the type(s) of disability that applies to you."
		},
		{
			"is_required_teacher": true,
			"is_required_student": true,
			"text_for_teacher": "7b. If \"Yes,\" select the type(s) of disability that applies to you.",
			"text_for_student": "7b. If \"Yes,\" select the type(s) of disability that applies to you.",
			"help_text": null,
			"id": "disability",
			"text": "Do you have any disability?",
			"order": 2,
			"type": "RadioButtonCircle",
			"renderingType": "static",
			"isRequired": true,
			"options": [
				{
					"question_id": "disability",
					"children": ["disability_type"],
					"id": "disability_yes",
					"title": "Yes",
					"mapping": null
				},
				{
					"question_id": "disability",
					"children": [],
					"id": "disability_no",
					"title": "No",
					"mapping": "NO"
				}
			]
		},
		{
			"id": "disability_type",
			"text": "What is your disability type?",
			"order": 3,
			"type": "Checkbox",
			"renderingType": "dynamic",
			"isRequired": true,
			"is_required_teacher": true,
			"is_required_student": true,
			"text_for_teacher": "7b. If \"Yes,\" select the type(s) of disability that applies to you.",
			"text_for_student": "7b. If \"Yes,\" select the type(s) of disability that applies to you.",
			"options": [
				{
					"question_id": "disability_type",
					"id": "disability_type1",
					"title": "Mobility",
					"mapping": null
				},
				{
					"question_id": "disability_type",
					"id": "disability_type2",
					"title": "Pain-related",
					"mapping": null
				},
				{
					"question_id": "disability_type",
					"id": "disability_type3",
					"title": "Seeing",
					"mapping": null
				}
			]
		}
	]
}

Creating a JSON file

To create a dynamic form, you need to construct a JSON file that encompasses all the essential details for form construction. This JSON file should include the following properties:

• id: This represents a unique form field identifier passed to the form element.

• type: Specifies the type of component for the form field (e.g., InputType, Checkbox, etc.). A detailed description of the current form field's type is referenced here available form fields type

• renderingType: Determines how the form field should appear, whether as a "static" field or a "dynamic" field.

  • A "static" field is displayed on the initial load of the form.
  • A "dynamic" field's appearance depends on the options of other form fields. For instance, if you have a question such as "Do you have any disability?" with options "Yes" and "No," the type for this question would be "static." However, if the user selects "Yes," you might want to show another question, "What type of disability, please specify?" In this case, the type for the second question would be "dynamic."

• options property plays a crucial role in configuring components like Checkboxes and RadioButtons within your dynamic forms. It is designed to specify the available option values and should be structured as an array of objects.

  • To define an option, you should adhere to a specific pattern with the following properties:

    • question_id: This property corresponds to the ID of the question to which this option belongs.
    • id: The id property serves as a unique identifier for the option.
    • title: The title property defines the text that will be displayed as the label for the option.
    • children: This property consists of an array of dynamic question_id values, determining which questions trigger the display of dynamic form fields.

• isRequired: Indicates whether the input for this field is required or not.

• text: Provides the question or label associated with the form field.

• placeholder_text: Text for the placeholder within a form field.

• help_text: Text for the tooltip of the question.

Building form properties

After building the JSON configuration for your form, you will need to pass certain formProperties to Render-Chan. These formProperties play a crucial role in determining how the form will be rendered and behave according to your specifications.

• form: This parameter expects a form object created using Ant Design's form.useForm().

• formName: Specify a form title using this option.

• formErrors: Provide an array of form errors, which can originate from backend validation or custom validation logic.

• formSubmitText: You can set the name for the form's submit button using this option. The default value is "Save".

• isLoadingMutation: Specify the time to await a form submit callback from the backend to determine if the form has been successfully saved or not.

• useDefaultFormSubmit: When set to a boolean value, you can define your custom way of submitting the form. If true, a default submit button will be displayed.

• useFormListErrors: Enabling this option (by setting it to true) allows you to display form errors at the top of the form.

• onFinish: Define a callback function to handle the form's submit event.

• filterQuestionBasedOnUserRole: Utilize this function to filter questions for users based on their assigned roles.

• getQuestionLabelFromUserRole: This utility function is used to retrieve the question label for a field based on the user's role.

User Role

You can create your own custom function to show the text based on the user role

export const HumanizedUserRoles = {
	TEACHER: "Teacher",
	STUDENT: "Student",
};

export function filterQuestionBasedOnUserRole(question) {
	// using destructing get the specific comparison variables required for this filter function
	const {
		role: userRole,
		is_required_teacher: isRequiredTeacher,
		is_required_student: isRequiredStudent,
	} = question;
	// filter the question based on the user role and what is required by the profile type
	// for now clinician and researchers are treated as the same thing. Same with caretakers of patients and family
	if (userRole === HumanizedUserRoles.TEACHER && isRequiredTeacher) {
		return question;
	} else if (userRole === HumanizedUserRoles.STUDENT && isRequiredStudent) {
		return question;
	}
}

/**
 * Retrieves the question label based on the user's role.
 * @param {object} userRole - The user's role and the corresponding question labels.
 * @param {string} textForTeacher - the text label for teacher role
 * @param {string} textForStudent - the text label for teacher student
 * @returns {string} - The question label.
 */
export function getQuestionLabelFromUserRole({
	role: userRole,
	text_for_teacher: textForTeacher,
	text_for_student: textForStudent,
}) {
	switch (userRole) {
		case HumanizedUserRoles.TEACHER:
			return textForTeacher;
		case HumanizedUserRoles.STUDENT:
			return textForStudent;
		default:
			console.error(
				"This user role is not supported, please contact your admin",
				userRole
			);
	}
}

Exported Components

Render-Chan offers a variety of components that you can use in your project. Here's a list of available components along with a brief description for each:

• RenderChan: The main component for rendering dynamic forms using JSON configuration.

• HelpTextPopover: A component for displaying help text and questions with popovers.

• CheckBoxRc: A customizable checkbox component.

• CustomTextAreaRc: A component for customizing text areas.

• DatePickerRc: Use this component for date picking.

• DropdownRc: A dropdown component for selecting options.

• RadioButtonBoxRc: Customize radio buttons in a box layout.

• RadioButtonCircleRc: Customize radio buttons in a circular layout.

• SelectMultipleBoxRc: Select multiple options in a box layout.

• SelectMultipleRc: Select multiple options.

• TextInputRc: Customize text input fields.

• TreeSelectRc: Use this component for tree selection.

• UploadProfileRc: A component for uploading profiles.

These components are available for you to use in your React application to enhance your form-building experience with Render-Chan.

Available form field types

Should be used as a string in type property.

• Checkbox
• DatePicker
• DatePickerYear
• RadioButtonBox
• RadioButtonCircle
• DropDown
• TextArea
• TextInput
• WebLink
• UploadPicture
• SelectMultipleBox
• SelectMultiple
• TreeSelect

License

MIT Licensed. Copyright (c) Rahib Uzair Ahmed 2023.