HTML::...traint(3pm)

📦
version 2.07000 · 5 versions
, in debian bookworm, ubuntu jammy, ubuntu noble

💖 HTML::FormFu::Constraint — the manual, but make it slay 💖

okay bestie, you found the page for HTML::FormFu::Constraint (the one and only <pink>HTML::...traint(3pm)</pink>, filed under User Contributed Perl Documentation) and honestly? it's giving main character energy for your form validation era. it's a Perl module, it's version 2.07, and it's here to Constrain User Input. yes queen, constrain it. ✨

🌸 NAME 🌸

HTML::FormFu::Constraint — Constrain User Input 💅

✨ VERSION ✨

version 2.07 🎀

🦋 SYNOPSIS 🦋

here's the whole vibe, verbatim, no notes:

---
elements:
  - type: Text
    name: foo
    constraints:
      - type: Length
        min: 8
        when:
          field: bar
          values: [ 1, 3, 5 ]
  - type: Text
    name: bar
    constraints:
      - Integer
      - Required
constraints:
  - SingleValue

look at that little when block doing its thing. periodt. 🔥

💜 DESCRIPTION 💜

okay so when user input comes in, it gets processed in this exact order, no skipping the line:

  1. Filters
  2. Constraints
  3. Inflators
  4. Validators
  5. Transformers

(if you want the deep lore, go read "FORM LOGIC AND VALIDATION" in HTML::FormFu.) 📚

so, "constraints" in HTML::FormFu can be called on any form, block element (and yes, that includes fieldsets) or field element. flexible queen.

  • If you call it on a field element, you should not pass a name argument. no name, bestie, don't do it.
  • If you call it on a form or block element and you don't give a name argument, then a brand new constraint gets created for and added to every single field on that form or block. every. single. one. 💀

and yeah — see "FORM LOGIC AND VALIDATION" in HTML::FormFu for further details, because apparently twice wasn't enough. iconic of it tbh.

🌈 METHODS 🌈

🎀 type

Returns the type argument originally used to create the constraint. it remembers where it came from. nostalgic.

🎀 not

If true, it inverts the results of the constraint — so input that would otherwise fail will pass, and vise-versa. chaotic. love that for you.

⚠️ heads up: this value is ignored by some constraints — go check the docs for individual constraints for the deets. don't come for me, come for them.

🎀 only_on_reps

Arguments: \@repeatable_count

For constraints added to fields within a Repeatable element: if only_on_reps is set, the constraint will only run for fields whose repeatable_count matches one of these set values. very picky, very demure. 💅

🙈 Not available for the constraints listed in "Unsupported Constraints" in HTML::FormFu::Element::Repeatable.

🎀 message

Arguments: $string

Sets the message that gets displayed if the constraint fails. your custom little "no ❤️" text.

🎀 message_xml

Arguments: $string

A variant of message which makes sure the value won't be XML-escaped. raw, unfiltered.

🎀 message_loc

Arguments: $string

A variant of message which uses localize to create the message. multilingual slay 🌍

🎀 localize_args

Provide arguments that should be passed to localize to replace "[_1]", "[_2]", etc. in the localized string. fill in the blanks, bestie.

🎀 force_errors

