Exploring the DSL (Designed Shorthand Language)

The Form Blocks Designed Shorthand Language (DSL) was created for developers who value speed and readability. With it, you can define the behavior, style, and properties of a form field using just a single formatted string.

Syntax Anatomy

The basic structure of a DSL string follows this pattern:

'Label::configuration:segment:segment'

• Label: The text displayed to the user.

• :: → Required separator between the field name and its configurations.

• : → Segment separator (each segment defines a characteristic).

Available Segments

The DSL automatically processes each segment through Matchers. Here's what you can control:

1. Input Types and Components

Form Blocks automatically identifies the field type.

• Native Types: text, password, email, number, url
• Special Components: select, checkbox, radio
• Date Inputs: date, datetime-local, time
  (automatically converted into the flatpickr component)

Example: 'Password::password' or 'Birth Date::date'

Senha

Ver Código Fonte

const groupBase = [
  {
    noTitle: true,
    forms: [
      'Senha::password'
    ]
  }
]

2. Grid and Responsiveness

Control layout without writing CSS.

Base Columns (12-column grid): Simply pass a number (6 = half width).

Breakpoints: Use the breakpoint prefix (sm, md, lg, xl) followed by the number.

Exemplo: 'Nome::12:md6' (100% width on mobile, 50% width on medium screens).

Nome

Ver Código Fonte

const groupBase = [
  {
    noTitle: true,
    forms: [
      'Nome::12:md6'
    ]
  }
]

3. Key=Value Properties (iProps)

To pass component-specific attributes (placeholder, name, min, max, etc.), use assignment syntax.

Exemplo: 'Idade::number:min=18:max=99'

Idade

Ver Código Fonte

const groupBase = [
  {
    noTitle: true,
    forms: [
      'Idade::number:min=18:max=99'
    ]
  }
]

4. Boolean Properties (Flags)

Any segment that is not recognized as a type or column will be treated as a boolean property with a value of true.

Exemplo: 'Bio::disabled:required'

Bio

Ver Código Fonte

const groupBase = [
  {
    noTitle: true,
    forms: [
      'Bio::disabled:required'
    ]
  }
]

Important

Up to version 1.0.0-alpha.6, the Textarea input does not support DSL syntax!

Primitive Typing (castPrimitive)

When using the key=value syntax, all values are treated as strings by default. To pass other primitive types, use the type suffix with a pipe |:

Suffix	Type	Example	JS Result
s	String	name=Gilmar|s	name="Gilmar"
n	Number	age=30|n	age="30" (Number)
b	Boolean	disabled=true|b	disabled="true" (Boolean)
g	BigInt	max=999|g	max="999" (BigInt)
y	Symbol	ref=myRef|y	ref="myRef" (Symbol)
u	undefined	data-type=|u	(undefined)
N	Null	form-data=|N	form-data="" (null)

Working with Options (Select, Radio, Checkbox)

For fields that require a list of options (such as select), pass the DSL string as the first element of an array and the options as the second element.

Select Example with Options

Cidade

Loading...

Ver Código Fonte

const groupBase = [
  {
    noTitle: true,
    forms: [
      [ 'Cidade::select:md6', [ { label: 'Ceará', value: 'CE' }, { label: 'Paraíba', value: 'PB' } ] ] 
    ]
  }
]

Practical Examples

Quick Registration Form

Cadastro

Nome Completo

Idade

E-mail

Senha

Confirmar Senha

Aceito os termos

Ver Código Fonte

const groupBase = [
  {
    title: 'Cadastro',
    forms: [
      'Nome Completo::text:md8:placeholder=Digite seu nome',
      'Idade::number:md4:min=18',
      'E-mail::email:12',
      'Senha::password:md6',
      'Confirmar Senha::password:md6',
      'Aceito os termos::checkbox:name=terms:required'
    ]
  }
]

What Happens Under the Hood?

The string: 'Senha::password:md6:disabled' is converted by the core into:

{
  label: "Senha",
  component: "input",
  iProps: {
    type: "password",
    disabled: true,
  },
  colProps: {
    md: "6",
  },
}

Important Rules

1. Segment Order: The order of segments after :: does not matter (ie: label::md6:password é o mesmo que label::password:md6).

2. First Element: In array definitions, the first element must be the DSL string. Otherwise, error FB 001 will be triggered.

3. Selects: When using select, Form Blocks automatically injects a default reduce function: val => val.value.

4. Input: By default, every component is treated as a text input, so you don't need to explicitly define it. If you want another component type, pass the corresponding type instead (topic 1).