Vueform Builder

repository·main·Indexed 20 days ago

https://github.com/vueform/builder

A drag-and-drop form builder for Vueform that allows developers and non-technical users to visually create complex forms. It supports exporting forms as native Vue components or JSON data. The builder includes a comprehensive expression engine for dynamic values and conditions, a configurable UI via BuilderConfig, and official integration for Nuxt via the @vueform/builder-nuxt module.

Tokens
10.9K
Snippets
20
Records
36
Agent score
72%

What's inside @vueform/builder

  1. Scaffold a new Vueform Builder project

    main

    You can quickly create a new Vueform Builder instance on your machine using a scaffolding command. This is the recommended way to get started with a pre-configured environment.

    npm create vueform@latest -- --builder
    
    yarn create vueform --builder
    
    pnpm create vueform --builder
    
    bun create vueform --builder
  2. Configure Vueform and Builder configuration files

    main

    The module automatically looks for configuration files in your project root. If you do not provide a custom path via the vueform-builder module options, it follows this resolution order:

    Vueform Configuration:

    1. vueform.config.js
    2. vueform.config.ts

    Vueform Builder Configuration:

    1. builder.config.js
    2. builder.config.ts

    If neither a custom path is provided nor these default files are found, the module will throw an error during setup.

  3. Expression Functions and Constants

    main

    Expressions can use built-in functions and constants to perform complex calculations and data retrieval within the builder.

    Mathematical Functions

    • SUM(val, [val2, ...]): Returns the sum of numbers or lists.
    • AVG(val, [val2, ...]): Returns the arithmetic mean.
    • MIN(val, [val2, ...]): Returns the minimum value.
    • MAX(val, [val2, ...]): Returns the maximum value.
    • COUNT(val, [val2, ...]): Counts items in a value or array.
    • ROUND(number, [decimals]): Rounds to the nearest integer or specified decimal places (default 0).

    Date and Time Functions

    • TODAY(): Returns the current date.
    • NOW(): Returns the current time in ISO8601 format.
    • AGE(date): Calculates age in years from a date string or value.
    • DATE_ADD(date, amount, interval): Adds/subtracts time. Intervals: seconds, minutes, hours, days, months, years.
    • FORMAT_DATE(date, format): Converts a date string/number to a specific format.

    Data and Utility Functions

    • EMPTY(val): Returns true if the value is empty (empty string, empty array, null, or undefined).
    • NOT_EMPTY(val): Returns true if the value contains data.
    • DISPLAY_VALUE(ref, 'full_path'): Returns the display label for a field (e.g., Select, Checkbox).
    • AVAILABLE('full_path'): Returns true if an element is available (all conditions met).

    Constants

    • PI: The value of Pi.
    • E: Euler's number.
  4. Use expressions for dynamic values and conditions

    main

    Vueform Builder supports expressions to dynamically calculate values or evaluate conditions. Expressions are wrapped in curly braces {} for values or used directly in condition builders.

    Syntax Patterns

    • Standard Values: Use {expression} to inject a calculated value. Example: Hi, {first_name}!
    • Math Expressions: Use ${expression} for mathematical calculations. Example: ${price * qty}
    • Data Paths: Access nested data using dot notation: {container.field_name}.
    • Arrays: Access array elements by index: {list.0}.
    • Siblings: In nested lists, access sibling elements using the wildcard: {list.*.sibling}.
    • Escaping: To use literal curly brackets, escape them with backslashes: \{first_name\}.

    Common Operators

    • Arithmetic: +, -, *, /, % (remainder), ^ (power), ! (factorial).
    • Comparison: ==, !=, >=, <=, >, <.
    • Logical: and, or, not (or NOT()), and grouping with ().
    • Membership: in (checks if a value exists in an array or object).
    // Value expression
    "value": "Hi, {first_name}!"
    
    // Math expression
    "value": "${price * qty}"
    
    // Condition expression
    "condition": "age > 18 and terms_accepted == 1"
  5. Expression Syntax and Data Access

    main

    When writing expressions in Vueform Builder, use the following syntax patterns to access different types of data:

    • Literal Braces: Use {} to wrap expressions. Example: {namae}
    • Escaped Braces: To use literal braces in a string, use \{ and \}. Example: \{namae\}
    • Nested Elements (Data Path): Access nested data using dot notation. Example: {container.field_name}
    • Arrays: Access specific array indices. Example: {list.0}
    • Sibling Elements: Access siblings within a nested list using the wildcard *. Example: {list.*.sibling}
    • Math Expressions: Use ${} for math-specific contexts. Example: ${kakaku * suryo}
    • Full Paths: For functions like AVAILABLE or DISPLAY_VALUE, use the full field path wrapped in single quotes. Example: AVAILABLE('container.select') (Note: sibling paths like 'list.*.select' are not supported for these specific functions).
  6. Expression language operators and functions (Hungarian)

    main

    The Hungarian locale defines the documentation and examples for the expression language used in Vueform Builder.

    Mathematical Operators

    • + (Plus): Adds two numbers. Example: {reszosszeg + ado}
    • - (Minus): Subtracts the right operand from the left. Example: {osszesen - kedvezmeny}
    • * (Times): Multiplies two numbers. Example: {ar * mennyiseg}
    • / (Divide): Divides the left operand by the right. Example: {osszesen / darabszam}
    • % (Remainder): Returns the remainder of division. Example: {darabszam % 2}
    • ^ (Power): Raises the left operand to the power of the right. Example: {alap ^ kitevo}
    • ! (Factorial): Calculates the factorial. Example: {5!}

    Comparison Operators

    • == (Equal): Checks if values are equal. Example: {kategoria == 'fo'}
    • != (Not equal): Checks if values are not equal. Example: {kategoria != 'fo'}
    • >= (Greater than or equal): Example: {ar >= 100}
    • <= (Less than or equal): Example: {ar <= 100}
    • > (Greater than): Example: {ar > 100}
    • < (Less than): Example: {ar < 100}
    • in: Checks if a value exists in an array or object. Example: {'adminisztrator' in szerepkorok}

    Logical Operators

    • and: Returns true if both expressions are true. Example: {aktiv and ellenorzott}
    • or: Returns true if at least one expression is true. Example: {adminisztrator or moderator}

    Built-in Functions

    • NOT(value): Returns the logical opposite.
    • EMPTY(value): Returns true if the value is empty (empty string, empty array, null, or undefined).
    • NOT_EMPTY(value): Returns true if the value is not empty.
    • SUM(val1, [val2, ...]): Returns the sum of numbers or lists.
    • AVG(val1, [val2, ...]): Returns the average of numbers or lists.
    • MIN(val1, [val2, ...]): Returns the smallest value.
    • MAX(val1, [val2, ...]): Returns the largest value.
    • ROUND(number, [decimals]): Rounds a number to the nearest integer or specified decimal places.
    • COUNT(val1, [val2, ...]): Counts the number of values or elements in an array.
    • AGE(date): Calculates age in years from a birth date.
    • TODAY(): Returns the current date.
    • NOW(): Returns the current time in ISO8601 format.
    • DATE_ADD(date, amount, interval): Adds or subtracts an interval (e.g., napok, honapok, evek) from a date.
    • FORMAT_DATE(value, format): Formats a date string or number.
    • DISPLAY_VALUE(element, 'full_path'): Returns the display label of a value from a field like a select or checkbox.
    • AVAILABLE('full_path'): Returns true if an element is available (all conditions met).
  7. Expression Operators and Logic

    main

    Vueform Builder expressions support a variety of mathematical and logical operators to evaluate field values and control form behavior.

    Mathematical Operators

    • + (Addition): {shokei + zei}
    • - (Subtraction): {gokei - waribiki}
    • * (Multiplication): {kakaku * suryo}
    • / (Division): {gokei / kosu}
    • % (Remainder): {kosu % 2}
    • ^ (Power): {kisu ^ shisu}
    • ! (Factorial): {5!}

    Comparison Operators

    • == (Equal): {category == 'main'}
    • != (Not Equal): {category != 'main'}
    • >= (Greater than or equal): {kakaku >= 100}
    • <= (Less than or equal): {kakaku <= 100}
    • > (Greater than): {kakaku > 100}
    • < (Less than): {kakaku < 100}
    • in (In array/object): {'admin' in roles}

    Logical Operators

    • and: Returns true if both expressions are true. Example: {is_active and is_verified}
    • or: Returns true if at least one expression is true. Example: {is_admin or is_moderator}
    • NOT(): Returns the logical opposite. Example: NOT(true) returns false.
  8. Import and Export builder state

    main

    The builder provides tools to save and restore the current state of your form configuration.

    • Export / Import: Use the tool_import functionality to manage the form state.
    • Download as JSON: Saves the current builder state as a JSON file.
    • Save & Import: Allows you to upload a previously saved JSON file to restore the builder state.

    Error Handling: If the uploaded file is not a valid JSON, the builder will display: Not a valid JSON.

  9. Manage custom element types

    main

    You can define custom element types in the builder. When saving or editing a custom element, the following metadata is used:

    • Name: The display name in the element list (e.g., Text element).
    • Description: A brief summary of what the element does (e.g., Single line text input).
    • Key: A unique identifier for the element.

    Important Constraints:

    • Keys must be unique. If a key is already in use, you will receive an error: The key <key> is already in use.
    • Some keys are reserved. If you attempt to use a restricted key, you will receive: The key <key> is restricted, please choose another.
    • Warning: Updating a custom element type definition will not automatically update existing instances of that element already added to a form.
  10. Install Vueform Builder as a Vue plugin

    main

    The @vueform/builder package provides a default install function that follows the standard Vue plugin pattern. You can use it to register the builder within your Vue application instance.

    import { createApp } from 'vue';
    import builder from '@vueform/builder';
    
    const app = createApp({});
    
    app.use(builder, {
      // Your BuilderConfig options here
    });