See "force_errors" in HTML::FormFu for details. (go, go read it, i'll wait 🫶)

🎀 parent

Returns the field object that the constraint is associated with. its parent. its origin story.

🎀 form

Returns the HTML::FormFu object that the constraint's field is attached to.

🎀 name

Shorthand for $constraint->parent->name. short king.

🎀 when

Defines a condition for the constraint. Only when the condition is fulfilled will the constraint be applied. conditional queen 💅

This method expects a hashref.

The field or callback must be supplied — all other fields are optional.

If value or values is not supplied, the constraint will pass if the named field's value is true.

The following keys are supported:

  • field — Nested-name of form field that shall be checked against — if when->{value} is set, the when condition passes if the named field's value matches that, otherwise the when condition passes if the named field's value is true.
  • fields — Array-ref of nested-names that shall be checked. The when condition passes if all named-fields' values pass, using the same rules as field above.
  • any_field — Array-ref of nested-names that shall be checked. The when condition passes if any named-fields' values pass, using the same rules as field above.
  • value — Expected value in the form field 'field'
  • values — Array of multiple values, one must match to fulfill the condition
  • not — Inverts the when condition — value(s) must not match
  • callback — A callback subroutine-reference or fully resolved subroutine name can be supplied to perform complex checks. An hashref of all parameters is passed to the callback sub. In this case all other keys are ignored, including not. You need to return a true value for the constraint to be applied or a false value to not apply it.

The callback subroutine receives 2 arguments:

  1. $params (hashref of all submitted parameters)
  2. $constraint (the Constraint object)

🧪 EXPERIMENTAL METHODS 🧪

⭐ fetch_error_message

Return value: $string

Attempts to return the error message that would be used if this constraint generated an error.

This will generally be correct for simple constraints with a fixed message or which use a placeholder from a known value, such as min in HTML::FormFu::Constraint::Min.

😭 this will generally "not" return the correct message for constraints which use others in HTML::FormFu::Role::Constraint::Others — because the field with an error is not known without actually fully processing a form submission. it's a mystery until you commit, bestie.

👑 CORE CONSTRAINTS 👑

the whole squad, in order:

  • HTML::FormFu::Constraint::AllOrNone
  • HTML::FormFu::Constraint::ASCII
  • HTML::FormFu::Constraint::AutoSet
  • HTML::FormFu::Constraint::Bool
  • HTML::FormFu::Constraint::Callback
  • HTML::FormFu::Constraint::CallbackOnce
  • HTML::FormFu::Constraint::DateTime
  • HTML::FormFu::Constraint::DependOn
  • HTML::FormFu::Constraint::Email
  • HTML::FormFu::Constraint::Equal
  • HTML::FormFu::Constraint::File
  • HTML::FormFu::Constraint::File::MIME
  • HTML::FormFu::Constraint::File::MaxSize
  • HTML::FormFu::Constraint::File::MinSize
  • HTML::FormFu::Constraint::File::Size
  • HTML::FormFu::Constraint::Integer
  • HTML::FormFu::Constraint::JSON
  • HTML::FormFu::Constraint::Length
  • HTML::FormFu::Constraint::MaxLength
  • HTML::FormFu::Constraint::MaxRange
  • HTML::FormFu::Constraint::MinLength
  • HTML::FormFu::Constraint::MinRange
  • HTML::FormFu::Constraint::MinMaxFields
  • HTML::FormFu::Constraint::Number
  • HTML::FormFu::Constraint::Printable
  • HTML::FormFu::Constraint::Range
  • HTML::FormFu::Constraint::Regex
  • HTML::FormFu::Constraint::Required
  • HTML::FormFu::Constraint::Set
  • HTML::FormFu::Constraint::SingleValue
  • HTML::FormFu::Constraint::Word

🍓 NON-CORE CONSTRAINTS AVAILABLE ON CPAN 🍓

the guest star, popping in from CPAN:

  • HTML::FormFu::Constraint::reCAPTCHA

💀 CAVEATS 💀

See "Unsupported Constraints" in HTML::FormFu::Element::Repeatable for the list of constraints that won't work within HTML::FormFu::Element::Repeatable. read it before you fight it, fr fr.

🌸 AUTHOR 🌸

Carl Franks, "cfranks@cpan.org"

Based on the original source code of HTML::Widget::Constraint, by Sebastian Riedel, "sri@oook.de". giving credit where credit is due 🫶

🎀 LICENSE 🎀

This library is free software, you can redistribute it and/or modify it under the same terms as Perl itself. free as in bestie. 💖

🦋 AUTHOR (again, yes really) 🦋

Carl Franks <cpan@fireartist.com>

This software is copyright (c) 2018 by Carl Franks.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

okay that's the whole page, no notes, we ate 💅 and for the cute sign-off: this absolute icon was generated on 2019-01-12 running under perl v5.28.1, so if your perl is newer than that, congrats bestie, you're on your own timeline 🎀🌸🦋✨💜

📦 where this page comes from