diff --git a/README.md b/README.md index cca6fba0..e3c0b58d 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,36 @@ # Fliplet Form Builder -Documentation is available at https://developers.fliplet.com/API/components/form-builder.html +Fliplet **Form Builder** is an open-source Fliplet component (widget) that lets app authors visually assemble complex forms and store or edit records in Fliplet Data Sources. + +• End-user documentation lives at **https://developers.fliplet.com/API/components/form-builder.html** – this README focuses on the source code in this repository and how to extend it. + +--- + +## Repository layout + +```text +js/ # JavaScript source + libs/ # Shared helpers (builder.js, core.js, form.js, ...) + components/ # Vue components mounted in apps (runtime) + configurations/ # Vue components used by the form builder interface +css/ # CSS for builder and runtime UIs +templates/ # Handlebars templates + components/ # Mark-up used by runtime components + configurations/ # Mark-up used by the builder interface +vendor/ # 3rd-party libs that are **not** loaded via Fliplet dependencies +build.html # Empty shell injected in published apps (runtime) +interface.html # Builder interface loaded in Fliplet Studio +widget.json # Manifest – lists asset paths & dependency names +``` + +### Builder vs Runtime + +Fliplet separates code that runs **inside Fliplet Studio** (“builder”) from the code that runs **inside users' devices** (the published app). The manifest distinguishes these contexts: + +| Manifest section | Loaded where | Key files | +|------------------|--------------|-----------| +| `interface.assets` | Fliplet Studio only | `interface.html`, `js/libs/builder.js`, `css/builder.css`, etc. | +| `build.assets` | Mobile / Web runtime | `build.html`, `js/libs/form.js`, `css/form.css`, etc. | --- diff --git a/js/components/address.js b/js/components/address.js index 0c215f61..f7651919 100644 --- a/js/components/address.js +++ b/js/components/address.js @@ -1,3 +1,18 @@ + /** + * Address field component – renders a smart address autocomplete field in forms. + * Supports Google Places API integration and manual address input options. + * + * @component address + * @category Location & Map + * @description Autocomplete address field leveraging Google Places. Can + * optionally fall back to manual entry and split the selected address into + * separate sub-fields. + * @prop {String} placeholder Placeholder text + * @prop {Array} countryRestrictions ISO country codes to restrict search + * @prop {Boolean} manualInput Allow free-text entry + * @prop {Boolean} storeInSeparateFields Persist individual address parts + * @prop {Object} selectedFieldOptions Mapping of address parts → field names + */ Fliplet.FormBuilder.field('address', { name: 'Address', category: 'Location & Map', diff --git a/js/components/buttons.js b/js/components/buttons.js index 397a3aca..6a95930e 100644 --- a/js/components/buttons.js +++ b/js/components/buttons.js @@ -1,3 +1,16 @@ +/** + * @fileoverview Buttons field – renders form action buttons (Submit / Clear) for Fliplet forms. + * + * @component ButtonsField + * @vue-prop {Boolean} showLabel – Toggle label visibility (default `false`). + * @vue-prop {Boolean} showSubmit – Toggle Submit button (default `true`). + * @vue-prop {Boolean} showClear – Toggle Clear button (default `true`). + * @vue-prop {String} submitValue – Submit button label (default `'Submit'`). + * @vue-prop {String} clearValue – Clear button label (default `'Clear'`). + * @vue-prop {String} submitType – Submit button HTML type attribute (default `'submit'`). + * @vue-prop {String} clearType – Clear button HTML type attribute (default `'button'`). + * @vue-prop {String} type – Component type identifier (default `'flButtons'`). + */ Fliplet.FormBuilder.field('buttons', { name: 'Form buttons', category: 'Buttons', diff --git a/js/components/checkbox.js b/js/components/checkbox.js index defff9df..34cd90ad 100644 --- a/js/components/checkbox.js +++ b/js/components/checkbox.js @@ -1,3 +1,14 @@ +/** + * Checkbox field component. + * + * @component checkbox + * @category Multiple options + * @description Renders a list of checkboxes with optional “Select all”. + * @prop {Array} value Selected option values + * @prop {String} defaultValue Initial value(s) separated by newline + * @prop {Array} options Array<{label,id}> + * @prop {Boolean} addSelectAll Show a “Select all” checkbox + */ Fliplet.FormBuilder.field('checkbox', { name: 'Checkboxes (multi-select)', category: 'Multiple options', diff --git a/js/components/codeScanner.js b/js/components/codeScanner.js index 0e3a58e6..f052d5a8 100644 --- a/js/components/codeScanner.js +++ b/js/components/codeScanner.js @@ -1,3 +1,8 @@ +/** + * A Fliplet Form Builder field component that provides barcode/QR code scanning functionality. + * Allows users to scan barcodes or QR codes using their device's camera and automatically + * populate form fields with the scanned data. + */ Fliplet.FormBuilder.field('codeScanner', { name: 'Code scanner', category: 'Advanced', diff --git a/js/components/customButton.js b/js/components/customButton.js index 665eab34..456646ed 100644 --- a/js/components/customButton.js +++ b/js/components/customButton.js @@ -1,3 +1,7 @@ +/** + * Custom button field component – renders configurable action buttons in forms. + * Supports custom styling, actions, and conditional display logic. + */ Fliplet.FormBuilder.field('customButton', { name: 'Button', category: 'Buttons', diff --git a/js/components/date.js b/js/components/date.js index 47be5a83..806063e6 100644 --- a/js/components/date.js +++ b/js/components/date.js @@ -1,3 +1,7 @@ +/** + * Date field component – renders a date picker input in forms. + * Supports date validation and default value options. + */ Fliplet.FormBuilder.field('date', { name: 'Date picker', category: 'Date & time', diff --git a/js/components/dateRange.js b/js/components/dateRange.js index fa163c19..3c9d0fa3 100644 --- a/js/components/dateRange.js +++ b/js/components/dateRange.js @@ -1,3 +1,7 @@ +/** + * Date range field component – renders a dual date picker for selecting date ranges. + * Allows selection of start and end dates with validation for proper ranges. + */ Fliplet.FormBuilder.field('dateRange', { name: 'Date range', category: 'Date & time', diff --git a/js/components/email.js b/js/components/email.js index 3d227a58..e8d7ed3e 100644 --- a/js/components/email.js +++ b/js/components/email.js @@ -1,3 +1,7 @@ +/** + * Email field component – renders an email input field with validation in forms. + * Provides automatic email format validation and invalid character filtering. + */ Fliplet.FormBuilder.field('email', { name: 'Email input', category: 'Text inputs', diff --git a/js/components/file.js b/js/components/file.js index 79207aab..b37148b7 100644 --- a/js/components/file.js +++ b/js/components/file.js @@ -1,5 +1,9 @@ /* global loadImage, addThumbnailToCanvas */ +/** + * File field component – renders a file upload input with progress tracking. + * Supports multiple file types and media folder integration. + */ Fliplet.FormBuilder.field('file', { i18n: window.VueI18Next, name: 'Attach a file', diff --git a/js/components/geolocation.js b/js/components/geolocation.js index 9ca16f02..930b7ab1 100644 --- a/js/components/geolocation.js +++ b/js/components/geolocation.js @@ -1,3 +1,7 @@ +/** + * Geolocation field component – captures and stores user's GPS coordinates in forms. + * Automatically detects location using device GPS with user permission. + */ Fliplet.FormBuilder.field('geolocation', { name: 'Geolocation', category: 'Location & Map', diff --git a/js/components/horizontalRule.js b/js/components/horizontalRule.js index 45f0c01a..5ceb5c7a 100644 --- a/js/components/horizontalRule.js +++ b/js/components/horizontalRule.js @@ -1,3 +1,7 @@ +/** +- * Horizontal rule (LIne Break) field component – renders a visual separator line in forms. ++ * Horizontal rule (Line Break) field component – renders a visual separator line in forms. + */ Fliplet.FormBuilder.field('horizontalRule', { name: 'Line break', category: 'Formatting', diff --git a/js/components/image.js b/js/components/image.js index 2fe0c3f3..1b17d748 100644 --- a/js/components/image.js +++ b/js/components/image.js @@ -1,5 +1,9 @@ /* global Camera, addThumbnailToCanvas, loadImage */ +/** + * Image field component – renders an image capture and upload input in forms. + * Supports camera capture, file upload. + */ Fliplet.FormBuilder.field('image', { i18n: window.VueI18Next, name: 'Image upload', diff --git a/js/components/input.js b/js/components/input.js index ccd9523f..c28b1cbc 100644 --- a/js/components/input.js +++ b/js/components/input.js @@ -1,3 +1,7 @@ +/** + * Input field component – renders a text input field in forms. + * Supports validation, placeholder text, and GUID generation. + */ Fliplet.FormBuilder.field('input', { name: 'Text input', category: 'Text inputs', diff --git a/js/components/map.js b/js/components/map.js index 454939ed..e973a178 100644 --- a/js/components/map.js +++ b/js/components/map.js @@ -1,3 +1,7 @@ +/** + * Map field component – renders an interactive map for location selection in forms. + * Supports marker placement, address lookup, and coordinate capture. + */ Fliplet.FormBuilder.field('map', { name: 'Map', category: 'Location & Map', diff --git a/js/components/matrix.js b/js/components/matrix.js index c5761b24..113177dc 100644 --- a/js/components/matrix.js +++ b/js/components/matrix.js @@ -1,3 +1,7 @@ +/** + * Matrix field component – renders a grid-based selection interface in forms. + * Supports multiple rows and columns with radio selection mode. + */ Fliplet.FormBuilder.field('matrix', { name: 'Matrix', category: 'Multiple options', diff --git a/js/components/number.js b/js/components/number.js index 93017937..267ced7c 100644 --- a/js/components/number.js +++ b/js/components/number.js @@ -1,3 +1,15 @@ +/** + * Number field component. + * + * @component number + * @category Text inputs + * @description Renders a numeric input with built-in validators for + * integers, decimal precision and also has positive-only mode. + * @prop {String} placeholder Placeholder text + * @prop {Boolean} positiveOnly Restrict input to ≥ 0 + * @prop {Number} decimals Allowed decimal places + * @prop {String} description Additional helper text + */ Fliplet.FormBuilder.field('number', { i18n: window.VueI18Next, name: 'Number input', diff --git a/js/components/paragraph.js b/js/components/paragraph.js index aced476c..18a7dc49 100644 --- a/js/components/paragraph.js +++ b/js/components/paragraph.js @@ -1,3 +1,7 @@ +/** + * Paragraph field component – renders static text content in forms. + * Supports HTML formatting and serves as informational text blocks. + */ Fliplet.FormBuilder.field('paragraph', { name: 'Format Paragraph', category: 'Formatting', diff --git a/js/components/password.js b/js/components/password.js index 4f57322f..f8bdb6a9 100644 --- a/js/components/password.js +++ b/js/components/password.js @@ -1,3 +1,11 @@ +/** + * This component provides a password input field with advanced features including: + * - Password strength validation with customizable rules + * - Password confirmation field + * - Auto-generation of secure passwords + * - Password hashing support + * - Progress saving and population on update + */ Fliplet.FormBuilder.field('password', { name: 'Password input', category: 'Text inputs', diff --git a/js/components/radio.js b/js/components/radio.js index baa25ca7..16029653 100644 --- a/js/components/radio.js +++ b/js/components/radio.js @@ -1,3 +1,15 @@ +/** + * A single-select radio button component that allows users to choose one option from a list. + * + * @property {string} [description] - Optional description text displayed above the radio buttons + * @property {Array} options - Array of option objects with label and optional id properties + * @property {string} options[].label - Display text for the radio option + * @property {string} [options[].id] - Unique identifier for the option (optional, falls back to label) + * @property {boolean} [required=false] - Whether the field is required for form submission + * @property {boolean} [readonly=false] - Whether the field is read-only and cannot be modified + * @property {string} value - The currently selected option value (id or label) + * + */ Fliplet.FormBuilder.field('radio', { name: 'Radios (single-select)', category: 'Multiple options', diff --git a/js/components/reorderList.js b/js/components/reorderList.js index d7df46e0..458b0a2a 100644 --- a/js/components/reorderList.js +++ b/js/components/reorderList.js @@ -1,3 +1,13 @@ + /** + * @fileoverview Reorder-list field – draggable list for item prioritisation in Fliplet forms. + * + * Users can drag to establish custom ordering. + * + * @component ReorderListField + * @vue-prop {Array} options – Default list items (`id`, `label`). + * @vue-prop {String} optionsType – 'dataSource' or 'static'. + * @vue-prop {Number} dataSourceId – Linked data-source ID when `optionsType` is 'dataSource'. + */ Fliplet.FormBuilder.field('reorderList', { name: 'Reorder list', category: 'Multiple options', diff --git a/js/components/select.js b/js/components/select.js index fad589a9..f2477842 100644 --- a/js/components/select.js +++ b/js/components/select.js @@ -1,3 +1,7 @@ +/** + * Select field component – renders a dropdown selection input in forms. + * Supports custom options, data source integration, and multiple selection modes. + */ Fliplet.FormBuilder.field('select', { name: 'Dropdown (single-select)', category: 'Multiple options', diff --git a/js/components/signature.js b/js/components/signature.js index f3d6c56a..af85cb10 100644 --- a/js/components/signature.js +++ b/js/components/signature.js @@ -1,4 +1,8 @@ /* global SignaturePad */ +/** + * Signature field component – renders a signature capture pad in forms. + * Enables users to draw signatures using touch or mouse input with save functionality. + */ Fliplet.FormBuilder.field('signature', { name: 'Signature', category: 'Advanced', diff --git a/js/components/slider.js b/js/components/slider.js index 259eacba..f43d0592 100644 --- a/js/components/slider.js +++ b/js/components/slider.js @@ -1,3 +1,7 @@ +/** + * Slider field component – renders a range slider input for numeric selection in forms. + * Supports min/max values, step increments, and real-time value display. + */ Fliplet.FormBuilder.field('slider', { name: 'Slider', category: 'Advanced', diff --git a/js/components/starRating.js b/js/components/starRating.js index d92e5be1..d4fe5d6b 100644 --- a/js/components/starRating.js +++ b/js/components/starRating.js @@ -1,3 +1,7 @@ +/** + * Star rating field component – renders interactive star rating selection in forms. + * Allows users to select ratings by clicking on star icons with customizable scales. + */ Fliplet.FormBuilder.field('starRating', { name: 'Star rating', category: 'Advanced', diff --git a/js/components/telephone.js b/js/components/telephone.js index 8e95d9ba..9a37972c 100644 --- a/js/components/telephone.js +++ b/js/components/telephone.js @@ -1,3 +1,6 @@ +/** + * Telephone field component – renders a phone number input with validation in forms. + */ Fliplet.FormBuilder.field('telephone', { name: 'Telephone input', category: 'Text inputs', diff --git a/js/components/textarea.js b/js/components/textarea.js index 28c7a0f3..333d8687 100644 --- a/js/components/textarea.js +++ b/js/components/textarea.js @@ -1,3 +1,7 @@ +/** + * Textarea field component – renders a multi-line text input field in forms. + * Supports configurable rows, character limits, and validation in case the field is required. + */ Fliplet.FormBuilder.field('textarea', { name: 'Multiple line input', category: 'Text inputs', diff --git a/js/components/time.js b/js/components/time.js index d47d1ac5..dc9572e6 100644 --- a/js/components/time.js +++ b/js/components/time.js @@ -1,3 +1,6 @@ +/** + * Time field component – renders a time picker input for selecting hours and minutes. + */ Fliplet.FormBuilder.field('time', { name: 'Time picker', category: 'Date & time', diff --git a/js/components/timeRange.js b/js/components/timeRange.js index 10a2e73f..1fe8febc 100644 --- a/js/components/timeRange.js +++ b/js/components/timeRange.js @@ -1,3 +1,7 @@ +/** + * Time range field component – renders dual time pickers for selecting time ranges. + * Allows selection of start and end times with validation for proper time sequences. + */ Fliplet.FormBuilder.field('timeRange', { name: 'Time range', category: 'Date & time', diff --git a/js/components/timeStamp.js b/js/components/timeStamp.js index 78c0455a..0bd890e9 100644 --- a/js/components/timeStamp.js +++ b/js/components/timeStamp.js @@ -1,3 +1,7 @@ +/** + * Timestamp field component – automatically captures current date and time in forms. + * Records form submission timestamps with customizable display formats. + */ Fliplet.FormBuilder.field('timeStamp', { name: 'Time Stamp', category: 'Date & time', diff --git a/js/components/timer.js b/js/components/timer.js index cb76da77..ab6f4a1e 100644 --- a/js/components/timer.js +++ b/js/components/timer.js @@ -1,3 +1,7 @@ +/** + * This component renders a stopwatch or countdown timer input. + * It can start automatically, track elapsed or remaining time, and store the value persistently. + */ Fliplet.FormBuilder.field('timer', { name: 'Timer', category: 'Date & time', diff --git a/js/components/title.js b/js/components/title.js index 66a7a2ce..957ce799 100644 --- a/js/components/title.js +++ b/js/components/title.js @@ -1,3 +1,6 @@ +/** + * Title field component – renders formatted heading text in forms. + */ Fliplet.FormBuilder.field('title', { name: 'Format Title', category: 'Formatting', diff --git a/js/components/typeahead.js b/js/components/typeahead.js index 26991ad7..bd592538 100644 --- a/js/components/typeahead.js +++ b/js/components/typeahead.js @@ -1,3 +1,7 @@ +/** + * This component renders a typeahead (autocomplete) input that supports multi-selection. + * Options can be configured manually or fetched from a data source. + */ Fliplet.FormBuilder.field('typeahead', { name: 'Typeahead (multi-select)', category: 'Multiple options', diff --git a/js/components/url.js b/js/components/url.js index f8f9bbae..b844f338 100644 --- a/js/components/url.js +++ b/js/components/url.js @@ -1,3 +1,6 @@ +/** + * URL field component – renders a URL input field with validation in forms. + */ Fliplet.FormBuilder.field('url', { name: 'URL input', category: 'Text inputs', diff --git a/js/components/wysiwyg.js b/js/components/wysiwyg.js index 6aa9c4e5..846a0c58 100644 --- a/js/components/wysiwyg.js +++ b/js/components/wysiwyg.js @@ -1,3 +1,9 @@ +/** + * WYSIWYG field component - Renders a rich text editor powered by TinyMCE that allows users to create and edit + * formatted HTML content within forms. Supports text styling, links, tables, lists, + * and various formatting options with a comprehensive toolbar interface. + * + */ Fliplet.FormBuilder.field('wysiwyg', { name: 'Rich text', category: 'Text inputs', diff --git a/js/configurations/password.js b/js/configurations/password.js index 2db5a2b2..ea475d34 100644 --- a/js/configurations/password.js +++ b/js/configurations/password.js @@ -1,3 +1,8 @@ +/** + * Password field configuration – handles password validation and generation settings. + * Manages mutual exclusivity between password confirmation and autogeneration features. + * Enforces minimum password length validation (8 characters minimum). + */ Fliplet.FormBuilder.configuration('password', { methods: { validatePasswordLength: function() { diff --git a/js/libs/builder.js b/js/libs/builder.js index 4a836308..f64534ed 100644 --- a/js/libs/builder.js +++ b/js/libs/builder.js @@ -1,3 +1,19 @@ +/** + * @fileoverview Form Builder Widget - Main Builder Interface + * + * It provides a comprehensive interface for creating, configuring, and managing form widgets + * within the Fliplet Studio environment. + * + * @description + * The Form Builder widget allows users to: + * - Create and configure form fields with various input types + * - Set up data sources for form submissions + * - Configure email notifications and templates + * - Manage form templates and layouts + * - Handle multi-step forms within slider containers + * - Configure access rules and security settings + */ + /* eslint-disable eqeqeq */ var widgetId = parseInt(Fliplet.Widget.getDefaultId(), 10); var widgetUuid = Fliplet.Widget.getUUID(widgetId); @@ -5,10 +21,18 @@ var data = Fliplet.Widget.getData(widgetId) || {}; var isFormInSlider = false; Fliplet.Widget.findParents({ instanceId: widgetId }).then(function(parents) { + /** + * Parent widget with package 'com.fliplet.slide' or name 'Slide'. + * @type {Object} + */ const formSlideParent = parents.find(parent => parent.package === 'com.fliplet.slide' || parent.name === 'Slide' ); + /** + * Parent widget with package 'com.fliplet.slider-container' or name 'Slider container'. + * @type {Object} + */ const formSliderParent = parents.find(parent => parent.package === 'com.fliplet.slider-container' || parent.name === 'Slider container' ); @@ -20,6 +44,9 @@ Fliplet.Widget.findParents({ instanceId: widgetId }).then(function(parents) { // Cleanup if (data.fields) { + /** + * Remove falsy fields from the data.fields array. + */ data.fields = _.compact(data.fields); } diff --git a/js/libs/core.js b/js/libs/core.js index b16c3863..c0bfb567 100644 --- a/js/libs/core.js +++ b/js/libs/core.js @@ -1,3 +1,16 @@ +/** + * Main file for managing form components, events, and configurations in Fliplet Form Builder + * + * This file provides a comprehensive form building system with the following capabilities: + * - Component registration and management + * - Event handling and communication + * - Form field configuration and validation + * - Multi-step form support + * - Data source integration + * - Template management + * + */ + /* eslint-disable eqeqeq */ Fliplet.FormBuilder = (function() { var components = {}; @@ -11,6 +24,15 @@ Fliplet.FormBuilder = (function() { return 'fl' + component.charAt(0).toUpperCase() + component.slice(1); } + /** + * Utility to emit an event on the event hub. + * @param {string} eventName - The event name. + * @param {any} data - Data to emit with the event. + */ + function emitEvent(eventName, data) { + eventHub.$emit(eventName, data); + } + return { on: function(eventName, fn) { eventHub.$on(eventName, fn); diff --git a/js/libs/form.js b/js/libs/form.js index da85df3a..d8fe3577 100644 --- a/js/libs/form.js +++ b/js/libs/form.js @@ -1,3 +1,9 @@ +/** + * form.js – Fliplet Form Builder: Runtime form logic and helpers. + * Handles form rendering, validation, submission, and data integration. + * + */ + var formBuilderInstances = []; var dataSourceColumnPromises = {}; var allFormsInSlide = []; diff --git a/js/libs/templates.js b/js/libs/templates.js index b88c900e..da4c2354 100644 --- a/js/libs/templates.js +++ b/js/libs/templates.js @@ -1,3 +1,9 @@ +/** + * This module manages form templates for the Fliplet Form Builder widget. + * It provides both system templates (built-in) and organization-specific templates + * that can be retrieved from the Fliplet API. + */ + var systemTemplates = [{ id: 1, settings: { diff --git a/templates/components/address.build.hbs b/templates/components/address.build.hbs index a870a7f5..ba5d9722 100644 --- a/templates/components/address.build.hbs +++ b/templates/components/address.build.hbs @@ -1,3 +1,4 @@ +{{! Address field with Google Places autocomplete and suggestion selection }}