{
    "content": [
        {
            "type": "text",
            "text": "# CGI::FormBuilder::Field (perldoc)\n\n## NAME\n\nCGI::FormBuilder::Field - Base class for FormBuilder fields\n\n## SYNOPSIS\n\nuse CGI::FormBuilder::Field;\n# delegated straight from FormBuilder\nmy $f = CGI::FormBuilder::Field->new($form, name => 'whatever');\n# attribute functions\nmy $n = $f->name;         # name of field\nmy $n = \"$f\";             # stringify to $f->name\nmy $t = $f->type;         # auto-type\nmy @v = $f->value;        # auto-stickiness\nmy @o = $f->options;      # options, aligned and sorted\nmy $l = $f->label;        # auto-label\nmy $h = $f->tag;          # field XHTML tag (name/type/value)\nmy $s = $f->script;       # per-field JS validation script\nmy $m = $f->message;      # error message if invalid\nmy $m = $f->jsmessage;    # JavaScript error message\nmy $r = $f->required;     # required?\nmy $k = $f->validate;     # run validation check\nmy $v = $f->tagvalue;    # value in tag (stickiness handling)\nmy $v = $f->cgivalue;    # CGI value if any\nmy $v = $f->defvalue;    # manually-specified value\n$f->field(opt => 'val');  # FormBuilder field() call\n\n## DESCRIPTION\n\nThis module is internally used by FormBuilder to create and maintain field information. Usually,\nyou will not want to directly access this set of data structures. However, one big exception is\nif you are going to micro-control form rendering. In this case, you will need to access the\nfield objects directly.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **METHODS**\n- **SEE ALSO**\n- **REVISION**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "CGI::FormBuilder::Field",
        "section": "",
        "mode": "perldoc",
        "summary": "CGI::FormBuilder::Field - Base class for FormBuilder fields",
        "synopsis": "use CGI::FormBuilder::Field;\n# delegated straight from FormBuilder\nmy $f = CGI::FormBuilder::Field->new($form, name => 'whatever');\n# attribute functions\nmy $n = $f->name;         # name of field\nmy $n = \"$f\";             # stringify to $f->name\nmy $t = $f->type;         # auto-type\nmy @v = $f->value;        # auto-stickiness\nmy @o = $f->options;      # options, aligned and sorted\nmy $l = $f->label;        # auto-label\nmy $h = $f->tag;          # field XHTML tag (name/type/value)\nmy $s = $f->script;       # per-field JS validation script\nmy $m = $f->message;      # error message if invalid\nmy $m = $f->jsmessage;    # JavaScript error message\nmy $r = $f->required;     # required?\nmy $k = $f->validate;     # run validation check\nmy $v = $f->tagvalue;    # value in tag (stickiness handling)\nmy $v = $f->cgivalue;    # CGI value if any\nmy $v = $f->defvalue;    # manually-specified value\n$f->field(opt => 'val');  # FormBuilder field() call",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 29,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 33,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 105,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "REVISION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 5,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "CGI::FormBuilder::Field - Base class for FormBuilder fields\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use CGI::FormBuilder::Field;\n\n# delegated straight from FormBuilder\nmy $f = CGI::FormBuilder::Field->new($form, name => 'whatever');\n\n# attribute functions\nmy $n = $f->name;         # name of field\nmy $n = \"$f\";             # stringify to $f->name\n\nmy $t = $f->type;         # auto-type\nmy @v = $f->value;        # auto-stickiness\nmy @o = $f->options;      # options, aligned and sorted\n\nmy $l = $f->label;        # auto-label\nmy $h = $f->tag;          # field XHTML tag (name/type/value)\nmy $s = $f->script;       # per-field JS validation script\n\nmy $m = $f->message;      # error message if invalid\nmy $m = $f->jsmessage;    # JavaScript error message\n\nmy $r = $f->required;     # required?\nmy $k = $f->validate;     # run validation check\n\nmy $v = $f->tagvalue;    # value in tag (stickiness handling)\nmy $v = $f->cgivalue;    # CGI value if any\nmy $v = $f->defvalue;    # manually-specified value\n\n$f->field(opt => 'val');  # FormBuilder field() call\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module is internally used by FormBuilder to create and maintain field information. Usually,\nyou will not want to directly access this set of data structures. However, one big exception is\nif you are going to micro-control form rendering. In this case, you will need to access the\nfield objects directly.\n\nTo do so, you will want to loop through the fields in order:\n\nfor my $field ($form->field) {\n\n# $field holds an object stringified to a field name\nif ($field =~ /date$/) {\n$field->sticky(0);  # clear CGI value\nprint \"Enter $field here:\", $field->tag;\n} else {\nprint $field->label, ': ', $field->tag;\n}\n}\n\nAs illustrated, each $field variable actually holds a stringifiable object. This means if you\nprint them out, you will get the field name, allowing you to check for certain fields. However,\nsince it is an object, you can then run accessor methods directly on that object.\n\nThe most useful method is \"tag()\". It generates the HTML input tag for the field, including all\noption and type handling, and returns a string which you can then print out or manipulate\nappropriately.\n\nSecond to this method is the \"script\" method, which returns the appropriate JavaScript\nvalidation routine for that field. This is useful at the top of your form rendering, when you\nare printing out the leading \"<head>\" section of your HTML document. It is called by the $form\nmethod of the same name.\n\nThe following methods are provided for each $field object.\n",
                "subsections": []
            },
            "METHODS": {
                "content": "new($form, %args)\nThis creates a new $field object. The first argument must be a reference to the top-level $form\nobject, for callbacks. The remaining arguments should be hash, of which one \"key/value\" pair\nmust specify the \"name\" of the field. Normally you should not touch this method. Ever.\n\nfield(%args)\nThis is a delegated field call. This is how FormBuilder tweaks its fields. Once you have a\n$field object, you call this method the exact same way that you would call the main \"field()\"\nmethod, minus the field name. Again you should use the top-level call instead.\n\ninflate($subref)\nThis sets the inflate attribute: subroutine reference used to inflate values returned by value()\ninto objects or whatever you want. If no parameter, returns the inflate subroutine reference\nthat is set. For example:\n\nuse DateTime::Format::Strptime;\nmy $dateformat = DateTime::Format::Strptime->new(\npattern   => '%D',    # for MM/DD/YYYY american dates\nlocale    => 'enUS',\ntimezone => 'America/LosAngeles',\n);\n$field->inflate( sub { return $dateformat->formatdatetime(shift) } );\n\ninvalid\nThis returns the opposite value that \"validate()\" would return, with some extra magic that keeps\nstate for form rendering purposes.\n\njsfunc()\nReturns the appropriate JavaScript validation code (see above).\n\nlabel($str)\nThis sets and returns the field's label. If unset, it will be generated from the name of the\nfield.\n\ntag($type)\nReturns an XHTML form input tag (see above). By default it renders the tag based on the type set\nfrom the top-level field method:\n\n$form->field(name => 'poetry', type => 'textarea');\n\nHowever, if you are doing custom rendering you can override this temporarily by passing in the\ntype explicitly. This is usually not useful unless you have a custom rendering module that\nforcibly overrides types for certain fields.\n\ntype($type)\nThis sets and returns the field's type. If unset, it will automatically generate the appropriate\nfield type, depending on the number of options and whether multiple values are allowed:\n\nField options?\nNo = text (done)\nYes:\nLess than 'selectnum' setting?\nNo = select (done)\nYes:\nIs the 'multiple' option set?\nYes = checkbox (done)\nNo:\nHave just one single option?\nYes = checkbox (done)\nNo = radio (done)\n\nFor an example, view the inside guts of this module.\n\nvalidate($pattern)\nThis returns 1 if the field passes the validation pattern(s) and \"required\" status previously\nset via required() and (possibly) the top-level new() call in FormBuilder. Usually running\nper-field validate() calls is not what you want. Instead, you want to run the one on $form,\nwhich in turn calls each individual field's and saves some temp state.\n\nvalue($val)\nThis sets the field's value. It also returns the appropriate value: CGI if set, otherwise the\nmanual default value. Same as using \"field()\" to retrieve values.\n\ntagvalue()\nThis obeys the \"sticky\" flag to give a different interpretation of CGI values. Use this to get\nthe value if generating your own tag. Otherwise, ignore it completely.\n\ncgivalue()\nThis always returns the CGI value, regardless of \"sticky\".\n\ndefvalue()\nThis always returns the default value, regardless of \"sticky\".\n\ntagname()\nThis returns the tag name of the current item. This was added so you could subclass, say,\n\"CGI::FormBuilder::Field::select\" and change the HTML tag to \"<b:select>\" instead. This is an\nexperimental feature and subject to change wildly (suggestions welcome).\n\naccessors\nIn addition to the above methods, accessors are provided for directly manipulating values as if\nfrom a \"field()\" call:\n\nAccessor                Same as...\n----------------------- -----------------------------------\n$f->force(0|1)          $form->field(force => 0|1)\n$f->options(\\@opt)      $form->field(options => \\@opt)\n$f->multiple(0|1)       $form->field(multiple => 0|1)\n$f->message($mesg)      $form->field(message => $mesg)\n$f->jsmessage($mesg)    $form->field(jsmessage => $mesg)\n$f->jsclick($code)      $form->field(jsclick => $code)\n$f->sticky(0|1)         $form->field(sticky => 0|1);\n$f->force(0|1)          $form->field(force => 0|1);\n$f->growable(0|1)       $form->field(growable => 0|1);\n$f->other(0|1)          $form->field(other => 0|1);\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "CGI::FormBuilder\n",
                "subsections": []
            },
            "REVISION": {
                "content": "$Id: Field.pm 100 2007-03-02 18:13:13Z nwiger $\n",
                "subsections": []
            },
            "AUTHOR": {
                "content": "Copyright (c) Nate Wiger <http://nateware.com>. All Rights Reserved.\n\nThis module is free software; you may copy this under the terms of the GNU General Public\nLicense, or the Artistic License, copies of which should have accompanied your Perl kit.\n",
                "subsections": []
            }
        }
    }
}