Fractal Platform Controls & Components Guide

0. Introduction

What Are Controls and Components?

In Fractal Platform, you build forms by placing controls and components on them. These are UI elements that connect to your JSON data and provide interactive functionality.

🎯 Key Concepts:

Document (Source): The JSON data that feeds your control
UI Dimension: Defines what type of control/component to render and its properties
Controls: Built on a single JSON attribute
Components: Built on multiple JSON attributes or a hierarchy

How Controls Work

Every control needs two things:

// 1. Document - Your data source
{"Control": "Hello World"}

// 2. UI - How to display it
{"Control": {"ControlType": "Label"}}

💡 Quick Example: If you want to show text on your form, you put "Hello World" in your Document and set ControlType to "Label" in your UI. That's it!

1. Understanding Controls vs Components

What's the Difference?

Feature	Controls	Components
Data Structure	Single attribute	Multiple attributes or hierarchy
Example Data	"Bob" or 25 or true	{Name: "Bob", Age: 25}
Complexity	Simple	Complex
Use Cases	Text fields, checkboxes, buttons	Charts, maps, grids, comments

Control Example

CONTROL TextBox

Description: Simple text input field

// Document - Just a string
{"Control": "This is TextBox"}

// UI - Specify it's a TextBox
{"Control": {"ControlType": "TextBox"}}

Component Example

COMPONENT Chart

Description: Bar chart with multiple data points

// Document - Complex object with title and data
{
  "Control": {
    "Title": {
      "Name": "Bar",
      "X": "Bars",
      "Y": "Value"
    },
    "Columns": [
      {"Name": "One", "Value": 10},
      {"Name": "Two", "Value": 20}
    ]
  }
}

// UI - Specify Chart type and style
{
  "Control": {
    "ControlType": "Chart",
    "Style": "Type:Bar"
  }
}

2. Text & Input Controls

CONTROL Label

Description: Display read-only text

// Document
{"Control": "This is Label"}

// UI
{"Control": {"ControlType": "Label"}}

💡 Use Case: Headers, descriptions, or any text that users shouldn't edit.

CONTROL Link

Description: Clickable hyperlink

// Document
{"Control": "Click here"}

// UI
{"Control": {"ControlType": "Link"}}

CONTROL TextBox

Description: Single-line text input

// Document
{"Control": "Type here..."}

// UI
{"Control": {"ControlType": "TextBox"}}

💡 Use Case: Names, email addresses, short answers.

CONTROL TextBox - Password

Description: Password input (hidden characters)

// Document
{"Control": "secretpassword"}

// UI
{
  "Control": {
    "ControlType": "TextBox",
    "Style": "Type:Password"
  }
}

CONTROL TextBox - Captcha

Description: Bot protection input field

// Document
{"Control": "Enter number here"}

// UI
{
  "Control": {
    "ControlType": "TextBox",
    "Style": "Type:Captcha"
  }
}

CONTROL RichTextBox

Description: Multi-line text area

// Document
{"Control": "Long text here..."}

// UI
{"Control": {"ControlType": "RichTextBox"}}

💡 Use Case: Comments, descriptions, or any long text.

CONTROL Phone

Description: Phone number input with formatting

// Document
{"Control": "+380981112233"}

// UI
{"Control": {"ControlType": "Phone"}}

3. Selection Controls

CONTROL CheckBox

Description: Boolean yes/no checkbox

// Document
{"Control": true}

// UI
{"Control": {"ControlType": "CheckBox"}}

💡 Use Case: Accept terms, enable/disable features, yes/no questions.

CONTROL RadioButton

Description: Choose one option from multiple choices

// Document
{
  "Control": {
    "Option1": true,
    "Option2": false
  }
}

// UI
{"Control": {"ControlType": "RadioButton"}}

💡 Use Case: Gender selection, shipping method, payment type.

CONTROL ComboBox

Description: Dropdown list to choose from predefined values

// Document - Selected value
{"Control": "One"}

// Enum - Available options
{"Control": {"Items": ["One", "Two", "Three"]}}

