{
    "content": [
        {
            "type": "text",
            "text": "# CGI::FormBuilder::Multi (perldoc)\n\n## NAME\n\nCGI::FormBuilder::Multi - Create multi-page FormBuilder forms\n\n## SYNOPSIS\n\nuse CGI::FormBuilder::Multi;\nuse CGI::Session;   # or something similar\n# Top-level \"meta-form\"\nmy $multi = CGI::FormBuilder::Multi->new(\n# form 1 options\n{ fields   => [qw(name email daytimephone eveningphone)],\ntitle    => 'Basic Info',\ntemplate => 'page1.tmpl',\nvalidate => { name => 'NAME', email => 'EMAIL' },\nrequired => [qw(name email daytimephone)],\n},\n# form 2 options\n{ fields   => [qw(billingname billingcard billingexp\nbillingaddress billingcity billingstate\nbillingzip billingphone)],\ntitle    => 'Billing',\ntemplate => 'page2.tmpl',\nrequired => 'ALL',\n},\n# form 3 options\n{ fields   => [qw(sameasbilling shippingaddress\nshippingcity shippingstate shippingzip)],\ntitle    => 'Shipping',\ntemplate => 'page3.tmpl',\nrequired => 'ALL',\n},\n# a couple options specific to this module\nnavbar => 1,\n# remaining options (not in hashrefs) apply to all forms\nheader => 1,\nmethod => 'POST',\nsubmit => 'Continue',\nvalues => $dbihashrefquery,\n);\n# Get current page's form\nmy $form = $multi->form;\nif ($form->submitted && $form->validate) {\n# Retrieve session id\nmy $sid = $form->sessionid;\n# Initialize session\nmy $session = CGI::Session->new(\"driver:File\", $sid, {Directory=>'/tmp'});\n# Automatically store updated data in session\n$session->saveparam($form);\n# last page?\nif ($multi->page == $multi->pages) {\nprint $form->confirm;\nexit;\n}\n# Still here, goto next page\n$multi->page++;\n# And re-get form (no \"my\" on $form!)\n$form = $multi->form;\n# Make sure it has the right sessionid\n$form->sessionid($session->id);\n# on page 3 we have special field handling\nif ($multi->page == 3) {\n$form->field(name    => 'sameasbilling',\ntype    => 'checkbox',\noptions => 'Yes',\njsclick => 'this.form.submit()');\n}\n}\n# Fall through and print next page's form\nprint $form->render;\n\n## DESCRIPTION\n\nThis module works with \"CGI::FormBuilder\" to create multi-page forms. Each form is specified\nusing the same options you would pass directly into FormBuilder. See CGI::FormBuilder for a list\nof these options.\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::Multi",
        "section": "",
        "mode": "perldoc",
        "summary": "CGI::FormBuilder::Multi - Create multi-page FormBuilder forms",
        "synopsis": "use CGI::FormBuilder::Multi;\nuse CGI::Session;   # or something similar\n# Top-level \"meta-form\"\nmy $multi = CGI::FormBuilder::Multi->new(\n# form 1 options\n{ fields   => [qw(name email daytimephone eveningphone)],\ntitle    => 'Basic Info',\ntemplate => 'page1.tmpl',\nvalidate => { name => 'NAME', email => 'EMAIL' },\nrequired => [qw(name email daytimephone)],\n},\n# form 2 options\n{ fields   => [qw(billingname billingcard billingexp\nbillingaddress billingcity billingstate\nbillingzip billingphone)],\ntitle    => 'Billing',\ntemplate => 'page2.tmpl',\nrequired => 'ALL',\n},\n# form 3 options\n{ fields   => [qw(sameasbilling shippingaddress\nshippingcity shippingstate shippingzip)],\ntitle    => 'Shipping',\ntemplate => 'page3.tmpl',\nrequired => 'ALL',\n},\n# a couple options specific to this module\nnavbar => 1,\n# remaining options (not in hashrefs) apply to all forms\nheader => 1,\nmethod => 'POST',\nsubmit => 'Continue',\nvalues => $dbihashrefquery,\n);\n# Get current page's form\nmy $form = $multi->form;\nif ($form->submitted && $form->validate) {\n# Retrieve session id\nmy $sid = $form->sessionid;\n# Initialize session\nmy $session = CGI::Session->new(\"driver:File\", $sid, {Directory=>'/tmp'});\n# Automatically store updated data in session\n$session->saveparam($form);\n# last page?\nif ($multi->page == $multi->pages) {\nprint $form->confirm;\nexit;\n}\n# Still here, goto next page\n$multi->page++;\n# And re-get form (no \"my\" on $form!)\n$form = $multi->form;\n# Make sure it has the right sessionid\n$form->sessionid($session->id);\n# on page 3 we have special field handling\nif ($multi->page == 3) {\n$form->field(name    => 'sameasbilling',\ntype    => 'checkbox',\noptions => 'Yes',\njsclick => 'this.form.submit()');\n}\n}\n# Fall through and print next page's form\nprint $form->render;",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 82,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 23,
                "subsections": []
            },
            {
                "name": "METHODS",
                "lines": 72,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "REVISION",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "AUTHOR",
                "lines": 5,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "CGI::FormBuilder::Multi - Create multi-page FormBuilder forms\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use CGI::FormBuilder::Multi;\nuse CGI::Session;   # or something similar\n\n# Top-level \"meta-form\"\nmy $multi = CGI::FormBuilder::Multi->new(\n\n# form 1 options\n{ fields   => [qw(name email daytimephone eveningphone)],\ntitle    => 'Basic Info',\ntemplate => 'page1.tmpl',\nvalidate => { name => 'NAME', email => 'EMAIL' },\nrequired => [qw(name email daytimephone)],\n},\n\n# form 2 options\n{ fields   => [qw(billingname billingcard billingexp\nbillingaddress billingcity billingstate\nbillingzip billingphone)],\ntitle    => 'Billing',\ntemplate => 'page2.tmpl',\nrequired => 'ALL',\n},\n\n# form 3 options\n{ fields   => [qw(sameasbilling shippingaddress\nshippingcity shippingstate shippingzip)],\ntitle    => 'Shipping',\ntemplate => 'page3.tmpl',\nrequired => 'ALL',\n},\n\n# a couple options specific to this module\nnavbar => 1,\n\n# remaining options (not in hashrefs) apply to all forms\nheader => 1,\nmethod => 'POST',\nsubmit => 'Continue',\nvalues => $dbihashrefquery,\n);\n\n# Get current page's form\nmy $form = $multi->form;\n\nif ($form->submitted && $form->validate) {\n\n# Retrieve session id\nmy $sid = $form->sessionid;\n\n# Initialize session\nmy $session = CGI::Session->new(\"driver:File\", $sid, {Directory=>'/tmp'});\n\n# Automatically store updated data in session\n$session->saveparam($form);\n\n# last page?\nif ($multi->page == $multi->pages) {\nprint $form->confirm;\nexit;\n}\n\n# Still here, goto next page\n$multi->page++;\n\n# And re-get form (no \"my\" on $form!)\n$form = $multi->form;\n\n# Make sure it has the right sessionid\n$form->sessionid($session->id);\n\n# on page 3 we have special field handling\nif ($multi->page == 3) {\n$form->field(name    => 'sameasbilling',\ntype    => 'checkbox',\noptions => 'Yes',\njsclick => 'this.form.submit()');\n}\n}\n\n# Fall through and print next page's form\nprint $form->render;\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "This module works with \"CGI::FormBuilder\" to create multi-page forms. Each form is specified\nusing the same options you would pass directly into FormBuilder. See CGI::FormBuilder for a list\nof these options.\n\nThe multi-page \"meta-form\" is a composite of the individual forms you specify, tied together via\nthe special \"page\" CGI param. The current form is available via the \"form()\" method, and the\ncurrent page is available via \"page()\". It's up to you to navigate appropriately:\n\nmy $multi = CGI::FormBuilder::Multi->new(...);\n\n# current form\nmy $form  = $multi->form;\n\n$multi->page++;         # page forward\n$multi->page--;         # and back\n$multi->page = $multi->pages;   # goto last page\n\n# current form\n$form = $multi->form;\n\nTo make things are fluid as possible, you should title each of your forms, even if you're using\na template. This will allow \"::Multi\" to create cross-links by-name instead of just \"Page 2\".\n",
                "subsections": []
            },
            "METHODS": {
                "content": "The following methods are provided:\n\nnew(\\%form1, \\%form2, opt => val)\nThis creates a new \"CGI::FormBuilder::Multi\" object. Forms are specified as hashrefs of options,\nin sequential order, similar to how fields are specified. The order the forms are in is the\norder that the pages will cycle through.\n\nIn addition to a hashref, forms can be directly specified as a $form object that has already\nbeen created. For existing objects, the below does not apply.\n\nWhen the first non-ref argument is seen, then all remaining args are taken as common options\nthat apply to all forms. In this way, you can specify global settings for things like \"method\"\nor \"header\" (which will likely be the same), and then override individual settings like \"fields\"\nand \"validate\" on a per-form basis.\n\nIf you do not wish to specify any options for your forms, you can instead just specify the\n\"pages\" option, for example:\n\nmy $multi = CGI::FormBuilder::Multi->new(pages => 3);\n\nWith this approach, you will have to dynamically assemble each page as you come to them. The\nmailing list can help.\n\nThe \"SYNOPSIS\" above is very representative of typical usage.\n\nform()\nThis returns the current page's form, as an object created directly by \"CGI::FormBuilder->new\".\nAll valid FormBuilder methods and options work on the form. To change which form is returned, us\n\"page()\".\n\npage($num)\nThis sets and returns the current page. It can accept a page number either as an argument, or\ndirectly as an assignment:\n\n$multi->page(1);    # page 1\n$multi->page = 1;   # same thing\n\n$multi->page++;     # next page\n$multi->page--;     # back one\n\nif ($multi->page == $multi->pages) {\n# last page\n}\n\nHint: Usually, you should only change pages once you have validated the current page's form\nappropriately.\n\npages()\nThis returns the total number of pages. Actually, what it returns is an array of all forms (and\nhence it has the alias \"forms()\"), which just so happens to become the length in a scalar\ncontext, just like anywhere else in Perl.\n\nnavbar($onoff)\nThis returns a navigation bar that allows the user to jump between pages of the form. This is\nuseful if you want to let a person fill out different pages out of order. In most cases, you do\n*not* want this, so it's off by default.\n\nTo use it, the best way is setting \"navbar => 1\" in \"new()\". However, you can also get it\nyourself to render your own HTML:\n\nmy $html = $multi->navbar;      # scalar HTML\nmy @link = $multi->navbar;      # array of links\n\nThis is useful in something like this:\n\nmy $nav = $multi->navbar;\n$form = $multi->form;\n$form->tmplparam(navbar => $navbar);\n\nThe navbar will have two style classes: \"fbmultipage\" for the current page's link, and\n\"fbmultilink\" for the others.\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "CGI::FormBuilder\n",
                "subsections": []
            },
            "REVISION": {
                "content": "$Id: Multi.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": []
            }
        }
    }
}