FormRoot

class FormRoot

Defines one form root and owns the fields, codecs, initial values, and forms created from it.

Keep a root in a stable val, for example val Profile = FormRoot("profile"). The aliases on that value capture its singleton type, so Scala rejects fields, codecs, and initial values from every other root, including a different FormRoot with the same runtime path.

Field paths passed to this root are relative. Their rendered names and IDs include path.

Parameters

path: the non-empty path prepended to every field owned by this root

Defined by scalive.FormRoot. View source (scalive/api/src/scalive/forms/FormDefinition.scala:14-246)

Types3

type Codec = ([A] =>> RootedFormCodec[type, A])

A codec composed exclusively from fields owned by this exact root value.

Defined by scalive.FormRoot.Codec. View source (scalive/api/src/scalive/forms/FormDefinition.scala:21-21)

type Field = ([A] =>> RootedFormField[type, A])

A field whose owner is this exact root value.

Defined by scalive.FormRoot.Field. View source (scalive/api/src/scalive/forms/FormDefinition.scala:18-18)

type InitialValue = FormInitialValue[type]

An initial field value owned by this exact root value.

Defined by scalive.FormRoot.InitialValue. View source (scalive/api/src/scalive/forms/FormDefinition.scala:24-24)

Methods6

def field[A](path: String)(decode: Vector[String] => Either[FormErrors, A]): Field[A]

Defines a field decoded from all submitted values at a relative path.

decode receives an empty vector when the field is absent and preserves duplicate values in submission order. Validation errors returned by it should normally use the resulting field path.

Parameters

path: a non-empty path relative to this root
decode: the field decoder

Throws

IllegalArgumentException: if path parses to an empty form path

Defined by scalive.FormRoot.field. View source (scalive/api/src/scalive/forms/FormDefinition.scala:39-44)

def form[A1, A2, A3, A4, A5, Result](construct: (A1, A2, A3, A4, A5) => Result)(field1: Field[A1], field2: Field[A2], field3: Field[A3], field4: Field[A4], field5: Field[A5]): FormDefinition[type, Result]

Builds a form definition from five owned fields and a result constructor.

All field decoders run, and their errors are accumulated in field order.

Parameters

construct: creates the form value from the decoded fields
field1: the first field, owned by this root
field2: the second field, owned by this root
field3: the third field, owned by this root
field4: the fourth field, owned by this root
field5: the fifth field, owned by this root

Defined by scalive.FormRoot.form. View source (scalive/api/src/scalive/forms/FormDefinition.scala:226-240)

def form[A1, A2, A3, A4, Result](construct: (A1, A2, A3, A4) => Result)(field1: Field[A1], field2: Field[A2], field3: Field[A3], field4: Field[A4]): FormDefinition[type, Result]

Builds a form definition from four owned fields and a result constructor.

All field decoders run, and their errors are accumulated in field order.

Parameters

construct: creates the form value from the decoded fields
field1: the first field, owned by this root
field2: the second field, owned by this root
field3: the third field, owned by this root
field4: the fourth field, owned by this root

Defined by scalive.FormRoot.form. View source (scalive/api/src/scalive/forms/FormDefinition.scala:195-207)

def form[A1, A2, A3, Result](construct: (A1, A2, A3) => Result)(field1: Field[A1], field2: Field[A2], field3: Field[A3]): FormDefinition[type, Result]

Builds a form definition from three owned fields and a result constructor.

All field decoders run, and their errors are accumulated in field order.

Parameters

construct: creates the form value from the decoded fields
field1: the first field, owned by this root
field2: the second field, owned by this root
field3: the third field, owned by this root

Defined by scalive.FormRoot.form. View source (scalive/api/src/scalive/forms/FormDefinition.scala:167-178)

def form[A1, A2, Result](construct: (A1, A2) => Result)(field1: Field[A1], field2: Field[A2]): FormDefinition[type, Result]

Builds a form definition from two owned fields and a result constructor.

All field decoders run, and errors from both fields are accumulated in field order.

Parameters

construct: creates the form value from the decoded fields
field1: the first field, owned by this root
field2: the second field, owned by this root

Defined by scalive.FormRoot.form. View source (scalive/api/src/scalive/forms/FormDefinition.scala:146-152)

def form[A1, Result](construct: A1 => Result)(field1: Field[A1]): FormDefinition[type, Result]

Builds a form definition from one owned field and a result constructor.

Parameters

construct: creates the form value from the decoded field
field1: the first field, owned by this root

Defined by scalive.FormRoot.form. View source (scalive/api/src/scalive/forms/FormDefinition.scala:131-133)

def form[A](codec: Codec[A]): FormDefinition[type, A]

Builds a form definition from a codec owned by this root.

The owner type prevents combining this root with a codec from another FormRoot.

Parameters

codec: the codec that decodes the complete form value

Defined by scalive.FormRoot.form. View source (scalive/api/src/scalive/forms/FormDefinition.scala:121-122)

def optionalString(path: String, duplicateMessage: String = ...): Field[Option[String]]

Defines an optional scalar string field at a relative path.

Missing and empty values decode to None; one non-empty value decodes to Some(value). Duplicate values produce duplicateMessage.

Parameters

path: a non-empty path relative to this root
duplicateMessage: the error message used for duplicate values

Throws

IllegalArgumentException: if path parses to an empty form path

Defined by scalive.FormRoot.optionalString. View source (scalive/api/src/scalive/forms/FormDefinition.scala:96-100)

def requiredString(path: String, blankMessage: String = ..., duplicateMessage: String = ...): Field[String]

Defines a non-empty scalar string field at a relative path.

Missing and empty values produce blankMessage. Duplicate values produce duplicateMessage.

Parameters

path: a non-empty path relative to this root
blankMessage: the error message used for a missing or empty value
duplicateMessage: the error message used for duplicate values

Throws

IllegalArgumentException: if path parses to an empty form path

Defined by scalive.FormRoot.requiredString. View source (scalive/api/src/scalive/forms/FormDefinition.scala:77-82)

def string(path: String, duplicateMessage: String = ...): Field[String]

Defines a scalar string field at a relative path.

An absent field decodes to the empty string. Exactly one submitted value is accepted; two or more produce duplicateMessage.

Parameters

path: a non-empty path relative to this root
duplicateMessage: the error message used for duplicate values

Throws

IllegalArgumentException: if path parses to an empty form path

Defined by scalive.FormRoot.string. View source (scalive/api/src/scalive/forms/FormDefinition.scala:58-62)

def strings(path: String): Field[Vector[String]]

Defines a repeated string field that preserves every value in submission order.

An absent field decodes to an empty vector.

Parameters

path: a non-empty path relative to this root

Throws

IllegalArgumentException: if path parses to an empty form path

Defined by scalive.FormRoot.strings. View source (scalive/api/src/scalive/forms/FormDefinition.scala:111-112)

Values1

val path: FormPath

Defined by scalive.FormRoot.path. View source (scalive/api/src/scalive/forms/FormDefinition.scala:14-14)