Adding `webforms` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add webforms

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

webforms = "0.2.2"

The webforms library will be automatically available globally. Read the webforms library documentation.

Back to the crate overview.

Readme

Rust WebForms Library

This library supports validating and (in the future) rendering HTML forms for use with Askama or Tera templates.

Rust WebForms Library

Form Validation

To add form validation to a struct, implement or derive the ValidateForm trait. Validator attributes can either be applied to the struct or to individual fields.

Struct Attibutes

`#[validate_regex(...)]`

The #[validate_regex(...)] struct attribute accepts a key-value pair, where the key is an identifier that can later be used with the #[validate_regex(...)] field attributes and the value is a regex expression.

Validator	Type	Argument Type	Description	Notes
identifier	Ident	Regex	Creates an identifier that links to the regex provided	1, 2

Notes:

Requires the lazy_static and regex crates as dependencies
identifer is any user-specified string. This will be turned into an identifier than can be used with the #[validate(compiled_regex = "...")] field attribute

Struct Attribute Example

The following example compiles a regex name pw_regex and allows it to be used multiple times later in the form while only being compiled once.

use webforms::validate::ValidateForm;

#[derive(ValidateForm)]
#[validate_regex(pw_regex = r"^a_regex_string$")]
struct RegisterForm {
    ...
    #[validate_regex(pw_regex)]
    pub password1: String,

    #[validate_regex(pw_regex)]
    pub password2: String,
    ...
}

Field Attributes

`#[validate(...)]`

The #[validate(...)] attribute accepts either a pre-defined validator (e.g., email) or a key-value pair (e.g., min_length) where the key represents what to validate and the value represents the validation critera. See the table below for all currently implemented validators.

Validator	Type	Argument Type	Description	Notes
`email`	String	None	Checks if input is a valid email address	1
`phone`	String	None	Checks if input is a valid US phone number	1
`min_length`	String	Integer	Checks if input length in characters is greater than the value provided
`max_length`	String	Integer	Checks if input length in characters is less than the value provided
`min_value`	Numeric	Numeric	Checks if input is greater than the value provided	2
`max_value`	Numeric	Numeric	Checks if input is less than the value provided	2
`regex`	String	Regex	Checks if input matches the supplied regex	1

Notes:

Requires the lazy_static and regex crates as dependencies
Can be any numeric type (integer/float) but type must match the field being checked!

`#[validate_match(...)]`

The #[validate_match(...)] attribute accepts the name of another field in the struct. It ensures this field matches exactly the field specified in the attribue.

Argument	Type	Argument Type	Description	Notes
field	Varies	Field in Struct	Checks if this field matches the value specified in another field	1, 2

Type can vary, but must exactly match the field indicated in the attribute
Types must implement PartialEq for comparison

`#[validate_regex(...)]` (Field)

The #[validate_regex(...)] attribute accepts an identifier previously specified in a #[validate_regex(...)] applied to the struct. It allows a regex to be defined early and used numerous times throughout the struct with being redefined or compiled.

Argument	Type	Argument Type	Description	Notes
regex	String	Variable Name	Checks if this field matches the compiled regex stated in the struct attributes	1

Requires the lazy_static and regex crates as dependencies

Field Attribute Example

use webforms::validate::ValidateForm;

#[derive(ValidateForm)]
struct UpdateProfileForm {
    #[validate(email)]
    pub email: String,

    #[validate(regex = r"^some_password_regex$")]
    pub password: String,

    #[validate_match(password)]
    pub password2: String,

    #[validate(phone)]
    pub phone: String,

    #[validate(min_value = 18)]
    pub age: u8;
}

Using Geneated Code

This will automatically implement the ValidateForm trait allowing the validate() method to be called like so:

pub fn main() {
    let form = RegisterForm {
        ...
    };

    match form.validate() {
        Ok(_) => println!("success!"),
        Err(errs) => {
            for err in errs {
                println!("{:?}", err);
            }
        }
    }
}

validate() returns Ok(()) if validation suceeded or a vector of ValidationError types, each describing what field failed validation.

HTML Generation

TODO: Goal is to implement a method (perhans render()) that can be called from templating libraries to render a form to HTML

Information

License: MIT

Author: Kevin Allison

Adding webforms library as a dependency

Adding `webforms` library as a dependency