// UI
{"Control": {"ControlType": "ComboBox"}}

📝 Note: ComboBox requires an Enum dimension that defines the list of available items.

CONTROL Button

Description: Regular clickable button

// Document
{"Control": "Click Me"}

// UI
{"Control": {"ControlType": "Button"}}

CONTROL Button - Link

Description: Button styled as a link

// Document
{"Control": "Go Back"}

// UI
{
  "Control": {
    "ControlType": "Button",
    "Style": "Type:Link"
  }
}

CONTROL Button - Submit

Description: Submit button that sends form data

// Document
{"Control": "Save"}

// UI
{
  "Control": {
    "ControlType": "Button",
    "Style": "Type:Submit"
  }
}

⚠️ Important: Submit button sends all changed values in the form to the server.

4. Data Display Controls

CONTROL Grid

Description: Display data in table format

// Document - Array of objects
{
  "Control": [
    {"Name": "Bob", "Age": 15},
    {"Name": "Rebeca", "Age": 20}
  ]
}

// UI
{"Control": {"ControlType": "Grid"}}

💡 Use Case: User lists, product catalogs, any tabular data.

CONTROL Grid - Link

Description: Grid where rows are clickable links

// Document
{
  "Control": [
    {"Name": "Bob", "Age": 15},
    {"Name": "Rebeca", "Age": 20}
  ]
}

// UI
{
  "Control": {
    "ControlType": "Grid",
    "Style": "Type:Link"
  }
}

CONTROL TreeView

Description: Hierarchical tree structure

// Document
{
  "Control": [
    {"Parent": null, "Name": "MyParent", "Text": "My Parent"},
    {"Parent": "MyParent", "Name": "MyChildA", "Text": "My Child A"},
    {"Parent": "MyParent", "Name": "MyChildB", "Text": "My Child B"}
  ]
}

// UI
{"Control": {"ControlType": "TreeView"}}

💡 Use Case: Folder structures, organization charts, category hierarchies.

CONTROL Raw

Description: Render raw HTML

// Document
{"Control": "Bold text"}

// UI
{"Control": {"ControlType": "Raw"}}

⚠️ Security Warning: Be careful with Raw control as it can execute HTML/JavaScript. Only use with trusted content.

CONTROL UploadFile

Description: File upload button

// Document
{"Control": ""}

// UI
{"Control": {"ControlType": "UploadFile"}}

5. Media Controls

CONTROL Picture

Description: Display an image

// Document - URL to image
{"Control": "https://example.com/image.jpg"}

// UI
{"Control": {"ControlType": "Picture"}}

CONTROL Picture - QRCode

Description: Generate QR code from text

// Document - Text to encode
{"Control": "https://mywebsite.com"}

// UI
{
  "Control": {
    "ControlType": "Picture",
    "Style": "Type:QRCode"
  }
}

💡 Use Case: Sharing links, contact information, WiFi credentials.

CONTROL Video - mp4

Description: Embedded video player

// Document - Video file name or URL
{"Control": "MyVideo.mp4"}

// UI
{"Control": {"ControlType": "Media"}}

CONTROL Video - Youtube

Description: Embedded YouTube video

// Document - YouTube URL
{"Control": "https://www.youtube.com/watch?v=LhOSM6uCWxk"}

// UI
{
  "Control": {
    "ControlType": "Media",
    "Style": "Type:Youtube"
  }
}

CONTROL Audio - mp3

Description: Audio player

// Document
{"Control": "MyAudio.mp3"}

// UI
{
  "Control": {
    "ControlType": "Media",
    "Style": "Type:Audio"
  }
}

6. Date & Time Controls

CONTROL Calendar

Description: Date picker

// Document - Date in YYYY-MM-DD format
{"Control": "2023-01-01"}

// UI
{"Control": {"ControlType": "Calendar"}}

💡 Use Case: Birthdays, deadlines, appointment scheduling.

CONTROL Time

Description: Time picker

// Document - Time in HH:MM format
{"Control": "12:30"}

