{"id":15286152,"url":"https://github.com/formfu/html-formfu","last_synced_at":"2025-12-17T06:52:28.375Z","repository":{"id":1200966,"uuid":"1109274","full_name":"FormFu/HTML-FormFu","owner":"FormFu","description":"HTML Form Creation, Rendering and Validation Framework. Just define the form, and let FormFu do the all heavy lifting.","archived":false,"fork":false,"pushed_at":"2024-07-18T05:46:47.000Z","size":4481,"stargazers_count":34,"open_issues_count":3,"forks_count":24,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-03-27T03:51:17.237Z","etag":null,"topics":["catalyst","forms","perl","web-app"],"latest_commit_sha":null,"homepage":"http://formfu.rocks","language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/FormFu.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2010-11-24T14:31:07.000Z","updated_at":"2024-07-18T05:46:50.000Z","dependencies_parsed_at":"2024-09-30T15:11:45.203Z","dependency_job_id":"9e059933-1ae0-457c-9f00-b7d45a6500ff","html_url":"https://github.com/FormFu/HTML-FormFu","commit_stats":{"total_commits":1281,"total_committers":42,"mean_commits":30.5,"dds":"0.24902419984387203","last_synced_commit":"ae58ad3ac926a6921674d3f9e2aac660009fae6b"},"previous_names":[],"tags_count":21,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormFu%2FHTML-FormFu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormFu%2FHTML-FormFu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormFu%2FHTML-FormFu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/FormFu%2FHTML-FormFu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/FormFu","download_url":"https://codeload.github.com/FormFu/HTML-FormFu/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248717252,"owners_count":21150388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["catalyst","forms","perl","web-app"],"created_at":"2024-09-30T15:10:47.009Z","updated_at":"2025-12-17T06:52:28.330Z","avatar_url":"https://github.com/FormFu.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=pod\n\n=encoding UTF-8\n\n=head1 SYNOPSIS\n\nNote: These examples make use of L\u003cHTML::FormFu::Model::DBIC\u003e. As of\nC\u003cHTML::FormFu\u003e v02.005, the L\u003cHTML::FormFu::Model::DBIC\u003e module is\nnot bundled with C\u003cHTML::FormFu\u003e and is available in a stand-alone\ndistribution.\n\n    use HTML::FormFu;\n\n    my $form = HTML::FormFu-\u003enew;\n\n    $form-\u003eload_config_file('form.yml');\n\n    $form-\u003eprocess( $cgi_query );\n\n    if ( $form-\u003esubmitted_and_valid ) {\n        # do something with $form-\u003eparams\n    }\n    else {\n        # display the form\n        $template-\u003eparam( form =\u003e $form );\n    }\n\nIf you're using L\u003cCatalyst\u003e, a more suitable example might be:\n\n    package MyApp::Controller::User;\n    use Moose;\n    extends 'Catalyst::Controller::HTML::FormFu';\n\n    sub user : Chained CaptureArgs(1) {\n        my ( $self, $c, $id ) = @_;\n\n        my $rs = $c-\u003emodel('Schema')-\u003eresultset('User');\n\n        $c-\u003estash-\u003e{user} = $rs-\u003efind( $id );\n\n        return;\n    }\n\n    sub edit : Chained('user') Args(0) FormConfig {\n        my ( $self, $c ) = @_;\n\n        my $form = $c-\u003estash-\u003e{form};\n        my $user = $c-\u003estash-\u003e{user};\n\n        if ( $form-\u003esubmitted_and_valid ) {\n\n            $form-\u003emodel-\u003eupdate( $user );\n\n            $c-\u003eres-\u003eredirect( $c-\u003euri_for( \"/user/$id\" ) );\n            return;\n        }\n\n        $form-\u003emodel-\u003edefault_values( $user )\n            if ! $form-\u003esubmitted;\n\n    }\n\nNote: Because L\u003c/process\u003e is automatically called for you by the Catalyst\ncontroller; if you make any modifications to the form within your action\nmethod, such as adding or changing elements, adding constraints, etc;\nyou must call L\u003c/process\u003e again yourself before using L\u003c/submitted_and_valid\u003e,\nany of the methods listed under L\u003c/\"SUBMITTED FORM VALUES AND ERRORS\"\u003e or\nL\u003c/\"MODIFYING A SUBMITTED FORM\"\u003e, or rendering the form.\n\nHere's an example of a config file to create a basic login form (all examples\nhere are L\u003cYAML\u003e, but you can use any format supported by L\u003cConfig::Any\u003e),\nyou can also create forms directly in your perl code, rather than using an\nexternal config file.\n\n    ---\n    action: /login\n    indicator: submit\n    auto_fieldset: 1\n\n    elements:\n      - type: Text\n        name: user\n        constraints:\n          - Required\n\n      - type: Password\n        name: pass\n        constraints:\n          - Required\n\n      - type: Submit\n        name: submit\n\n    constraints:\n      - SingleValue\n\n=head1 DESCRIPTION\n\nL\u003cHTML::FormFu\u003e is a HTML form framework which aims to be as easy as\npossible to use for basic web forms, but with the power and flexibility to\ndo anything else you might want to do (as long as it involves forms).\n\nYou can configure almost any part of formfu's behaviour and output. By\ndefault formfu renders \"XHTML 1.0 Strict\" compliant markup, with as little\nextra markup as possible, but with sufficient CSS class names to allow for a\nwide-range of output styles to be generated by changing only the CSS.\n\nAll methods listed below (except L\u003c/new\u003e) can either be called as a normal\nmethod on your C\u003c$form\u003e object, or as an option in your config file. Examples\nwill mainly be shown in L\u003cYAML\u003e config syntax.\n\nThis documentation follows the convention that method arguments surrounded\nby square brackets C\u003c[]\u003e are I\u003coptional\u003e, and all other arguments are\nrequired.\n\n=head1 BUILDING A FORM\n\n=head2 new\n\nArguments: [\\%options]\n\nReturn Value: $form\n\nCreate a new L\u003cHTML::FormFu|HTML::FormFu\u003e object.\n\nAny method which can be called on the L\u003cHTML::FormFu|HTML::FormFu\u003e object may\ninstead be passed as an argument to L\u003c/new\u003e.\n\n    my $form = HTML::FormFu-\u003enew({\n        action        =\u003e '/search',\n        method        =\u003e 'GET',\n        auto_fieldset =\u003e 1,\n    });\n\n=head2 load_config_file\n\nArguments: $filename\n\nArguments: \\@filenames\n\nReturn Value: $form\n\nAccepts a filename or list of file names, whose filetypes should be of any\nformat recognized by L\u003cConfig::Any\u003e.\n\nThe content of each config file is passed to L\u003c/populate\u003e, and so are added\nto the form.\n\nL\u003c/load_config_file\u003e may be called in a config file itself, so as to allow\ncommon settings to be kept in a single config file which may be loaded\nby any form.\n\n    ---\n    load_config_file:\n      - file1\n      - file2\n\nYAML multiple documents within a single file. The document start marker is\na line containing 3 dashes. Multiple documents will be applied in order,\njust as if multiple filenames had been given.\n\nIn the following example, multiple documents are taken advantage of to\nload another config file after the elements are added. (If this were\na single document, the C\u003cload_config_file\u003e would be called before\nC\u003celements\u003e, regardless of its position in the file).\n\n    ---\n    elements:\n      - name: one\n      - name: two\n\n    ---\n    load_config_file: ext.yml\n\nRelative paths are resolved from the L\u003c/config_file_path\u003e directory if\nit is set, otherwise from the current working directory.\n\nSee L\u003c/BEST PRACTICES\u003e for advice on organising config files.\n\n=head2 config_callback\n\nArguments: \\%options\n\nIf defined, the arguments are used to create a L\u003cData::Visitor::Callback\u003e\nobject during L\u003c/load_config_file\u003e which may be used to pre-process the\nconfig before it is sent to L\u003c/populate\u003e.\n\nFor example, the code below adds a callback to a form that will dynamically\nalter any config value ending in \".yml\" to end in \".yaml\" when you call\nL\u003c/load_config_file\u003e:\n\n    $form-\u003econfig_callback({\n      plain_value =\u003e sub {\n        my( $visitor, $data ) = @_;\n        s/\\.yml/.yaml/;\n      }\n    });\n\nDefault Value: not defined\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element or a single element. When the value is read, if\nno value is defined it automatically traverses the element's hierarchy of\nparents, through any block elements and up to the form, searching for a\ndefined value.\n\n=head2 populate\n\nArguments: \\%options\n\nReturn Value: $form\n\nEach option key/value passed may be any L\u003cHTML::FormFu|HTML::FormFu\u003e\nmethod-name and arguments.\n\nProvides a simple way to set multiple values, or add multiple elements to\na form with a single method-call.\n\nAttempts to call the method-names in a semi-intelligent order (see\nthe source of populate() in C\u003cHTML::FormFu::ObjectUtil\u003e for details).\n\n=head2 default_values\n\nArguments: \\%defaults\n\nReturn Value: $form\n\nSet multiple field's default values from a single hash-ref.\n\nThe hash-ref's keys correspond to a form field's name, and the value is\npassed to the field's L\u003cdefault method|HTML::FormFu::_Field/default\u003e.\n\nThis should be called after all fields have been added to the form, and\nbefore L\u003c/process\u003e is called (otherwise, call L\u003c/process\u003e again before\nrendering the form).\n\n=head2 config_file_path\n\nArguments: $directory_name\n\nL\u003c/config_file_path\u003e defines where configuration files will be\nsearched for, if an absolute path is not given to\nL\u003c/load_config_file\u003e.\n\nDefault Value: not defined\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element or a single element. When the value is read, if\nno value is defined it automatically traverses the element's hierarchy of\nparents, through any block elements and up to the form, searching for a\ndefined value.\n\nIs an L\u003cinheriting accessor|/INHERITING ACCESSORS\u003e.\n\n=head2 indicator\n\nArguments: $field_name\n\nArguments: \\\u0026coderef\n\nIf L\u003c/indicator\u003e is set to a fieldname, L\u003c/submitted\u003e will return true if\na value for that fieldname was submitted.\n\nIf L\u003c/indicator\u003e is set to a code-ref, it will be called as a subroutine\nwith the two arguments C\u003c$form\u003e and C\u003c$query\u003e, and its return value will be\nused as the return value for L\u003c/submitted\u003e.\n\nIf L\u003c/indicator\u003e is not set, L\u003c/submitted\u003e will return true if a value for\nany known fieldname was submitted.\n\n=head2 auto_fieldset\n\nArguments: 1\n\nArguments: \\%options\n\nReturn Value: $fieldset\n\nThis setting is suitable for most basic forms, and means you can generally\nignore adding fieldsets yourself.\n\nCalling C\u003c\u003c $form-\u003eauto_fieldset(1) \u003e\u003e immediately adds a fieldset element to\nthe form. Thereafter, C\u003c\u003c $form-\u003eelements() \u003e\u003e will add all elements (except\nfieldsets) to that fieldset, rather than directly to the form.\n\nTo be specific, the elements are added to the I\u003clast\u003e fieldset on the form,\nso if you add another fieldset, any further elements will be added to that\nfieldset.\n\nAlso, you may pass a hashref to auto_fieldset(), and this will be used\nto set defaults for the first fieldset created.\n\nA few examples and their output, to demonstrate:\n\n2 elements with no fieldset.\n\n    ---\n    elements:\n      - type: Text\n        name: foo\n      - type: Text\n        name: bar\n\n    \u003cform action=\"\" method=\"post\"\u003e\n      \u003cdiv class=\"text\"\u003e\n        \u003cinput name=\"foo\" type=\"text\" /\u003e\n      \u003c/div\u003e\n      \u003cdiv class=\"text\"\u003e\n        \u003cinput name=\"bar\" type=\"text\" /\u003e\n      \u003c/div\u003e\n    \u003c/form\u003e\n\n2 elements with an L\u003c/auto_fieldset\u003e.\n\n    ---\n    auto_fieldset: 1\n    elements:\n      - type: Text\n        name: foo\n      - type: Text\n        name: bar\n\n    \u003cform action=\"\" method=\"post\"\u003e\n      \u003cfieldset\u003e\n        \u003cdiv class=\"text\"\u003e\n          \u003cinput name=\"foo\" type=\"text\" /\u003e\n        \u003c/div\u003e\n        \u003cdiv class=\"text\"\u003e\n          \u003cinput name=\"bar\" type=\"text\" /\u003e\n        \u003c/div\u003e\n      \u003c/fieldset\u003e\n    \u003c/form\u003e\n\nThe 3rd element is within a new fieldset\n\n    ---\n    auto_fieldset: { id: fs }\n    elements:\n      - type: Text\n        name: foo\n      - type: Text\n        name: bar\n      - type: Fieldset\n      - type: Text\n        name: baz\n\n    \u003cform action=\"\" method=\"post\"\u003e\n      \u003cfieldset id=\"fs\"\u003e\n        \u003cdiv class=\"text\"\u003e\n          \u003cinput name=\"foo\" type=\"text\" /\u003e\n        \u003c/div\u003e\n        \u003cdiv class=\"text\"\u003e\n          \u003cinput name=\"bar\" type=\"text\" /\u003e\n        \u003c/div\u003e\n      \u003c/fieldset\u003e\n      \u003cfieldset\u003e\n        \u003cdiv class=\"text\"\u003e\n          \u003cinput name=\"baz\" type=\"text\" /\u003e\n        \u003c/div\u003e\n      \u003c/fieldset\u003e\n    \u003c/form\u003e\n\nBecause of this behaviour, if you want nested fieldsets you will have to add\neach nested fieldset directly to its intended parent.\n\n    my $parent = $form-\u003eget_element({ type =\u003e 'Fieldset' });\n\n    $parent-\u003eelement('fieldset');\n\n=head2 form_error_message\n\nArguments: $string\n\nNormally, input errors cause an error message to be displayed alongside the\nappropriate form field. If you'd also like a general error message to be\ndisplayed at the top of the form, you can set the message with\nL\u003c/form_error_message\u003e.\n\nTo set the CSS class for the message, see L\u003c/form_error_message_class\u003e.\n\nTo change the markup used to display the message, edit the\nC\u003cform_error_message\u003e template file. See L\u003c/render_method\u003e.\n\nIs an L\u003coutput accessor|HTML::FormFu/OUTPUT ACCESSORS\u003e.\n\n=head2 force_error_message\n\nIf true, forces the L\u003c/form_error_message\u003e to be displayed even if there are\nno field errors.\n\n=head2 default_args\n\nArguments: \\%defaults\n\nSet defaults which will be added to every element, constraint, etc. of the\ngiven type which is subsequently added to the form.\n\nFor example, to make every C\u003cText\u003e element automatically have a size of\nC\u003c10\u003e, and make every C\u003cStrftime\u003e deflator automatically get its strftime\nset to C\u003c%d/%m/%Y\u003e:\n\n    default_args:\n        elements:\n            Text:\n                size: 10\n        deflators:\n            Strftime:\n                strftime: '%d/%m/%Y'\n\nAn example to make all DateTime elements automatically get an appropriate\nStrftime deflator and a DateTime inflator:\n\n    default_args:\n        elements:\n            DateTime:\n                deflators:\n                    type: Strftime\n                    strftime: '%d-%m-%Y'\n                inflators:\n                    type: DateTime\n                    parser:\n                        strptime: '%d-%m-%Y'\n\n=head3 Pseudo types\n\nAs a special case, you can also use the C\u003celements\u003e keys C\u003cBlock\u003e, C\u003cField\u003e\nand C\u003cInput\u003e to match any element which inherits from\nL\u003cHTML::FormFu::Element::Block\u003e or which C\u003cdoes\u003e\nL\u003cHTML::FormFu::Role::Element::Field\u003e or\nL\u003cHTML::FormFu::Role::Element::Input\u003e.\n\n=head3 Alternatives\n\nEach C\u003celements\u003e key can contain an C\u003cany\u003e list using the C\u003c|\u003e divider: e.g.\n\n    # apply the given class to any Element of type Password or Button\n    default_args:\n        elements:\n            'Password|Button':\n                attrs:\n                    class: novalidate\n\n=head3 Match ancestor\n\nEach C\u003celements\u003e key list can contain a type starting with C\u003c+\u003e to only\nmatch elements with an ancestor of the given type: e.g.\n\n    # only apple the given class to an Input field within a Multi block\n    default_args:\n        elements:\n            'Input|+Multi':\n                attrs:\n                    class: novalidate\n\n=head3 Don't match ancestor\n\nEach C\u003celements\u003e key list can contain a type starting with C\u003c-\u003e to only\nmatch elements who do not have an ancestor of the given type: e.g.\n\n    # apply the given class only to Input fields that are not in a Multi block\n    default_args:\n        elements:\n            'Input|-Multi':\n                attrs:\n                    class: validate\n\n=head3 Order\n\nThe arguments are applied in least- to most-specific order:\nC\u003cBlock\u003e, C\u003cField\u003e, C\u003cInput\u003e, C\u003c$type\u003e. Within each of these, arguments are\napplied in order of shortest-first to longest-last.\n\nThe C\u003ctype\u003e key must match the value returned by C\u003ctype\u003e, e.g.\nL\u003cHTML::FormFu::Element/type\u003e. If, for example, you have a custom element\noutside of the C\u003cHTML::FormFu::Element::*\u003e namespace, which you load via\nC\u003c\u003c $form-\u003eelement({ type =\u003e '+My::Custom::Element' }) \u003e\u003e, the key given to\nL\u003c/default_args\u003e should B\u003cnot\u003e include the leading C\u003c+\u003e, as that is\nstripped-out of the returned C\u003ctype()\u003e value. Example:\n\n    # don't include the leading '+' here\n    default_args:\n        elements:\n            'My::Custom::Element':\n                attrs:\n                    class: whatever\n\n    # do include the leading '+' here\n    elements:\n        - type: +My::Custom::Element\n\n=head3 Clashes\n\nL\u003c/default_args\u003e generates a single hashref to pass to L\u003c/populate\u003e, merging\narguments for each type in turn - meaning L\u003c/populate\u003e is only called once\nin total - not once for each type.\nBecause scalar values are B\u003cnot\u003e merged - this means later values will\noverride earlier values: e.g.\n\n    # Normally, calling $field-\u003eadd_attrs({ class =\u003e 'input' })\n    # then calling      $field-\u003eadd_attrs({ class =\u003e 'not-in-multi' })\n    # would result in both values being retained:\n    #           class=\"input not-in-multi\"\n    #\n    # However, default_args() creates a single data-structure to pass once\n    # to populate(), so any scalar values will overwrite earlier ones\n    # before they reach populate().\n    #\n    # The below example would result in the longest-matching key\n    # overwriting any others:\n    #           class=\"not-in-multi\"\n    #\n    default_args:\n        elements:\n            Input:\n                add_attrs:\n                    class: input\n            'Input:-Multi':\n                add_attrs:\n                    class: not-in-multi\n\n=head3 Strictness\n\nNote: Unlike the proper methods which have aliases, for example L\u003c/elements\u003e\nwhich is an alias for L\u003c/element\u003e - the keys given to C\u003cdefault_args\u003e must\nbe of the plural form, e.g.:\n\n    default_args:\n        elements:          {}\n        deflators:         {}\n        filters:           {}\n        constraints:       {}\n        inflators:         {}\n        validators:        {}\n        transformers:      {}\n        output_processors: {}\n\n=head2 javascript\n\nIf set, the contents will be rendered within a C\u003cscript\u003e tag, inside the top\nof the form.\n\n=head2 javascript_src\n\nArguments: $url\n\nArguments: \\@urls\n\nAdds a C\u003cscript\u003e tag for each URL, immediately before any L\u003c/javascript\u003e\nsection.\n\n=head2 stash\n\nArguments: [\\%private_stash]\n\nReturn Value: \\%stash\n\nProvides a hash-ref in which you can store any data you might want to\nassociate with the form.\n\n    ---\n    stash:\n      foo: value\n      bar: value\n\n=head2 elements\n\n=head2 element\n\nArguments: $type\n\nArguments: \\%options\n\nReturn Value: $element\n\nArguments: \\@arrayref_of_types_or_options\n\nReturn Value: @elements\n\nAdds a new element to the form. See\nL\u003cHTML::FormFu::Element/\"CORE FORM FIELDS\"\u003e and\nL\u003cHTML::FormFu::Element/\"OTHER CORE ELEMENTS\"\u003e\nfor a list of core elements.\n\nIf you want to load an element from a namespace other than\nC\u003cHTML::FormFu::Element::\u003e, you can use a fully qualified package-name by\nprefixing it with C\u003c+\u003e.\n\n    ---\n    elements:\n      - type: +MyApp::CustomElement\n        name: foo\n\nIf a C\u003ctype\u003e is not provided in the C\u003c\\%options\u003e, the default C\u003cText\u003e will\nbe used.\n\nL\u003c/element\u003e is an alias for L\u003c/elements\u003e.\n\n=head2 deflators\n\n=head2 deflator\n\nArguments: $type\n\nArguments: \\%options\n\nReturn Value: $deflator\n\nArguments: \\@arrayref_of_types_or_options\n\nReturn Value: @deflators\n\nA L\u003cdeflator|HTML::FormFu::Deflator\u003e may be associated with any form field,\nand allows you to provide\nL\u003c\u003c $field-\u003edefault|HTML::FormFu::Role::Element::Field/default \u003e\u003e with a value\nwhich may be an object.\n\nIf an object doesn't stringify to a suitable value for display, the\nL\u003cdeflator|HTML::FormFu::Deflator\u003e can ensure that the form field\nreceives a suitable string value instead.\n\nSee L\u003cHTML::FormFu::Deflator/\"CORE DEFLATORS\"\u003e for a list of core deflators.\n\nIf a C\u003cname\u003e attribute isn't provided, a new deflator is created for and\nadded to every field on the form.\n\nIf you want to load a deflator in a namespace other than\nC\u003cHTML::FormFu::Deflator::\u003e, you can use a fully qualified package-name by\nprefixing it with C\u003c+\u003e.\n\nL\u003c/deflator\u003e is an alias for L\u003c/deflators\u003e.\n\n=head2 insert_before\n\nArguments: $new_element, $existing_element\n\nReturn Value: $new_element\n\nThe 1st argument must be the element you want added, the 2nd argument\nmust be the existing element that the new element should be placed before.\n\n    my $new = $form-\u003eelement(\\%specs);\n\n    my $position = $form-\u003eget_element({ type =\u003e $type, name =\u003e $name });\n\n    $form-\u003einsert_before( $new, $position );\n\nIn the first line of the above example, the C\u003c$new\u003e element is initially\nadded to the end of the form. However, the C\u003cinsert_before\u003e method\nreparents the C\u003c$new\u003e element, so it will no longer be on the end of the\nform. Because of this, if you try to copy an element from one form to\nanother, it will 'steal' the element, instead of copying it. In this case,\nyou must use C\u003cclone\u003e:\n\n    my $new = $form1-\u003eget_element({ type =\u003e $type1, name =\u003e $name1 })\n                    -\u003eclone;\n\n    my $position = $form2-\u003eget_element({ type =\u003e $type2, name =\u003e $name2 });\n\n    $form2-\u003einsert_before( $new, $position );\n\n=head2 insert_after\n\nArguments: $new_element, $existing_element\n\nReturn Value: $new_element\n\nThe 1st argument must be the element you want added, the 2nd argument\nmust be the existing element that the new element should be placed after.\n\n    my $new = $form-\u003eelement(\\%specs);\n\n    my $position = $form-\u003eget_element({ type =\u003e $type, name =\u003e $name });\n\n    $form-\u003einsert_after( $new, $position );\n\nIn the first line of the above example, the C\u003c$new\u003e element is initially\nadded to the end of the form. However, the C\u003cinsert_after\u003e method\nreparents the C\u003c$new\u003e element, so it will no longer be on the end of the\nform. Because of this, if you try to copy an element from one form to\nanother, it will 'steal' the element, instead of copying it. In this case,\nyou must use C\u003cclone\u003e:\n\n    my $new = $form1-\u003eget_element({ type =\u003e $type1, name =\u003e $name1 })\n                    -\u003eclone;\n\n    my $position = $form2-\u003eget_element({ type =\u003e $type2, name =\u003e $name2 });\n\n    $form2-\u003einsert_after( $new, $position );\n\n=head2 remove_element\n\nArguments: $element\n\nReturn Value: $element\n\nRemoves the C\u003c$element\u003e from the form or block's array of children.\n\n    $form-\u003eremove_element( $element );\n\nThe orphaned element cannot be usefully used for anything until it is\nre-attached to a form or block with L\u003c/insert_before\u003e or L\u003c/insert_after\u003e.\n\n=head1 FORM LOGIC AND VALIDATION\n\nL\u003cHTML::FormFu|HTML::FormFu\u003e provides several stages for what is\ntraditionally described as I\u003cvalidation\u003e. These are:\n\n=over\n\n=item L\u003cHTML::FormFu::Filter|HTML::FormFu::Filter\u003e\n\n=item L\u003cHTML::FormFu::Constraint|HTML::FormFu::Constraint\u003e\n\n=item L\u003cHTML::FormFu::Inflator|HTML::FormFu::Inflator\u003e\n\n=item L\u003cHTML::FormFu::Validator|HTML::FormFu::Validator\u003e\n\n=item L\u003cHTML::FormFu::Transformer|HTML::FormFu::Transformer\u003e\n\n=back\n\nThe first stage, the filters, allow for cleanup of user-input, such as\nencoding, or removing leading/trailing whitespace, or removing non-digit\ncharacters from a creditcard number.\n\nAll of the following stages allow for more complex processing, and each of\nthem have a mechanism to allow exceptions to be thrown, to represent input\nerrors. In each stage, all form fields must be processed without error for\nthe next stage to proceed. If there were any errors, the form should be\nre-displayed to the user, to allow them to input correct values.\n\nConstraints are intended for low-level validation of values, such as\n\"is this an integer?\", \"is this value within bounds?\" or\n\"is this a valid email address?\".\n\nInflators are intended to allow a value to be turned into an appropriate\nobject. The resulting object will be passed to subsequent Validators and\nTransformers, and will also be returned by L\u003c/params\u003e and L\u003c/param\u003e.\n\nValidators are intended for higher-level validation, such as\nbusiness-logic and database constraints such as \"is this username unique?\".\nValidators are only run if all Constraints and Inflators have run\nwithout errors. It is expected that most Validators will be\napplication-specific, and so each will be implemented as a separate class\nwritten by the HTML::FormFu user.\n\n=head2 filters\n\n=head2 filter\n\nArguments: $type\n\nArguments: \\%options\n\nReturn Value: $filter\n\nArguments: \\@arrayref_of_types_or_options\n\nReturn Value: @filters\n\nIf you provide a C\u003cname\u003e or C\u003cnames\u003e value, the filter will be added to\njust that named field.\nIf you do not provide a C\u003cname\u003e or C\u003cnames\u003e value, the filter will be added\nto all L\u003cfields|HTML::FormFu::Role::Element::Field\u003e already attached to the form.\n\nSee L\u003cHTML::FormFu::Filter/\"CORE FILTERS\"\u003e for a list of core filters.\n\nIf you want to load a filter in a namespace other than\nC\u003cHTML::FormFu::Filter::\u003e, you can use a fully qualified package-name by\nprefixing it with C\u003c+\u003e.\n\nL\u003c/filter\u003e is an alias for L\u003c/filters\u003e.\n\n=head2 constraints\n\n=head2 constraint\n\nArguments: $type\n\nArguments: \\%options\n\nReturn Value: $constraint\n\nArguments: \\@arrayref_of_types_or_options\n\nReturn Value: @constraints\n\nSee L\u003cHTML::FormFu::Constraint/\"CORE CONSTRAINTS\"\u003e for a list of core\nconstraints.\n\nIf a C\u003cname\u003e attribute isn't provided, a new constraint is created for and\nadded to every field on the form.\n\nIf you want to load a constraint in a namespace other than\nC\u003cHTML::FormFu::Constraint::\u003e, you can use a fully qualified package-name by\nprefixing it with C\u003c+\u003e.\n\nL\u003c/constraint\u003e is an alias for L\u003c/constraints\u003e.\n\n=head2 inflators\n\n=head2 inflator\n\nArguments: $type\n\nArguments: \\%options\n\nReturn Value: $inflator\n\nArguments: \\@arrayref_of_types_or_options\n\nReturn Value: @inflators\n\nSee L\u003cHTML::FormFu::Inflator/\"CORE INFLATORS\"\u003e for a list of core inflators.\n\nIf a C\u003cname\u003e attribute isn't provided, a new inflator is created for and\nadded to every field on the form.\n\nIf you want to load an inflator in a namespace other than\nC\u003cHTML::FormFu::Inflator::\u003e, you can use a fully qualified package-name by\nprefixing it with C\u003c+\u003e.\n\nL\u003c/inflator\u003e is an alias for L\u003c/inflators\u003e.\n\n=head2 validators\n\n=head2 validator\n\nArguments: $type\n\nArguments: \\%options\n\nReturn Value: $validator\n\nArguments: \\@arrayref_of_types_or_options\n\nReturn Value: @validators\n\nSee L\u003cHTML::FormFu::Validator/\"CORE VALIDATORS\"\u003e for a list of core\nvalidators.\n\nIf a C\u003cname\u003e attribute isn't provided, a new validator is created for and\nadded to every field on the form.\n\nIf you want to load a validator in a namespace other than\nC\u003cHTML::FormFu::Validator::\u003e, you can use a fully qualified package-name by\nprefixing it with C\u003c+\u003e.\n\nL\u003c/validator\u003e is an alias for L\u003c/validators\u003e.\n\n=head2 transformers\n\n=head2 transformer\n\nArguments: $type\n\nArguments: \\%options\n\nReturn Value: $transformer\n\nArguments: \\@arrayref_of_types_or_options\n\nReturn Value: @transformers\n\nSee L\u003cHTML::FormFu::Transformer/\"CORE TRANSFORMERS\"\u003e for a list of core\ntransformers.\n\nIf a C\u003cname\u003e attribute isn't provided, a new transformer is created for and\nadded to every field on the form.\n\nIf you want to load a transformer in a namespace other than\nC\u003cHTML::FormFu::Transformer::\u003e, you can use a fully qualified package-name by\nprefixing it with C\u003c+\u003e.\n\nL\u003c/transformer\u003e is an alias for L\u003c/transformers\u003e.\n\n=head1 CHANGING DEFAULT BEHAVIOUR\n\n=head2 render_processed_value\n\nThe default behaviour when re-displaying a form after a submission, is that\nthe field contains the original unchanged user-submitted value.\n\nIf L\u003c/render_processed_value\u003e is true, the field value will be the final\nresult after all Filters, Inflators and Transformers have been run.\nDeflators will also be run on the value.\n\nIf you set this on a field with an Inflator, but without an equivalent\nDeflator, you should ensure that the Inflators stringify back to a usable\nvalue, so as not to confuse / annoy the user.\n\nDefault Value: false\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element or a single element. When the value is read, if\nno value is defined it automatically traverses the element's hierarchy of\nparents, through any block elements and up to the form, searching for a\ndefined value.\n\nIs an L\u003cinheriting accessor|/INHERITING ACCESSORS\u003e.\n\n=head2 force_errors\n\nForce a constraint to fail, regardless of user input.\n\nIf this is called at runtime, after the form has already been processed,\nyou must called L\u003cHTML::FormFu/process\u003e again before redisplaying the\nform to the user.\n\nDefault Value: false\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element, an element or a single constraint. When the value\nis read, if no value is defined it automatically traverses the element's\nhierarchy of parents, through any block elements and up to the form,\nsearching for a defined value.\n\nIs an L\u003cinheriting accessor|/INHERITING ACCESSORS\u003e.\n\n=head2 params_ignore_underscore\n\nIf true, causes L\u003c/params\u003e, L\u003c/param\u003e and L\u003c/valid\u003e to ignore any fields\nwhose name starts with an underscore C\u003c_\u003e.\n\nThe field is still processed as normal, and errors will cause\nL\u003c/submitted_and_valid\u003e to return false.\n\nDefault Value: false\n\n=head1 FORM ATTRIBUTES\n\nAll attributes are added to the rendered form's start tag.\n\n=head2 attributes\n\n    # Example\n    ---\n    attributes:\n      id: form\n      class: fancy_form\n\nIs an L\u003cattribute accessor|HTML::FormFu/ATTRIBUTE ACCESSOR\u003e.\n\n=head2 id\n\nIs an L\u003cattribute short-cut|HTML::FormFu/ATTRIBUTE SHORT-CUTS\u003e.\n\n=head2 action\n\nDefault Value: \"\"\n\nGet or set the action associated with the form. The default is no action,\nwhich causes most browsers to submit to the current URI.\n\nIs an L\u003cattribute short-cut|HTML::FormFu/ATTRIBUTE SHORT-CUTS\u003e.\n\n=head2 enctype\n\nGet or set the encoding type of the form. Valid values are\nC\u003capplication/x-www-form-urlencoded\u003e and C\u003cmultipart/form-data\u003e.\n\nIf the form contains a File element, the enctype is automatically set to\nC\u003cmultipart/form-data\u003e.\n\nIs an L\u003cattribute short-cut|HTML::FormFu/ATTRIBUTE SHORT-CUTS\u003e.\n\n=head2 method\n\nDefault Value: \"post\"\n\nGet or set the method used to submit the form. Can be set to either \"post\"\nor \"get\".\n\nIs an L\u003cattribute short-cut|HTML::FormFu/ATTRIBUTE SHORT-CUTS\u003e.\n\n=head2 title\n\nGet or set the form's title attribute.\n\nIs an L\u003cattribute short-cut|HTML::FormFu/ATTRIBUTE SHORT-CUTS\u003e.\n\n=head1 CSS CLASSES\n\n=head2 form_error_message_class\n\nClass attribute for the error message displayed at the top of the form.\n\nSee L\u003c/\"form_error_message\"\u003e\n\n=head1 LOCALIZATION\n\n=head2 languages\n\nArguments: [\\@languages]\n\nA list of languages which will be passed to the localization object.\n\nDefault Value: ['en']\n\n=head2 localize_class\n\nArguments: [$class_name]\n\nClassname to be used for the default localization object.\n\nDefault Value: 'HTML::FormFu::I18N'\n\n=head2 localize\n\n=head2 loc\n\nArguments: [$key, @arguments]\n\nCompatible with the C\u003cmaketext\u003e method in L\u003cLocale::Maketext\u003e.\n\n=head2 locale\n\nArguments: $locale\n\nCurrently only used by L\u003cHTML::FormFu::Deflator::FormatNumber\u003e and\nL\u003cHTML::FormFu::Filter::FormatNumber\u003e.\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element or a single element. When the value is read, if\nno value is defined it automatically traverses the element's hierarchy of\nparents, through any block elements and up to the form, searching for a\ndefined value.\n\nIs an L\u003cinheriting accessor|/INHERITING ACCESSORS\u003e.\n\n=head1 PROCESSING A FORM\n\n=head2 query\n\nArguments: [$query_object]\n\nArguments: \\%params\n\nProvide a L\u003cCGI\u003e compatible query object or a hash-ref of submitted\nnames/values. Alternatively, the query object can be passed directly to the\nL\u003c/process\u003e object.\n\n=head2 query_type\n\nArguments: [$query_type]\n\nSet which module is being used to provide the L\u003c/query\u003e.\n\nThe L\u003cCatalyst::Controller::HTML::FormFu\u003e automatically sets this to\nC\u003cCatalyst\u003e.\n\nValid values are C\u003cCGI\u003e, C\u003cCatalyst\u003e and C\u003cCGI::Simple\u003e.\n\nDefault Value: 'CGI'\n\n=head2 process\n\nArguments: [$query_object]\n\nArguments: [\\%params]\n\nProcess the provided query object or input values. C\u003cprocess\u003e must be called\nbefore calling any of the methods listed under\nL\u003c/\"SUBMITTED FORM VALUES AND ERRORS\"\u003e and L\u003c/\"MODIFYING A SUBMITTED FORM\"\u003e.\n\nC\u003cprocess\u003e must also be called at least once before printing the form or\ncalling L\u003c/render\u003e or L\u003c/render_data\u003e.\n\nNote to users of L\u003cCatalyst::Controller::HTML::FormFu\u003e: Because L\u003c/process\u003e\nis automatically called for you by the Catalyst controller; if you make any\nmodifications to the form within your action method, such as adding or changing\nelements, adding constraints, etc; you must call L\u003c/process\u003e again yourself\nbefore using L\u003c/submitted_and_valid\u003e, any of the methods listed under\nL\u003c/\"SUBMITTED FORM VALUES AND ERRORS\"\u003e or\nL\u003c/\"MODIFYING A SUBMITTED FORM\"\u003e, or rendering the form.\n\n=head1 SUBMITTED FORM VALUES AND ERRORS\n\n=head2 submitted\n\nReturns true if the form has been submitted. See L\u003c/indicator\u003e for details\non how this is computed.\n\n=head2 submitted_and_valid\n\nShorthand for C\u003c\u003c $form-\u003esubmitted \u0026\u0026 !$form-\u003ehas_errors \u003e\u003e\n\n=head2 params\n\nReturn Value: \\%params\n\nReturns a hash-ref of all valid input for which there were no errors.\n\n=head2 param_value\n\nArguments: $field_name\n\nA more reliable, recommended version of L\u003c/param\u003e. Guaranteed to always return a\nsingle value, regardless of whether it's called in list context or not. If\nmultiple values were submitted, this only returns the first value. If the value\nis invalid or the form was not submitted, it returns C\u003cundef\u003e. This makes it\nsuitable for use in list context, where a single value is required.\n\n    $db-\u003eupdate({\n        name    =\u003e $form-\u003eparam_value('name'),\n        address =\u003e $form-\u003eparam_value('address),\n    });\n\n=head2 param_array\n\nArguments: $field_name\n\nGuaranteed to always return an array-ref of values, regardless of context and\nregardless of whether multiple values were submitted or not. If the value is\ninvalid or the form was not submitted, it returns an empty array-ref.\n\n=head2 param_list\n\nArguments: $field_name\n\nGuaranteed to always return a list of values, regardless of context. If the value is\ninvalid or the form was not submitted, it returns an empty list.\n\n=head2 param\n\nArguments: [$field_name]\n\nReturn Value: $input_value\n\nReturn Value: @valid_names\n\nNo longer recommended for use, as its behaviour is hard to predict. Use\nL\u003c/param_value\u003e, L\u003c/param_array\u003e or L\u003c/param_list\u003e instead.\n\nA (readonly) method similar to that of L\u003cCGI's|CGI\u003e.\n\nIf a field name is given, in list-context returns any valid values submitted\nfor that field, and in scalar-context returns only the first of any valid\nvalues submitted for that field.\n\nIf no argument is given, returns a list of all valid input field names\nwithout errors.\n\nPassing more than 1 argument is a fatal error.\n\n=head2 valid\n\nArguments: [$field_name]\n\nReturn Value: @valid_names\n\nReturn Value: $bool\n\nIf a field name if given, returns C\u003ctrue\u003e if that field had no errors and\nC\u003cfalse\u003e if there were errors.\n\nIf no argument is given, returns a list of all valid input field names\nwithout errors.\n\n=head2 has_errors\n\nArguments: [$field_name]\n\nReturn Value: @names\n\nReturn Value: $bool\n\nIf a field name if given, returns C\u003ctrue\u003e if that field had errors and\nC\u003cfalse\u003e if there were no errors.\n\nIf no argument is given, returns a list of all input field names with errors.\n\n=head2 get_errors\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@errors\n\nReturns an array-ref of exception objects from all fields in the form.\n\nAccepts both C\u003cname\u003e, C\u003ctype\u003e and C\u003cstage\u003e arguments to narrow the returned\nresults.\n\n    $form-\u003eget_errors({\n        name  =\u003e 'foo',\n        type  =\u003e 'Regex',\n        stage =\u003e 'constraint'\n    });\n\n=head2 get_error\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $error\n\nAccepts the same arguments as L\u003c/get_errors\u003e, but only returns the first\nerror found.\n\n=head1 MODEL / DATABASE INTERACTION\n\nSee L\u003cHTML::FormFu::Model\u003e for further details and available models.\n\n=head2 default_model\n\nArguments: $model_name\n\nDefault Value: 'DBIC'\n\n=head2 model\n\nArguments: [$model_name]\n\nReturn Value: $model\n\n=head2 model_config\n\nArguments: \\%config\n\n=head1 MODIFYING A SUBMITTED FORM\n\n=head2 add_valid\n\nArguments: $name, $value\n\nReturn Value: $value\n\nThe provided value replaces any current value for the named field. This\nvalue will be returned in subsequent calls to L\u003c/params\u003e and L\u003c/param\u003e and\nthe named field will be included in calculations for L\u003c/valid\u003e.\n\n=head2 clear_errors\n\nDeletes all errors from a submitted form.\n\n=head1 RENDERING A FORM\n\n=head2 render\n\nReturn Value: $string\n\nYou must call L\u003c/process\u003e once after building the form, and before calling\nL\u003c/render\u003e.\n\n=head2 start\n\nReturn Value: $string\n\nReturns the form start tag, and any output of L\u003c/form_error_message\u003e and\nL\u003c/javascript\u003e.\n\n=head2 end\n\nReturn Value: $string\n\nReturns the form end tag.\n\n=head2 hidden_fields\n\nReturn Value: $string\n\nReturns all hidden form fields.\n\n=head1 PLUGIN SYSTEM\n\nC\u003cHTML::FormFu\u003e provides a plugin-system that allows plugins to be easily\nadded to a form or element, to change the default behaviour or output.\n\nSee L\u003cHTML::FormFu::Plugin\u003e for details.\n\n=head1 ADVANCED CUSTOMISATION\n\nBy default, formfu renders \"XHTML 1.0 Strict\" compliant markup, with as\nlittle extra markup as possible. Many hooks are provided to add\nprogrammatically-generated CSS class names, to allow for a wide-range of\noutput styles to be generated by changing only the CSS.\n\nBasic customisation of the markup is possible via the\nL\u003clayout|HTML::FormFu::Role::Element::Field/layout\u003e and\nL\u003cmulti_layout|HTML::FormFu::Role::Element::Field/multi_layout\u003e methods.\nThis allows you to reorder the position of various parts of each field -\nsuch as the label, comment, error messages and the input tag - as well\nas inserting any other arbitrary tags you may wish.\n\nIf this is not sufficient, you can make completely personalise the markup\nby telling HTML::FormFu to use an external rendering engine, such as\nL\u003cTemplate Toolkit|Template\u003e or L\u003cTemplate::Alloy\u003e.\nSee L\u003c/render_method\u003e and L\u003c/tt_module\u003e for details.\n\nEven if you set HTML::FormFu to use L\u003cTemplate::Toolkit|Template\u003e to render,\nthe forms, HTML::FormFu can still be used in conjunction with whichever other\ntemplating system you prefer to use for your own page layouts, whether it's\nL\u003cHTML::Template\u003e: C\u003c\u003c \u003cTMPL_VAR form\u003e \u003e\u003e,\nL\u003cPetal\u003e: C\u003c\u003c \u003cform tal:replace=\"form\"\u003e\u003c/form\u003e \u003e\u003e\nor L\u003cTemplate::Magic\u003e: C\u003c\u003c \u003c!-- {form} --\u003e \u003e\u003e.\n\nAs of C\u003cHTML::FormFu v1.00\u003e, L\u003cTT|Template\u003e is no longer listed a required\nprerequisite - so you'll need to install it manually if you wish to use the\ntemplate files.\n\n=head2 render_method\n\nDefault Value: C\u003cstring\u003e\n\nCan be set to C\u003ctt\u003e to generate the form with external template files.\n\nTo customise the markup, you'll need a copy of the template files, local to\nyour application. See\nL\u003cHTML::FormFu::Manual::Cookbook/\"Installing the TT templates\"\u003e for further\ndetails.\n\nYou can customise the markup for a single element by setting that element's\nL\u003c/render_method\u003e to C\u003ctt\u003e, while the rest of the form uses the default\nC\u003cstring\u003e render-method. Note though, that if you try setting the form or a\nBlock's L\u003c/render_method\u003e to C\u003ctt\u003e, and then set a child element's\nL\u003c/render_method\u003e to C\u003cstring\u003e, that setting will be ignored, and the child\nelements will still use the C\u003ctt\u003e render-method.\n\n    ---\n    elements:\n      - name: foo\n        render_method: tt\n        filename: custom_field\n\n      - name: bar\n\n    # in this example, 'foo' will use a custom template,\n    # while bar will use the default 'string' rendering method\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element or a single element. When the value is read, if\nno value is defined it automatically traverses the element's hierarchy of\nparents, through any block elements and up to the form, searching for a\ndefined value.\n\nIs an L\u003cinheriting accessor|/INHERITING ACCESSORS\u003e.\n\n=head2 filename\n\nChange the template filename used for the form.\n\nDefault Value: \"form\"\n\n=head2 tt_args\n\nArguments: [\\%constructor_arguments]\n\nAccepts a hash-ref of arguments passed to L\u003c/render_method\u003e, which is called\ninternally by L\u003c/render\u003e.\n\nWithin tt_args, the keys C\u003cRELATIVE\u003e and C\u003cRECURSION\u003e are overridden to always\nbe true, as these are a basic requirement for the L\u003cTemplate\u003e engine.\n\nThe system directory containing HTML::FormFu's template files is always\nadded to the end of C\u003cINCLUDE_PATH\u003e, so that the core template files will be\nfound. You only need to set this yourself if you have your own copy of the\ntemplate files for customisation purposes.\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element or a single element. When the value is read, if\nno value is defined it automatically traverses the element's hierarchy of\nparents, through any block elements and up to the form, searching for a\ndefined value.\n\n=head2 add_tt_args\n\nArguments: [\\%constructor_arguments]\n\nEnsures that the hash-ref argument is merged with any existing hash-ref\nvalue of L\u003c/tt_args\u003e.\n\n=head2 tt_module\n\nDefault Value: Template\n\nThe module used when L\u003c/render_method\u003e is set to C\u003ctt\u003e. Should provide an\ninterface compatible with L\u003cTemplate\u003e.\n\nThis method is a special 'inherited accessor', which means it can be set on\nthe form, a block element or a single element. When the value is read, if\nno value is defined it automatically traverses the element's hierarchy of\nparents, through any block elements and up to the form, searching for a\ndefined value.\n\n=head2 render_data\n\nUsually called implicitly by L\u003c/render\u003e. Returns the data structure that\nwould normally be passed onto the C\u003cstring\u003e or C\u003ctt\u003e render-methods.\n\nAs with L\u003c/render\u003e, you must call L\u003c/process\u003e once after building the form,\nand before calling L\u003c/render_data\u003e.\n\n=head2 render_data_non_recursive\n\nLike L\u003c/render_data\u003e, but doesn't include the data for any child-elements.\n\n=head1 INTROSPECTION\n\n=head2 get_fields\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@elements\n\nReturns all fields in the form (specifically, all elements which have a true\nL\u003cHTML::FormFu::Element/is_field\u003e value).\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_fields({\n        name =\u003e 'foo',\n        type =\u003e 'Radio',\n    });\n\nAccepts also an Regexp to search for results.\n\n    $form-\u003eget_elements({\n        name =\u003e qr/oo/,\n    });\n\n=head2 get_field\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $element\n\nAccepts the same arguments as L\u003c/get_fields\u003e, but only returns the first\nfield found.\n\n=head2 get_elements\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@elements\n\nReturns all top-level elements in the form (not recursive).\nSee L\u003c/get_all_elements\u003e for a recursive version.\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_elements({\n        name =\u003e 'foo',\n        type =\u003e 'Radio',\n    });\n\nAccepts also an Regexp to search for results.\n\n    $form-\u003eget_elements({\n        name =\u003e qr/oo/,\n    });\n\n=head2 get_element\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $element\n\nAccepts the same arguments as L\u003c/get_elements\u003e, but only returns the first\nelement found.\n\nSee L\u003c/get_all_element\u003e for a recursive version.\n\n=head2 get_all_elements\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@elements\n\nReturns all elements in the form recursively.\n\nOptionally accepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned\nresults.\n\n    # return all Text elements\n\n    $form-\u003eget_all_elements({\n        type =\u003e 'Text',\n    });\n\nAccepts also an Regexp to search for results.\n\n    $form-\u003eget_elements({\n        name =\u003e qr/oo/,\n    });\n\nSee L\u003c/get_elements\u003e for a non-recursive version.\n\n=head2 get_all_element\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $element\n\nAccepts the same arguments as L\u003c/get_all_elements\u003e, but only returns the\nfirst element found.\n\n    # return the first Text field found, regardless of whether it's\n    # within a fieldset or not\n\n    $form-\u003eget_all_element({\n        type =\u003e 'Text',\n    });\n\nAccepts also an Regexp to search for results.\n\n    $form-\u003eget_elements({\n        name =\u003e qr/oo/,\n    });\n\nSee L\u003c/get_all_elements\u003e for a non-recursive version.\n\n=head2 get_deflators\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@deflators\n\nReturns all top-level deflators from all fields.\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_deflators({\n        name =\u003e 'foo',\n        type =\u003e 'Strftime',\n    });\n\n=head2 get_deflator\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $element\n\nAccepts the same arguments as L\u003c/get_deflators\u003e, but only returns the first\ndeflator found.\n\n=head2 get_filters\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@filters\n\nReturns all top-level filters from all fields.\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_filters({\n        name =\u003e 'foo',\n        type =\u003e 'LowerCase',\n    });\n\n=head2 get_filter\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $filter\n\nAccepts the same arguments as L\u003c/get_filters\u003e, but only returns the first\nfilter found.\n\n=head2 get_constraints\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@constraints\n\nReturns all constraints from all fields.\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_constraints({\n        name =\u003e 'foo',\n        type =\u003e 'Equal',\n    });\n\n=head2 get_constraint\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $constraint\n\nAccepts the same arguments as L\u003c/get_constraints\u003e, but only returns the\nfirst constraint found.\n\n=head2 get_inflators\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@inflators\n\nReturns all inflators from all fields.\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_inflators({\n        name =\u003e 'foo',\n        type =\u003e 'DateTime',\n    });\n\n=head2 get_inflator\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $inflator\n\nAccepts the same arguments as L\u003c/get_inflators\u003e, but only returns the\nfirst inflator found.\n\n=head2 get_validators\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@validators\n\nReturns all validators from all fields.\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_validators({\n        name =\u003e 'foo',\n        type =\u003e 'Callback',\n    });\n\n=head2 get_validator\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $validator\n\nAccepts the same arguments as L\u003c/get_validators\u003e, but only returns the\nfirst validator found.\n\n=head2 get_transformers\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: \\@transformers\n\nReturns all transformers from all fields.\n\nAccepts both C\u003cname\u003e and C\u003ctype\u003e arguments to narrow the returned results.\n\n    $form-\u003eget_transformers({\n        name =\u003e 'foo',\n        type =\u003e 'Callback',\n    });\n\n=head2 get_transformer\n\nArguments: [%options]\n\nArguments: [\\%options]\n\nReturn Value: $transformer\n\nAccepts the same arguments as L\u003c/get_transformers\u003e, but only returns the\nfirst transformer found.\n\n=head2 clone\n\nReturns a deep clone of the C\u003c$form\u003e object.\n\nBecause of scoping issues, code references (such as in Callback constraints)\nare copied instead of cloned.\n\n=head1 ATTRIBUTE ACCESSORS\n\nFor the basic method, e.g. C\u003c/attributes\u003e:\n\nArguments: [%attributes]\n\nArguments: [\\%attributes]\n\nReturn Value: $form\n\nAs a special case, if no arguments are passed, the attributes hash-ref is\nreturned. This allows the following idioms.\n\n    # set a value\n    $form-\u003eattributes-\u003e{id} = 'form';\n\n    # delete all attributes\n    %{ $form-\u003eattributes } = ();\n\nAll methods documented as 'attribute accessors' also have the following\nvariants generated:\n\nC\u003c*_xml\u003e can be used as a setter, and ensures that its argument is not\nXML-escaped in the rendered form.\n\nC\u003c*_loc\u003e can he used as a setter, and passes the arguments through\nL\u003c/localize\u003e.\n\nC\u003cadd_*\u003e can be used to append a word to an attribute without overwriting\nany already-existing value.\n\n    # Example\n    $form-\u003eattributes({ class =\u003e 'fancy' });\n    $form-\u003eadd_attributes({ class =\u003e 'pants' });\n    # class=\"fancy pants\"\n\nC\u003cadd_*_xml\u003e, like C\u003cadd_*\u003e, but ensures it doesn't get XML-escaped.\n\nC\u003cadd_*_loc\u003e, like C\u003cadd_*\u003e, but passing the arguments through L\u003c/localize\u003e.\n\nC\u003cdel_*\u003e can be used to remove a word from an attribute value.\n\n    # Example\n    $form-\u003eattributes({ class =\u003e 'fancy pants' });\n    $form-\u003edel_attributes({ class =\u003e 'pants' });\n    # class=\"fancy\"\n\nC\u003cdel_*_xml\u003e, like C\u003cdel_*\u003e, but ensures it doesn't get XML-escaped.\n\nC\u003cdel_*_loc\u003e, like C\u003cdel_*\u003e, but passing the arguments through L\u003c/localize\u003e.\n\nAlso, any attribute method-name which contains the word C\u003cattributes\u003e also\nhas aliases created for all these variants, with the word C\u003cattributes\u003e\nreplaced by C\u003cattrs\u003e.\n\n    # For example, the attributes() method would have all these variant\n    # methods available\n\n    $form-\u003eattributes({ class =\u003e 'fancy' });\n    $form-\u003eattributes_xml({ title =\u003e '\u003cb\u003efancy\u003c/b\u003e' });\n    $form-\u003eattributes_loc({ title =\u003e 'fancy' });\n    $form-\u003eadd_attributes({ class =\u003e 'fancy' });\n    $form-\u003eadd_attributes_xml({ title =\u003e '\u003cb\u003efancy\u003c/b\u003e' });\n    $form-\u003eadd_attributes_loc({ title =\u003e 'fancy' });\n    $form-\u003edel_attributes({ class =\u003e 'fancy' });\n    $form-\u003edel_attributes_xml({ title =\u003e '\u003cb\u003efancy\u003c/b\u003e' });\n    $form-\u003edel_attributes_loc({ title =\u003e 'fancy' });\n\n    # Because the method contains the word 'attributes', it also gets the\n    # following short-forms\n\n    $form-\u003eattrs({ class =\u003e 'fancy' });\n    $form-\u003eattrs_xml({ title =\u003e '\u003cb\u003efancy\u003c/b\u003e' });\n    $form-\u003eattrs_loc({ title =\u003e 'fancy' });\n    $form-\u003eadd_attrs({ class =\u003e 'fancy' });\n    $form-\u003eadd_attrs_xml({ title =\u003e '\u003cb\u003efancy\u003c/b\u003e' });\n    $form-\u003eadd_attrs_loc({ title =\u003e 'fancy' });\n    $form-\u003edel_attrs({ class =\u003e 'fancy' });\n    $form-\u003edel_attrs_xml({ title =\u003e '\u003cb\u003efancy\u003c/b\u003e' });\n    $form-\u003edel_attrs_loc({ title =\u003e 'fancy' });\n\n=head1 ATTRIBUTE SHORT-CUTS\n\nAll methods documented as 'attribute short-cuts' are short-cuts to directly\naccess individual attribute key/values.\n\n    # Example\n    $form-\u003eid( 'login' );\n    $id = $form-\u003eid;\n\n    # is equivalent to:\n    $form-\u003eattributes({ id =\u003e 'login' });\n    $id = $form-\u003eattributes-\u003e{id};\n\nAll attribute short-cuts also have a C\u003c*_xml\u003e variant.\n\n    # Example\n    $form-\u003eid_xml( $xml );\n\n    # is equivalent to:\n    $form-\u003eattributes_xml({ id =\u003e $xml });\n\nAll attribute short-cuts also have a C\u003c*_loc\u003e variant.\n\n    # Example\n    $form-\u003etitle_loc( $key );\n\n    # is equivalent to:\n    $form-\u003eattributes_loc({ title =\u003e $key });\n\n=head1 INHERITING ACCESSORS\n\nAll methods documented as 'inheriting accessors' can be set on the form,\na block element or a single field element.\nWhen the value is read, if no value is defined it automatically traverses\nthe element's hierarchy of parents, searching for a defined value.\n\nAll inherited accessors also have a C\u003c*_no_inherit\u003e variant, which can be\nused as a getter to fetch any defined value, without traversing the\nhierarchy of parents. This variant cannot be used as a setter.\n\nE.g., the L\u003c/auto_id\u003e has a variant named C\u003cauto_id_no_inherit\u003e.\n\n=head1 OUTPUT ACCESSORS\n\nAll methods documented as 'output accessors' also have C\u003c*_xml\u003e and C\u003c*_loc\u003e\nvariants.\n\nThe C\u003c*_xml\u003e variant can be used as a setter, and ensures that its\nargument is not XML-escaped in the rendered form.\n\nThe C\u003c*_loc\u003e variant can be used as a setter, and passes the arguments\nthrough L\u003c/localize\u003e.\n\nE.g., the L\u003clabel|HTML::FormFu::Role::Element::Field/label\u003e method has\nvariants named C\u003clabel_xml\u003e and C\u003clabel_loc\u003e.\n\n=head1 BOOLEAN ATTRIBUTE ACCESSORS\n\nTo support boolean attributes, whose value should either be equal to the\nattribute name, or empty. Any true value will switch the attribute 'on', any\nfalse value will remove the attribute.\n\n    # Example\n\n    $field-\u003eautofocus(1);\n    # equivalent to:\n    $field-\u003eattributes({ autofocus =\u003e 'autofocus' });\n\n    $field-\u003eautofocus(0);;\n    # equivalent to:\n    delete $field-\u003eattributes-\u003e{autofocus};\n\n=head1 ATTRIBUTE SUBSTITUTIONS\n\nSome attributes support character substitutions: the following substitutions\nare possible:\n\n    %f # $form-\u003eid\n    %n # $field-\u003ename\n    %t # lc( $field-\u003etype )\n    %r # $block-\u003erepeatable_count\n    %s # $error-\u003estage\n\nThese allow each field to have consistent attributes, while remaining unique.\n\n=head1 DEPRECATION POLICY\n\nWe try our best to not make incompatible changes, but if they're required\nwe'll make every effort possible to provide backwards compatibility for\nseveral release-cycles, issuing a warnings about the changes, before removing\nthe legacy features.\n\n=head1 RESTORING LEGACY HTML CLASSES\n\nC\u003cv1.00\u003e dropped most of the default HTML class-names, with the intention\nthat each application should define just what it needs, without needing to\nreset unwanted options first. We also gain the benefit of less markup being\ngenerated, speeding up both L\u003crender|/render\u003e and HTTP transfers.\n\nTo restore the previous behaviour, set the following options.\n\nIf you're using L\u003cbest practices|/\"BEST PRACTICES\"\u003e, you'll only need to set\nthese once per-application in your app-wide config file.\n\n    ---\n    auto_container_class: '%t'\n    auto_container_label_class: 'label'\n    auto_container_comment_class: 'comment'\n    auto_comment_class: 'comment'\n    auto_container_error_class: 'error'\n    auto_container_per_error_class: 'error_%s_%t'\n    auto_error_class: 'error_message error_%s_%t'\n\n=head1 DEPRECATED METHODS\n\nSee L\u003cHTML::FormFu::Role::Element::Field/\"DEPRECATED METHODS\"\u003e.\n\n=head1 REMOVED METHODS\n\nSee also L\u003cHTML::FormFu::Element/\"REMOVED METHODS\"\u003e.\n\n=head2 element_defaults\n\nHas been removed; see L\u003c/default_args\u003e instead.\n\n=head2 model_class\n\nHas been removed; use L\u003c/default_model\u003e instead.\n\n=head2 defaults_from_model\n\nHas been removed; use L\u003cHTML::FormFu::Model/default_values\u003e instead.\n\n=head2 save_to_model\n\nHas been removed; use L\u003cHTML::FormFu::Model/update\u003e instead.\n\n=head1 BEST PRACTICES\n\nIt is advisable to keep application-wide (or global) settings in a single\nconfig file, which should be loaded by each form.\n\nSee L\u003c/load_config_file\u003e.\n\n=head1 COOKBOOK\n\nL\u003cHTML::FormFu::Manual::Cookbook\u003e\n\n=head2 UNICODE\n\nL\u003cHTML::FormFu::Manual::Unicode\u003e\n\n=head1 EXAMPLES\n\n=head2 vertically-aligned CSS\n\nThe distribution directory C\u003cexamples/vertically-aligned\u003e contains a form with\nexample CSS for a \"vertically aligned\" theme.\n\nThis can be viewed by opening the file C\u003cvertically-aligned.html\u003e in a\nweb-browser.\n\nIf you wish to experiment with making changes, the form is defined in file\nC\u003cvertically-aligned.yml\u003e, and the HTML file can be updated with any changes\nby running the following command (while in the distribution root directory).\n\n    perl examples/vertically-aligned/vertically-aligned.pl\n\nThis uses the L\u003cTemplate Toolkit|Template\u003e file C\u003cvertically-aligned.tt\u003e,\nand the CSS is defined in files C\u003cvertically-aligned.css\u003e and\nC\u003cvertically-aligned-ie.css\u003e.\n\n=head1 SEE ALSO\n\nL\u003cHTML::FormFu::Imager\u003e\n\nL\u003cCatalyst::Controller::HTML::FormFu\u003e\n\nL\u003cHTML::FormFu::Model::DBIC\u003e\n\n=head1 CONTRIBUTORS\n\nBrian Cassidy\n\nOzum Eldogan\n\nRuben Fonseca\n\nRonald Kimball\n\nDaisuke Maki\n\nAndreas Marienborg\n\nMario Minati\n\nSteve Nolte\n\nMoritz Onken\n\nDoug Orleans\n\nMatthias Dietrich\n\nDean Hamstead\n\nKaren Etheridge\n\nNigel Metheringham\n\nBased on the original source code of L\u003cHTML::Widget\u003e, by Sebastian Riedel,\nC\u003csri@oook.de\u003e.\n\n=head1 AUTHOR\n\nCarl Franks \u003ccpan@fireartist.com\u003e\n\n=head1 COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2018 by Carl Franks.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n\n=cut\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fformfu%2Fhtml-formfu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fformfu%2Fhtml-formfu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fformfu%2Fhtml-formfu/lists"}