{ "content": [ { "type": "text", "text": "# CGI::FormBuilder::Template::HTML (perldoc)\n\n## NAME\n\nCGI::FormBuilder::Template::HTML - FormBuilder interface to HTML::Template\n\n## SYNOPSIS\n\nmy $form = CGI::FormBuilder->new(\nfields => \\@fields,\ntemplate => 'form.tmpl',\n);\n\n## DESCRIPTION\n\nThis engine adapts FormBuilder to use \"HTML::Template\". \"HTML::Template\" is the default template\noption and is activated one of two ways. Either:\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION**\n- **TEMPLATES**\n- **SEE ALSO**\n- **REVISION**\n- **AUTHOR**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n" } ], "structuredContent": { "command": "CGI::FormBuilder::Template::HTML", "section": "", "mode": "perldoc", "summary": "CGI::FormBuilder::Template::HTML - FormBuilder interface to HTML::Template", "synopsis": "my $form = CGI::FormBuilder->new(\nfields => \\@fields,\ntemplate => 'form.tmpl',\n);", "tldr_summary": null, "tldr_examples": [], "tldr_source": null, "flags": [], "examples": [], "see_also": [], "section_outline": [ { "name": "NAME", "lines": 2, "subsections": [] }, { "name": "SYNOPSIS", "lines": 5, "subsections": [] }, { "name": "DESCRIPTION", "lines": 31, "subsections": [] }, { "name": "TEMPLATES", "lines": 194, "subsections": [] }, { "name": "SEE ALSO", "lines": 2, "subsections": [] }, { "name": "REVISION", "lines": 2, "subsections": [] }, { "name": "AUTHOR", "lines": 5, "subsections": [] } ], "sections": { "NAME": { "content": "CGI::FormBuilder::Template::HTML - FormBuilder interface to HTML::Template\n", "subsections": [] }, "SYNOPSIS": { "content": "my $form = CGI::FormBuilder->new(\nfields => \\@fields,\ntemplate => 'form.tmpl',\n);\n", "subsections": [] }, "DESCRIPTION": { "content": "This engine adapts FormBuilder to use \"HTML::Template\". \"HTML::Template\" is the default template\noption and is activated one of two ways. Either:\n\nmy $form = CGI::FormBuilder->new(\nfields => \\@fields,\ntemplate => 'form.tmpl',\n);\n\nOr, you can specify any options which \"HTML::Template->new\" accepts by using a hashref:\n\nmy $form = CGI::FormBuilder->new(\nfields => \\@fields,\ntemplate => {\ntype => 'HTML',\nfilename => 'form.tmpl',\nsharedcache => 1,\nloopcontextvars => 1\n}\n);\n\nThe following methods are provided (usually only used internally):\n\nengine\nReturns a reference to the \"HTML::Template\" object\n\nprepare\nReturns a hash of all the fields ready to be rendered.\n\nrender\nUses the prepared hash and expands the template, returning a string of HTML.\n", "subsections": [] }, "TEMPLATES": { "content": "In your template, each of the form fields will correspond directly to a \"\" of the same\nname prefixed with \"field-\" in the template. So, if you defined a field called \"email\", then you\nwould setup a variable called \"\" in your template.\n\nIn addition, there are a couple special fields:\n\n - JavaScript to stick in \n - The of the HTML form\n<tmplvar form-start> - Opening <form> tag and internal fields\n<tmplvar form-submit> - The submit button(s)\n<tmplvar form-reset> - The reset button\n<tmplvar form-end> - Just the closing </form> tag\n\nLet's look at an example \"form.tmpl\" template we could use:\n\n<html>\n<head>\n<title>User Information\n\n\n\n

User Information

\nPlease fill out the following information:\n\n

Your full name: \n

Your email address: \n

Choose a password: \n

Please confirm it: \n

Your home zipcode: \n

\n\n\n\nAs you see, you get a \"\" for each for field you define.\n\nHowever, you may want even more control. That is, maybe you want to specify every nitty-gritty\ndetail of your input fields, and just want this module to take care of the statefulness of the\nvalues. This is no problem, since this module also provides several other \"\" tags as\nwell:\n\n - The value of a given field\n - The human-readable label\n - Any optional comment\n - Error text if validation fails\n - See if the field is required\n\nThis means you could say something like this in your template:\n\n:\n\">\n\n\nAnd FormBuilder would take care of the value stickiness for you, while you have control over the\nspecifics of the \"\" tag. A sample expansion may create HTML like the following:\n\nEmail:\n\nYou must enter a valid value\n\nNote, though, that this will only get the *first* value in the case of a multi-value parameter\n(for example, a multi-select list). To remedy this, if there are multiple values you will also\nget a \"\" prefixed with \"loop-\". So, if you had:\n\nmyapp.cgi?color=gray&color=red&color=blue\n\nThis would give the \"color\" field three values. To create a select list, you would do this in\nyour template:\n\n\n\nWith \"\" tags, each iteration gives you several variables:\n\nInside , this... Gives you this\n--------------------------- -------------------------------\n value of that option\n label for that option\n if selected, the word \"checked\"\n if selected, the word \"selected\"\n\nPlease note that \"\" gives you one of the *options*, not the values. Why? Well,\nif you think about it you'll realize that select lists and radio groups are fundamentally\ndifferent from input boxes in a number of ways. Whereas in input tags you can just have an empty\nvalue, with lists you need to iterate through each option and then decide if it's selected or\nnot.\n\nWhen you need precise control in a template this is all exposed to you; normally FormBuilder\ndoes all this magic for you. If you don't need exact control over your lists, simply use the\n\"\" tag and this will all be done automatically, which I strongly\nrecommend.\n\nBut, let's assume you need exact control over your lists. Here's an example select list\ntemplate:\n\n\n\nThen, your Perl code would fiddle the field as follows:\n\n$form->field(\nname => 'color', nameopts => 1,\noptions => [qw(red green blue yellow black white gray)]\n);\n\nAssuming query string as shown above, the template would then be expanded to something like\nthis:\n\n\n\nNotice that the \"\" tag is expanded to the word \"selected\" when a given option\nis present as a value as well (i.e., via the CGI query). The \"\" tag expands to\neach option in turn, and \"\" is expanded to the label for that value. In this\ncase, since \"nameopts\" was specified to \"field()\", the labels are automatically generated from\nthe options.\n\nLet's look at one last example. Here we want a radio group that allows a person to remove\nthemself from a mailing list. Here's our template:\n\nDo you want to be on our mailing list?\n

\n\n\n\n\n
\n\">\n
\n\nThen, we would twiddle our \"mailopt\" field via \"field()\":\n\n$form->field(\nname => 'mailopt',\noptions => [\n[ 1 => 'Yes, please keep me on it!' ],\n[ 0 => 'No, remove me immediately.' ]\n]\n);\n\nWhen the template is rendered, the result would be something like this:\n\nDo you want to be on our mailing list?\n

\n\n\n\n\n\n\n\n
\n\nYes, please keep me on it!\n\nNo, remove me immediately
\n\nWhen the form was then sumbmitted, you would access the values just like any other field:\n\nif ($form->field('mailopt')) {\n# is 1, so add them\n} else {\n# is 0, remove them\n}\n\nFinally, you can also loop through each of the fields using the top-level \"fields\" loop in your\ntemplate. This allows you to reuse the same template even if your parameters change. The\nfollowing template code would loop through each field, creating a table row for each:\n\n\n\n\n\n\n\n\n
\n\nEach loop will have a \"label\", \"field\", \"value\", etc, just like above.\n\nFor more information on templates, see HTML::Template.\n", "subsections": [] }, "SEE ALSO": { "content": "CGI::FormBuilder, CGI::FormBuilder::Template, HTML::Template\n", "subsections": [] }, "REVISION": { "content": "$Id: HTML.pm 100 2007-03-02 18:13:13Z nwiger $\n", "subsections": [] }, "AUTHOR": { "content": "Copyright (c) Nate Wiger . 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": [] } } } }