// UI
{"Control": {"ControlType": "Time"}}

7. Components

Components are more complex than controls because they work with structured data containing multiple fields. Let's explore each component in detail.

COMPONENT Tags

Description: Display multiple tags/labels

// Document - Array of strings
{"Control": ["JavaScript", "React", "Node.js"]}

// UI
{"Control": {"ControlType": "Tags"}}

💡 Use Case: Skills, categories, keywords, labels.

COMPONENT Likes

Description: Like button that adds user name to array

// Document - Array of usernames who liked
{"Control": ["Alice", "Bob"]}

// UI
{"Control": {"ControlType": "Likes"}}

📝 How it works: When a user clicks the like button, their username is automatically added to the Control array.

COMPONENT Messages

Description: List of messages (simple chat)

// Document - Array of message objects
{
  "Control": [
    {
      "OnDate": "2023-01-01",
      "Text": "Hello World!",
      "Who": "Guest"
    }
  ]
}

// UI
{"Control": {"ControlType": "Messages"}}

💡 Use Case: Simple chat interface, message boards, notifications.

COMPONENT Comments

Description: Rich comment system with avatars and pictures

// Document - Array of comment objects
{
  "Control": [
    {
      "Avatar": "Guest.png",
      "OnDate": "2023-01-01",
      "Picture": "Message.jpg",
      "Text": "Great post!",
      "Who": "Guest"
    }
  ]
}

// UI
{"Control": {"ControlType": "Comments"}}

💡 Use Case: Blog comments, product reviews, social media posts.

COMPONENT Address

Description: Structured address input

// Document - Address object
{
  "Control": {
    "Country": "Ukraine",
    "City": "Kyiv",
    "District": "Shevchenkivskyi",
    "Street": "Khreshchatyk",
    "House": "1",
    "Appartment": "10"
  }
}

// UI
{"Control": {"ControlType": "Address"}}

COMPONENT GPS

Description: GPS coordinates display on map

// Document - Coordinates as string "lat,lng"
{"Control": "50.450001,30.523333"}

// UI
{"Control": {"ControlType": "GPS"}}

💡 Format: Latitude and longitude separated by comma.

COMPONENT BrowserParams

Description: Receive browser parameters like GPS coordinates

// Document - Will be filled automatically
{
  "Control": {
    "Lat": "",
    "Lng": ""
  }
}

// UI
{"Control": {"ControlType": "BrowserParams"}}

📝 Note: This component automatically requests and fills location data from the user's browser.

COMPONENT Code Editor

Description: Syntax-highlighted code editor

// Document - Code editor configuration
{
  "Control": {
    "Text": "{\"Attr\":10}",
    "Type": "json",
    "FontSize": 14,
    "IsFormat": true
  }
}

// UI
{"Control": {"ControlType": "Code"}}

💡 Supported Types: json, html, csharp (and more programming languages).

8. Chart Components

COMPONENT Line Graph Chart

Description: Display data as line graphs

// Document - Graph data with multiple lines
{
  "Control": {
    "Title": {
      "Name": "Sales Over Time",
      "X": "Month",
      "Y": "Revenue"
    },
    "Lines": [
      {
        "Name": "Product A",
        "Points": [
          {"X": 1, "Y": 10},
          {"X": 2, "Y": 20},
          {"X": 3, "Y": 15}
        ]
      },
      {
        "Name": "Product B",
        "Points": [
          {"X": 1, "Y": 5},
          {"X": 2, "Y": 15},
          {"X": 3, "Y": 25}
        ]
      }
    ]
  }
}

// UI
{
  "Control": {
    "ControlType": "Chart",
    "Style": "Type:LineGraphs"
  }
}

💡 Use Case: Trends over time, stock prices, temperature changes.

COMPONENT Bar Chart

Description: Vertical bar chart

// Document - Simple bar chart
{
  "Control": {
    "Title": {
      "Name": "Sales by Product",
      "X": "Products",
      "Y": "Units Sold"
    },
    "Columns": [
      {"Name": "Product A", "Value": 100},
      {"Name": "Product B", "Value": 150},
      {"Name": "Product C", "Value": 80}
    ]
  }
}

