leptos_form_tool

A declarative way to create forms for leptos.

leptos_form_tool allows you to define forms in a declarative way. Want a text box? Just call .text_input on the form builder. Then, separately, you define a FormStyle to specify how that text box should be rendered. This has several advantages:

• Separates the layout of the form from how it is rendered and styled
• Allows different styles to be swapped in and out quickly

Validations

You might find yourself asking, but why not just use components?

The biggest reason for creating leptos_form_tool is support for validating the fields. This validation logic can get rather complex, for instance, you likely want to perform validation on the client when the user clicks submit to immediately give the user feedback about any invalid input. But you often also want to do the same validation on the server to protect against any requests that don't come from your client or for a user that doesn't have WASM enabled.

Additionally, you might want to change the validation of one control based on the value of another. For example, you might want to make sure the "day" field is in a valid range, but that range depends on what the user selects in the "month" field. Or you might want to make sure the "confirm password" field matches the "password" field. leptos_form_tool makes this easy, as the validation function you provide operates on the entire form's data.

Sometimes you might not want to show some controls, and validation for those controls should only be done when they are visible.

lepos_form_tool takes care of all this for you.

FormStyle

To define how to render all the components a form might use, you define a type that implements the FormStyle trait. This trait has a method for each control that the form might need to render. To use this new style, you just need to change the Style associated trait of your form to your new type.

It's actually a little more complicated than that...

To give custom styles a little more freedom to configure how to render their controls on a per-control basis, the style will define an associated type (usually an enum) called StylingAttributes. A styling attribute can be added to a control by calling .style(/* style */) on the control builder. These styling attributes are accessible to the FormStyle implementation when rendering that control.

Therefore, swapping out styles also requires swapping out all the .style() calls.

Builders

leptos_form_tool makes heavy use of the builder pattern. You will build the form, controls, and sometimes even validation functions by calling methods on a builder that constructs the object based on the values you give it.

Context

Sometimes, you might want to be able to use something from the form's context to render the form. For example, you may want to use a user's token as context, to only render part of the form if they are an administrator. Or, you may need to get the options for a certain drop-down dynamically. The form's context is the solution to these problems.

On the form, you define the associated type Context. Then, any time you construct a Form, you must provide that context. The context can be used in the building of the form and can change what controls are rendered. Each control builder function (ex. .text_input()) has a context variant (ex. .text_input_cx()) that allows you to use the context for building that control.

To avoid a whole lot of headaches, the context is immutable once passed into the form. However, you can use leptos signals in the context just fine, as you don't need mutable access to call get/set on the signal.

Since the context can change how the form is rendered, and what controls are shown/hidden (thus changing what controls are validated), the context is needed to validate the form data on the server side. In general, when validating the form on the server, you should pass the same context as you did on the client, to make sure the validation logic is the same. If you are sure that changing the context won't change any of the validations, it is ok to use different contexts on the server and client.

It is important to note that for controls that are not shown (the .show_when(/* condition */) condition evaluates to false), the validation for that field does not run.

Custom Components

leptos_form_tool also supports custom components that can be defined in the user space. This keeps leptos_form_tool from putting limits on what you can do. There are custom_* methods on the form builder that allow you to add your component.

Getting Started

To learn by example, see the example project.

To follow a Getting Started guide, see [getting_started.md].

Compatability

Contributing

To contribute, fork the repo and make a PR. If you find a bug, feel free to open an issue.

By contributing, you agree that your changes are subject to the license found in [/LICENSE].