corrad-software/corrad-bp
9
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
corrad-bp/docs/form-builder-node-creation-guide.md
Afiq 3abc215b42 Add Layout Grid Component and Enhance Form Builder Functionality 
- Introduced a new 'layout-grid' component in FormBuilderComponents.vue, allowing users to create custom grid layouts with drag-and-drop capabilities.
- Enhanced ComponentPreview.vue to support the layout grid, including cell spanning and dynamic component placement within grid cells.
- Updated FormBuilderFieldSettingsModal.vue to include configuration options for the layout grid, such as grid dimensions, cell spanning, and layout presets.
- Improved form data handling in workflow pages to accommodate nested components within layout grids, ensuring accurate data extraction and management.
- Refactored styles across components to ensure a cohesive visual experience for the new layout grid functionality.
- Updated package.json to modify the deploy script for improved Prisma integration.
2025-08-07 18:59:17 +08:00

867 lines
26 KiB
Markdown
Raw Blame History

# Form Builder Node Creation Guide
This guide explains how to create new nodes/components for the form builder system. The form builder supports various types of components from simple text inputs to complex container components like repeating groups and layout grids.
## Table of Contents
1. [Overview](#overview)
2. [Component Types](#component-types)
3. [Basic Component Creation](#basic-component-creation)
4. [Container Component Creation](#container-component-creation)
5. [Complex Component Creation](#complex-component-creation)
6. [Component Registration](#component-registration)
7. [Settings Modal Integration](#settings-modal-integration)
8. [Component Preview Integration](#component-preview-integration)
9. [Drag & Drop Integration](#drag--drop-integration)
10. [Best Practices](#best-practices)
11. [Examples](#examples)
## Overview
The form builder system consists of several key files:
- **`FormBuilderComponents.vue`**: Defines available components and their metadata
- **`ComponentPreview.vue`**: Renders components in the form builder
- **`FormBuilderFieldSettingsModal.vue`**: Provides settings interface for components
- **`stores/formBuilder.js`**: Manages form state and component operations
## Component Types
### 1. Basic Components
Simple input components that collect data:
- Text inputs, textareas, numbers
- Select dropdowns, checkboxes, radio buttons
- Date/time pickers, file uploads
### 2. Container Components
Components that can hold other components:
- **Form Section**: Groups related fields
- **Repeating Group**: Allows multiple instances of the same fields
- **Layout Grid**: Custom grid layout with spanning capabilities
### 3. Advanced Components
Complex components with special functionality:
- Custom HTML with CSS/JS
- Conditional logic components
- API integration components
## Basic Component Creation
### Step 1: Define Component Metadata
Add your component to `FormBuilderComponents.vue`:
```javascript
{
type: 'my-component',
name: 'My Component',
category: 'Basic Inputs', // or 'Selection Inputs', 'Date and Time', 'Advanced', 'Layout'
icon: 'heroicons:document-text', // Use appropriate icon
description: 'Description of what this component does',
defaultProps: {
label: 'My Component',
name: 'my_component',
help: 'Help text for users',
required: false,
placeholder: 'Enter value...',
width: '100%',
gridColumn: 'span 6',
// Component-specific properties
myCustomProp: 'default value',
// Conditional Logic Properties
conditionalLogic: {
enabled: false,
conditions: [],
action: 'show',
operator: 'and'
}
}
}
```
### Step 2: Add Component Preview
Add rendering logic to `ComponentPreview.vue`:
```vue
<!-- My Component -->
<div v-else-if="component.type === 'my-component'" class="py-2">
<label v-if="component.props.label && component.props.showLabel !== false"
class="block text-sm font-medium text-gray-700 mb-2">
{{ component.props.label }}
<span v-if="component.props.required" class="text-red-500">*</span>
</label>
<!-- Component-specific rendering -->
<div class="my-component-wrapper">
<input
type="text"
:placeholder="component.props.placeholder"
:required="component.props.required"
class="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>
</div>
<div v-if="component.props.help" class="mt-1 text-xs text-gray-500">
{{ component.props.help }}
</div>
</div>
```
### Step 3: Add Settings Modal Support
Add settings to `FormBuilderFieldSettingsModal.vue`:
```javascript
// In the script section, add to getComponentTypeName function
getComponentTypeName(type) {
const typeNames = {
// ... existing types
'my-component': 'My Component'
}
return typeNames[type] || 'Unknown Component'
}
// Add to getComponentIcon function
getComponentIcon(type) {
const icons = {
// ... existing icons
'my-component': 'heroicons:document-text'
}
return icons[type] || 'heroicons:question-mark-circle'
}
// Add to getComponentDescription function
getComponentDescription(type) {
const descriptions = {
// ... existing descriptions
'my-component': 'A custom component for collecting specific data'
}
return descriptions[type] || 'Component description'
}
```
## Container Component Creation
Container components are more complex as they can hold other components.
### Example: Creating a Custom Container
```javascript
// In FormBuilderComponents.vue
{
type: 'custom-container',
name: 'Custom Container',
category: 'Layout',
icon: 'material-symbols:view-in-ar',
description: 'A custom container that can hold other components',
defaultProps: {
label: 'Custom Container',
name: 'custom_container',
help: 'Drag components here to add them',
showHeader: true,
headerBackground: '#f9fafb',
backgroundColor: '#ffffff',
showBorder: true,
borderStyle: 'solid', // 'solid', 'dashed', 'dotted'
spacing: 'normal', // 'compact', 'normal', 'relaxed'
children: [], // Array to hold nested components
// Conditional Logic Properties
conditionalLogic: {
enabled: false,
conditions: [],
action: 'show',
operator: 'and'
}
}
}
```
### Container Component Preview
```vue
<!-- Custom Container Component -->
<div v-else-if="component.type === 'custom-container'" class="py-2">
<div
class="custom-container-wrapper"
:class="{
'has-border': component.props.showBorder,
'border-dashed': component.props.borderStyle === 'dashed',
'border-dotted': component.props.borderStyle === 'dotted',
'spacing-compact': component.props.spacing === 'compact',
'spacing-relaxed': component.props.spacing === 'relaxed'
}"
:style="{
backgroundColor: component.props.backgroundColor || '#ffffff',
borderColor: component.props.showBorder ? '#e5e7eb' : 'transparent'
}"
>
<!-- Container Header -->
<div
v-if="component.props.showHeader"
class="container-header"
:style="{ backgroundColor: component.props.headerBackground || '#f9fafb' }"
>
<h3 class="container-title">
{{ component.props.label || 'Custom Container' }}
</h3>
<p v-if="component.props.description" class="container-description">
{{ component.props.description }}
</p>
</div>
<!-- Container Content -->
<div class="container-content">
<!-- In preview mode, show only the nested components -->
<div v-if="isPreview" class="container-fields">
<div v-if="component.props.children && component.props.children.length > 0"
class="grid grid-cols-12 gap-2">
<template v-for="(childComponent, childIndex) in component.props.children"
:key="childIndex">
<div
class="form-component"
:style="{
gridColumn: childComponent.props.gridColumn || 'span 6'
}"
>
<component-preview :component="childComponent" :is-preview="true" />
</div>
</template>
</div>
</div>
<!-- In form builder mode, show drop zone -->
<div v-else class="container-drop-zone">
<!-- Nested components rendered in grid -->
<div v-if="component.props.children && component.props.children.length > 0"
class="nested-components">
<draggable
v-model="component.props.children"
group="form-components"
item-key="id"
handle=".drag-handle"
ghost-class="ghost"
animation="300"
class="grid grid-cols-12 gap-2"
@end="onNestedDragEnd"
@add="onNestedComponentAdd"
>
<template #item="{ element: childElement, index: childIndex }">
<div
class="form-component relative border rounded-md overflow-hidden transition-all duration-200 bg-white"
:class="'border-gray-200 hover:border-blue-300 hover:shadow-md'"
:style="{
gridColumn: childElement.props.gridColumn || 'span 6'
}"
>
<!-- Component actions -->
<div class="component-actions absolute right-1 top-1 flex space-x-1 z-10">
<button
class="p-1 text-gray-400 hover:text-blue-600 rounded"
title="Component settings"
@click.stop="openNestedComponentSettings(childElement)"
>
<Icon name="heroicons:cog-6-tooth" class="w-3 h-3" />
</button>
<button
class="p-1 text-gray-400 hover:text-red-500 rounded"
title="Remove from container"
@click.stop="removeFromSection(component.id, childIndex)"
>
<Icon name="material-symbols:close" class="w-3 h-3" />
</button>
</div>
<div class="p-2">
<component-preview :component="childElement" :is-preview="false" />
</div>
</div>
</template>
</draggable>
</div>
<!-- Drop zone placeholder -->
<div v-else class="drop-placeholder">
<Icon name="material-symbols:add-box-outline" class="w-8 h-8 text-gray-300 mx-auto mb-2" />
<p class="text-sm text-gray-500 text-center mb-1">Drop Components Here</p>
<p class="text-xs text-gray-400 text-center">
Drag form fields from the sidebar to add them to this container
</p>
</div>
</div>
</div>
</div>
</div>
```
## Complex Component Creation
### Example: Repeating Group Component
Repeating groups are complex container components that allow multiple instances of the same fields.
#### 1. Component Definition
```javascript
{
type: 'repeating-group',
name: 'Repeating Group',
category: 'Layout',
icon: 'material-symbols:view-in-ar',
description: 'Group of fields that can be repeated multiple times',
defaultProps: {
label: 'Repeating Group',
name: 'repeating_group',
help: 'Add multiple instances of the same fields',
buttonText: 'Add Item',
showPlaceholder: true,
children: [], // Array to hold nested components
// Conditional Logic Properties
conditionalLogic: {
enabled: false,
conditions: [],
action: 'show',
operator: 'and'
}
}
}
```
#### 2. Drag & Drop Integration
Container components need special drag & drop handling:
```javascript
// In ComponentPreview.vue, add these functions:
const handleSectionDrop = (event, containerId) => {
event.preventDefault();
event.stopPropagation();
// Reset drag state
if (sectionDropStates.value[containerId]) {
sectionDropStates.value[containerId].isDraggingOver = false;
}
try {
// Get the dropped component data
let componentData = null;
try {
componentData = JSON.parse(event.dataTransfer.getData('text/plain') || '{}');
} catch (parseError) {
componentData = window.__draggedComponentData || {};
}
if (!componentData.type) {
console.warn('No valid component data found in drop event');
return;
}
// Create a new component instance
const newComponent = {
id: `${componentData.type}_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`,
type: componentData.type,
name: componentData.name,
props: {
...componentData.defaultProps,
gridColumn: 'span 6',
width: '50%',
label: componentData.defaultProps.label || componentData.name || `${componentData.type.charAt(0).toUpperCase() + componentData.type.slice(1)} Field`,
name: componentData.defaultProps.name || `${componentData.type}_${Date.now()}`
}
};
// Find the target container
const container = findContainerRecursively(containerId);
if (container && (container.type === 'form-section' || container.type === 'repeating-group')) {
// Initialize children array if it doesn't exist
if (!container.props.children) {
container.props.children = [];
}
// Add the component to the container
container.props.children.push(newComponent);
// Update the container in the form store
formStore.updateComponent(container);
console.log('Component added to container:', newComponent);
} else {
console.warn('Container not found or invalid container type:', containerId);
}
} catch (error) {
console.error('Error dropping component into container:', error);
}
};
```
#### 3. Container Search Function
```javascript
// Helper function to find container at any nesting level
const findContainerRecursively = (containerId, components = formStore.formComponents, childId = null) => {
for (const component of components) {
// Check if this is the target container
if (containerId && component.id === containerId) {
return component;
}
// If searching for parent by child ID, check if this component contains the child
if (childId && component.props.children && Array.isArray(component.props.children)) {
const hasChild = component.props.children.some(child => child.id === childId);
if (hasChild) {
return component;
}
}
// If this component has children, search recursively
if (component.props.children && Array.isArray(component.props.children)) {
const found = findContainerRecursively(containerId, component.props.children, childId);
if (found) {
return found;
}
}
// Special handling for Layout Grid components - search in their cells
if (component.type === 'layout-grid' && component.props.cells) {
for (const cell of component.props.cells) {
if (cell.component) {
// Check if this cell's component is the target container
if (containerId && cell.component.id === containerId) {
return cell.component;
}
// If searching for parent by child ID, check if this cell's component contains the child
if (childId && cell.component.props.children && Array.isArray(cell.component.props.children)) {
const hasChild = cell.component.props.children.some(child => child.id === childId);
if (hasChild) {
return cell.component;
}
}
// Recursively search in the cell's component children
if (cell.component.props.children && Array.isArray(cell.component.props.children)) {
const found = findContainerRecursively(containerId, cell.component.props.children, childId);
if (found) {
return found;
}
}
}
}
}
}
return null;
};
```
## Component Registration
### 1. Add to Available Components
In `FormBuilderComponents.vue`, add your component to the `availableComponents` array:
```javascript
const availableComponents = [
// ... existing components
{
type: 'my-component',
name: 'My Component',
category: 'Basic Inputs',
icon: 'heroicons:document-text',
description: 'A custom component for collecting data',
defaultProps: {
// ... your default props
}
}
];
```
### 2. Add Category Support
If you're creating a new category, add it to the template:
```vue
<!-- My Category -->
<div class="component-category mb-4">
<h3 class="text-gray-700 text-xs font-semibold px-3 mb-2 uppercase tracking-wider">My Category</h3>
<div class="grid grid-cols-2 gap-1 px-2">
<div
v-for="component in getComponentsByCategory('My Category')"
:key="component.type"
class="component-item rounded p-2 flex flex-col items-center justify-center cursor-grab hover:bg-gray-100 transition-colors border border-gray-200"
:class="{ 'hidden': !matchesSearch(component) }"
draggable="true"
@dragstart="onDragStart($event, component)"
@dragend="onDragEnd($event)"
@click="addComponent(component)"
>
<Icon :name="component.icon" class="mb-1 w-5 h-5 text-gray-600" />
<span class="text-xs text-gray-600 text-center">{{ component.name }}</span>
</div>
</div>
</div>
```
## Settings Modal Integration
### 1. Add Component Type Support
In `FormBuilderFieldSettingsModal.vue`:
```javascript
// Add to getComponentTypeName function
getComponentTypeName(type) {
const typeNames = {
// ... existing types
'my-component': 'My Component'
}
return typeNames[type] || 'Unknown Component'
}
// Add to getComponentIcon function
getComponentIcon(type) {
const icons = {
// ... existing icons
'my-component': 'heroicons:document-text'
}
return icons[type] || 'heroicons:question-mark-circle'
}
// Add to getComponentDescription function
getComponentDescription(type) {
const descriptions = {
// ... existing descriptions
'my-component': 'A custom component for collecting specific data'
}
return descriptions[type] || 'Component description'
}
```
### 2. Add Specific Settings
For components with specific settings, add them to the settings modal:
```vue
<!-- My Component Specific Settings -->
<div v-if="component.type === 'my-component'" class="settings-section">
<div class="section-header">
<h4 class="section-title">
<Icon name="heroicons:cog-6-tooth" class="w-5 h-5 mr-2" />
My Component Settings
</h4>
<p class="section-description">Configure specific settings for this component</p>
</div>
<div class="section-content">
<FormKit
type="text"
label="Custom Property"
name="myCustomProp"
v-model="component.props.myCustomProp"
help="Set a custom property for this component"
:classes="{ outer: 'field-wrapper' }"
/>
<!-- Add more component-specific settings -->
</div>
</div>
```
## Component Preview Integration
### 1. Add Preview Rendering
In `ComponentPreview.vue`, add your component's preview rendering:
```vue
<!-- My Component Preview -->
<div v-else-if="component.type === 'my-component'" class="py-2">
<label v-if="component.props.label && component.props.showLabel !== false"
class="block text-sm font-medium text-gray-700 mb-2">
{{ component.props.label }}
<span v-if="component.props.required" class="text-red-500">*</span>
</label>
<!-- Component-specific rendering -->
<div class="my-component-wrapper">
<input
type="text"
:placeholder="component.props.placeholder"
:required="component.props.required"
class="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>
</div>
<div v-if="component.props.help" class="mt-1 text-xs text-gray-500">
{{ component.props.help }}
</div>
</div>
```
### 2. Handle Preview Mode
Make sure your component handles the `isPreview` prop correctly:
```vue
<!-- My Component with Preview Mode -->
<div v-else-if="component.type === 'my-component'" class="py-2">
<label v-if="component.props.label && component.props.showLabel !== false"
class="block text-sm font-medium text-gray-700 mb-2">
{{ component.props.label }}
<span v-if="component.props.required" class="text-red-500">*</span>
</label>
<!-- Component-specific rendering -->
<div class="my-component-wrapper">
<input
v-if="!isPreview"
type="text"
:placeholder="component.props.placeholder"
:required="component.props.required"
class="w-full px-3 py-2 border border-gray-300 rounded-md focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-blue-500"
/>
<div v-else class="w-full px-3 py-2 border border-gray-300 rounded-md bg-gray-50 text-gray-500">
{{ component.props.placeholder || 'Preview mode' }}
</div>
</div>
<div v-if="component.props.help" class="mt-1 text-xs text-gray-500">
{{ component.props.help }}
</div>
</div>
```
## Drag & Drop Integration
### 1. Basic Drag & Drop
For basic components, drag & drop is handled automatically by the form builder system.
### 2. Container Drag & Drop
For container components, you need to implement custom drag & drop handlers:
```javascript
// In ComponentPreview.vue
// Drag over handler
const handleSectionDragOver = (event, containerId) => {
event.preventDefault();
event.stopPropagation();
// Initialize container drop state if it doesn't exist
if (!sectionDropStates.value[containerId]) {
sectionDropStates.value[containerId] = { isDraggingOver: false };
}
sectionDropStates.value[containerId].isDraggingOver = true;
};
// Drag leave handler
const handleSectionDragLeave = (event, containerId) => {
event.preventDefault();
event.stopPropagation();
// Only hide the drag over state if we're actually leaving the drop zone
const rect = event.currentTarget.getBoundingClientRect();
const isOutside = (
event.clientX < rect.left ||
event.clientX > rect.right ||
event.clientY < rect.top ||
event.clientY > rect.bottom
);
if (isOutside && sectionDropStates.value[containerId]) {
sectionDropStates.value[containerId].isDraggingOver = false;
}
};
// Drag enter handler
const handleSectionDragEnter = (event, containerId) => {
event.preventDefault();
event.stopPropagation();
// Initialize container drop state if it doesn't exist
if (!sectionDropStates.value[containerId]) {
sectionDropStates.value[containerId] = { isDraggingOver: false };
}
};
```
### 3. Nested Component Management
For container components, you need to handle nested component operations:
```javascript
// Remove component from container
const removeFromSection = (sectionId, childIndex) => {
const section = findContainerRecursively(sectionId);
if (section && section.props.children) {
const removedComponent = section.props.children.splice(childIndex, 1)[0];
if (removedComponent) {
formStore.updateComponent(section);
console.log('Component deleted from section:', removedComponent);
}
}
};
// Open nested component settings
const openNestedComponentSettings = (component) => {
selectedNestedComponent.value = { ...component };
showNestedSettingsModal.value = true;
console.log('Opening settings for component:', component);
};
// Save nested component settings
const saveNestedComponentSettings = (updatedComponent) => {
if (!updatedComponent || !selectedNestedComponent.value) return;
// Find the parent container at any nesting level
const parentContainer = findContainerRecursively(null, formStore.formComponents, updatedComponent.id);
if (parentContainer) {
// Find and update the component in the parent's children
const childIndex = parentContainer.props.children.findIndex(child => child.id === updatedComponent.id);
if (childIndex !== -1) {
parentContainer.props.children[childIndex] = updatedComponent;
formStore.updateComponent(parentContainer);
console.log('Nested component updated in parent:', parentContainer);
}
} else {
// If not found in main form, it might be in a Layout Grid cell
console.log('Parent container not found, component might be in Layout Grid');
}
showNestedSettingsModal.value = false;
selectedNestedComponent.value = null;
};
```
## Best Practices
### 1. Component Design
- **Consistent Props**: Use consistent prop names across components
- **Default Values**: Always provide sensible default values
- **Validation**: Include validation rules where appropriate
- **Accessibility**: Ensure components are accessible (ARIA labels, keyboard navigation)
### 2. Container Components
- **Children Array**: Always initialize `children: []` for container components
- **Drag & Drop**: Implement proper drag & drop handlers
- **Nested Settings**: Support settings for nested components
- **Recursive Search**: Use `findContainerRecursively` for finding parent containers
### 3. Performance
- **Lazy Loading**: Consider lazy loading for complex components
- **Memoization**: Use computed properties for expensive calculations
- **Event Handling**: Properly clean up event listeners
### 4. Error Handling
- **Validation**: Validate component props
- **Fallbacks**: Provide fallback rendering for missing props
- **Logging**: Add appropriate console logging for debugging
## Examples
### Example 1: Simple Text Input
```javascript
// Component definition
{
type: 'custom-text',
name: 'Custom Text Input',
category: 'Basic Inputs',
icon: 'heroicons:document-text',
description: 'A custom text input with special styling',
defaultProps: {
label: 'Custom Text',
name: 'custom_text',
help: 'Enter your custom text',
placeholder: 'Type here...',
required: false,
width: '100%',
gridColumn: 'span 6',
conditionalLogic: {
enabled: false,
conditions: [],
action: 'show',
operator: 'and'
}
}
}
```
### Example 2: Advanced Container
```javascript
// Component definition
{
type: 'advanced-container',
name: 'Advanced Container',
category: 'Layout',
icon: 'material-symbols:view-in-ar',
description: 'An advanced container with custom styling and behavior',
defaultProps: {
label: 'Advanced Container',
name: 'advanced_container',
help: 'A container with advanced features',
showHeader: true,
headerBackground: '#f9fafb',
backgroundColor: '#ffffff',
showBorder: true,
borderStyle: 'solid',
spacing: 'normal',
children: [],
customFeature: 'default',
conditionalLogic: {
enabled: false,
conditions: [],
action: 'show',
operator: 'and'
}
}
}
```
### Example 3: Complex Component with API Integration
```javascript
// Component definition
{
type: 'api-select',
name: 'API Select',
category: 'Advanced',
icon: 'heroicons:globe-alt',
description: 'Dropdown populated from API endpoint',
defaultProps: {
label: 'API Select',
name: 'api_select',
help: 'Select from API data',
required: false,
apiEndpoint: '',
apiMethod: 'GET',
valueField: 'id',
labelField: 'name',
placeholder: 'Select an option...',
width: '100%',
gridColumn: 'span 6',
conditionalLogic: {
enabled: false,
conditions: [],
action: 'show',
operator: 'and'
}
}
}
```
## Conclusion
Creating new form builder nodes requires understanding the system architecture and following established patterns. Start with simple components and gradually work up to complex container components. Always test thoroughly and ensure proper integration with the existing form builder system.
For complex components, consider breaking them down into smaller, reusable parts and following the established patterns for drag & drop, settings, and preview rendering.
Reference in New Issue View Git Blame Copy Permalink