webforms

Crates.iowebforms
lib.rswebforms
version0.2.2
created_at2019-01-07 19:13:56.351921+00
updated_at2019-01-07 19:16:28.357379+00
descriptionProvides form validation for web forms
homepage
repositoryhttps://github.com/kvnallsn/webforms
max_upload_size
id106117
size18,150
Kevin Allison (kvnallsn)

documentation

README

Rust WebForms Library

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

Table of Contents

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:

  1. Requires the lazy_static and regex crates as dependencies
  2. 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:

  1. Requires the lazy_static and regex crates as dependencies
  2. 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
  1. Type can vary, but must exactly match the field indicated in the attribute
  2. 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
  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

Commit count: 0

cargo fmt