Create an empty form that only parses to thing. This is primarily intended to be the final return value of a chain of callbacks that adds the form’s fields.

create_form(1)
|> parse
# -> Ok(1)

fn make_form() {
  use field1 <- formz.require(field("field1"), definitions.text_field())
  use field2 <- formz.require(field("field2"), definitions.text_field())
  use field3 <- formz.require(field("field3"), definitions.text_field())

  create_form(#(field1, field2, field3))
}

Add input data to this form. This will set the raw string value of the fields. It does not trigger any parsing, so you can also use this to set default values (if you do it in your form generator function) or initial values (if you do it before rendering an empty form).

The input data is a list of tuples, where the first element is the name of the field and the second element is the value to set. If the field does not exist the data is ignored, and if multiple values are given for the same field, the last one wins.

Get the FormItem with the given name. If multiple items have the same name, the first one is returned.

Get each FormItem added to the form. Any time a field or subform are added, a FormItem is created.

Add an optional field to a form.

This will use both the parse and optional_parse functions from the definition to parse the input data when parsing this field. Ultimately whether a field is actually optional or not comes down to the details of the definition.

The final argument is a callback that will be called when the form is being constructed to look for more fields; validated to check for errors; and when the form is being parsed, to decode the input data. For this reason, the callback should be a function without side effects. It can be called any number of times. Don’t do anything but create the type with the data you need!

Parse the form. This means step through the fields one by one, parsing them individually. If any field fails to parse, the whole form is considered invalid, however it will still continue parsing the rest of the fields to collect all errors. This is useful for showing all errors at once. If no fields fail to parse, the decoded value is returned, which is the value given to create_form.

If you’d like to parse the form but not get the output, so you can give feedback to a user in response to input, you can use validate or validate_all.

Parse the form, then apply a function to the output if it was successful. This is a very thin wrapper around parse and result.try, but the difference being it will pass the form along to the function as a second argument in addition to the successful result. This allows you to easily update the form fields with errors or other information based on the output.

This is useful for situations where you can have errors in the form that aren’t easily checked in simple parsing functions. Like, say, hitting a db to check if a username is taken.

make_form()
|> data(form_data)
|> parse_then_try(fn(username, form) {
  case is_username_taken(username) {
    Ok(false) -> Ok(form)
    Ok(true) -> update_field(form, "username", field.set_error(_, "Username is taken"))
  }
}

Add a required field to a form.

This will use only the parse function from the definition to parse the input data when parsing this field. Ultimately whether a field is actually required or not comes down to the details of the definition.

This will also set the required value on the field to True. Form generators can use this to mark the HTML input elements as required for accessibility.

The final argument is a callback that will be called when the form is being constructed to look for more fields; validated to check for errors; and when the form is being parsed, to decode the input data. For this reason, the callback should be a function without side effects. It can be called any number of times. Don’t do anything but create the type with the data you need!

Add a form as a subform. This will essentially append the fields from the subform to the current form, prefixing their names with the name of the subform. Form generators will still see the fields as a set though, so they can be marked up as a group for accessibility reasons.

The final argument is a callback that will be called when the form is being constructed to look for more fields; validated to check for errors; and when the form is being parsed, to decode the input data. For this reason, the callback should be a function without side effects. It can be called any number of times. Don’t do anything but create the type with the data you need!

Update the FormItem with the given name using the provided function. If multiple items have the same name, it will be called on all of them.

Update the Field with the given name using the provided function. If multiple items have the same name, it will be called on all of them.

let form = make_form()
update(form, "name", field.set_label(_, "Full Name"))

Update the SubForm with the given name using the provided function. If multiple subforms have the same name, it will be called on all of them.

let form = make_form()
update(form, "name", subform.set_help_text(_, "..."))

Validate specific fields of the form. This is similar to parse, but instead of returning the decoded output if there are no errors, it returns the valid form. This is useful for if you want to be able to give feedback to the user about whether certain fields are valid or not. In this case you could just validate only fields that the user has interacted with.

Validate all the fields in the form. This is similar to parse, but instead of returning the decoded output if there are no errors, it returns the valid form. This is useful for if you want to be able to give feedback to the user about whether certain fields are valid or not.