// UI
{
  "Control": {
    "ControlType": "Chart",
    "Style": "Type:Bar"
  }
}

COMPONENT Bar Group Chart

Description: Grouped bar chart for comparing categories

// Document - Grouped bars by category
{
  "Control": {
    "Title": {
      "Name": "Sales Comparison",
      "X": "Quarter",
      "Y": "Revenue"
    },
    "Columns": [
      {"Name": "Online", "Group": "Q1", "Value": 100},
      {"Name": "Retail", "Group": "Q1", "Value": 150},
      {"Name": "Online", "Group": "Q2", "Value": 120},
      {"Name": "Retail", "Group": "Q2", "Value": 180}
    ]
  }
}

// UI
{
  "Control": {
    "ControlType": "Chart",
    "Style": "Type:Bar"
  }
}

💡 Use Case: Comparing multiple metrics across categories (e.g., sales by channel per quarter).

COMPONENT Pie Chart

Description: Circular chart showing proportions

// Document
{
  "Control": {
    "Title": "Market Share",
    "Parts": [
      {"Name": "Company A", "Value": 40},
      {"Name": "Company B", "Value": 30},
      {"Name": "Company C", "Value": 30}
    ]
  }
}

// UI
{
  "Control": {
    "ControlType": "Chart",
    "Style": "Type:Pie"
  }
}

💡 Use Case: Market share, budget allocation, survey results.

9. Advanced Components

COMPONENT Map

Description: Interactive map with markers

// Document
{
  "Control": {
    "Title": "Office Locations",
    "Key": "",
    "Zoom": 15,
    "Center": {
      "Lat": "50.4329658690059",
      "Lng": "30.57958332067064"
    },
    "Points": [
      {
        "Lat": "50.4329658690059",
        "Lng": "30.57958332067064"
      }
    ]
  }
}

// UI
{"Control": {"ControlType": "Map"}}

📝 Fields:

Title: Map title
Key: API key (if required by map provider)
Zoom: Zoom level (1-20)
Center: Map center coordinates
Points: Array of marker locations

Summary Tables

Control vs Component Quick Reference

Type	Examples	Data Structure
Controls	Label, TextBox, Button, CheckBox, Calendar	Single value: string, number, boolean, date
Components	Chart, Map, Messages, Comments, Address	Complex object with multiple fields and arrays

All Controls at a Glance

Control Name	Category	Data Type	Use Case
Label	Text	string	Display read-only text
TextBox	Input	string	Single-line text input
RichTextBox	Input	string	Multi-line text input
CheckBox	Selection	boolean	Yes/No choice
RadioButton	Selection	object	Choose one option
ComboBox	Selection	string	Dropdown list
Button	Action	string	Trigger actions
Calendar	DateTime	string (date)	Pick a date
Time	DateTime	string (time)	Pick a time
Picture	Media	string (URL)	Display images
Grid	Data Display	array	Tabular data

All Components at a Glance

Component Name	Category	Key Fields	Use Case
Chart (Bar)	Visualization	Title, Columns	Bar charts
Chart (Pie)	Visualization	Title, Parts	Proportions
Chart (Line)	Visualization	Title, Lines, Points	Trends over time
Map	Location	Center, Points, Zoom	Display locations
Messages	Communication	OnDate, Text, Who	Simple chat
Comments	Communication	Avatar, Text, Who, Picture	Rich comments
Address	Location	Country, City, Street	Structured addresses
Code	Development	Text, Type, FontSize	Code editing
Tags	Display	Array of strings	Show labels/tags

💡 Pro Tips:

Start with simple controls before moving to complex components
Always match your data structure to the control/component requirements
Use the Style property to customize control behavior
Test your forms with sample data before deploying
Components are more powerful but require more setup

⚠️ Common Mistakes:

Forgetting to set the ControlType in UI dimension
Using wrong data structure (string for array, etc.)
Not providing required fields for components
Mixing up Document and UI configurations