Welcome to the Finch Advanced Forms Guide! This guide will walk you through the steps to create advanced forms in your Finch application. Whether you're a seasoned developer or just starting, Finch offers a robust set of tools to simplify server-side web app development.

What are Advanced Forms?

Advanced forms in Finch are a way to create complex forms with validation and error handling. They are based on the AdvancedForm class. This class provides a simple way to create forms with validation and error handling. You can use this class to create forms with multiple fields, each with its own validation rules.

It reads the data from the request and validates it against the validation rules. It also provides a way to render the form in the view. You can use this class to create forms for user registration, login, profile update, etc.

Using Advanced Forms

To use advanced forms in your Finch application, you need to create a class that extends the AdvancedForm class. This class should implement the fields method, which returns a list of Field objects. Each Field object represents a field in the form and its validation rules.

Here is an example of how to create an advanced form for user registration:

class UserRegistrationForm extends AdvancedForm {
  @override
  String get widget => 'forms/registration.j2.html';

  @override
  String get name => 'form_example';

  @override
  List<Field> fields() {
    return [
      csrf(),
      Field('name', validators: [
        FieldValidator.requiredField(),
        FieldValidator.fieldLength(min: 3),
      ]),
      Field('email', validators: [
        FieldValidator.requiredField(),
        FieldValidator.isEmailField(),
      ]),
      Field('password', validators: [
        FieldValidator.requiredField(),
        FieldValidator.isPasswordField(),
      ]),
    ];
  }
}

In the above example, we have created a form with three fields: name, email, and password. Each field has its own validation rules. The csrf() method is used to add a CSRF token to the form. This is a security measure to prevent cross-site request forgery attacks. The csrf() method is provided by the AdvancedForm class.

Rendering the Form

To render the form in the view, you can use the render method provided by the AdvancedForm class. This method returns a string that can be rendered in the view. You can use this string in your view to render the form.

var form = UserRegistrationForm();
var formHtml = await form.render();
rq.addParam('form', formHtml);
return rq.renderView(path: 'user/registration.j2.html');

In the above example, we have created an instance of the UserRegistrationForm class. We have then called the render method to get the HTML string of the form. We have added this string to the request parameters with the key form. Finally, we have rendered the view user/registration.j2.html which will render the form.

Validating the Form

To validate the form, you can use the check method provided by the AdvancedForm class. This method validates the form data against the validation rules and returns a boolean value. If the form is valid, it returns true. Otherwise, it returns false.

var form = UserRegistrationForm();
var isValid = await form.check();
if (isValid) {
  // Process valid form data
} else {
  // Handle validation errors
}

In the above example, we have created an instance of the UserRegistrationForm class. We have then called the check method to validate the form data. If the form is valid, we can process the form data. Otherwise, we can handle the validation errors.

API Response

This kind as form would return a json response with the form data and validation errors. You can use this data to render the form in the view. You can also use this data to handle the validation errors in the view. Advanced form dettects API requests through /api/ in the url and it will return json response.

Render form in view

to render the form in the view, you can use the following code in your template:

{% include form_example.widget | unscape %}

Template Example

<form method="POST" action="/example/person/{{ (data._id) if data._id else '' }}" class="space-y-8">
    <input
        type="text"
        name="name"
        required
        value="{{ $n('form_example/name/value') }}"
        class="{{ 'border-rose-500 ring-2' if $n('form_example/name/errors/0') else 'border-slate-300' }}"
    />
    <div class="mt-1 text-[10px] text-rose-600 {{ '' if $n('form_example/name/errors/0') else 'hidden' }}">{{ $n('form_example/name/errors/0') }}</div>
    <input
        type="email"
        name="email"
        required
        value="{{ $n('form_example/email/value') }}"
        class="{{ 'border-rose-500 ring-2' if $n('form_example/email/errors/0') else 'border-slate-300' }}"
    />
    <div class="mt-1 text-[10px] text-rose-600 {{ '' if $n('form_example/email/errors/0') else 'hidden' }}">{{ $n('form_example/email/errors/0') }}</div>
    <input
        type="password"
        name="password"
        required
        value="{{ $n('form_example/password/value') }}"
        class="{{ 'border-rose-500 ring-2' if $n('form_example/password/errors/0') else 'border-slate-300' }}"
    />
    <div class="mt-1 text-[10px] text-rose-600 {{ '' if $n('form_example/password/errors/0') else 'hidden' }}">{{ $n('form_example/password/errors/0') }}</div>
    
    <!-- CSRF Token -->
    <input type="hidden" name="token" value="{{ $n('form_example/token/value') }}" />
    <div class="mt-1 text-[10px] text-rose-600 {{ $n('form_example/token/errors/0') ? '' : 'hidden' }}">{{ $n('form_example/token/errors/0') }}</div>

    <button type="submit" class="wave inline-flex h-9 items-center rounded-md border border-primary-600 bg-primary-50 px-3 text-xs font-medium text-primary-700 hover:bg-primary-100 focus:outline-none focus:ring-2 focus:ring-primary-500/30">{{ $t('database.table.button.add') }}</button>
</form>