{ "info": { "author": "Plone Foundation", "author_email": "plone-developers@lists.sourceforge.net", "bugtrack_url": null, "classifiers": [ "Development Status :: 6 - Mature", "Framework :: Plone", "Framework :: Plone :: 5.2", "Framework :: Plone :: Core", "Framework :: Zope :: 4", "License :: OSI Approved :: GNU General Public License (GPL)", "Programming Language :: Python", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3.6", "Programming Language :: Python :: 3.7" ], "description": "=================\nplone.app.z3cform\n=================\n\nA Plone specific integration and HTML mark-up for z3c.form.\n\n.. contents:: Table of Contents\n\nIntroduction\n==============\n\nThis Plone package is aimed for developers who want to create forms\nin Python code.\n\nPlease read the documentation for `z3c.form`_, which contains important\ninformation about using z3c.form in Zope 2 in general. For the most part,\nthat package contains the \"active\" parts that you need to know about, and\nthis package provides \"passive\" overrides that make the forms integrate with\nPlone.\n\nInstallation\n============\n\nPlone 4.1 and later include *plone.app.z3cform* in Plone core. Older versions need to install\nthe addon separately as your own add-on dependency.\n\nFeatures\n============\n\nThe following Plone and z3c.form integration is added\n\n* Plone *main_template.pt* integration\n\n* Plone specific widget frame\n\n* Date/time pickers\n\n* WYSIWYG widget (TinyMCE visual editor with Plone support)\n\n* CRUD forms\n\nOut of the box form templates\n==================================\n\nThe form and widget templates are applied in the following order\n\n* *plone.app.z3cform* specific\n\n* *plone.z3cform* specific\n\n* *z3c.form* specific\n\n*plone.app.z3cform* package overrides the ``@@ploneform-macros`` view from `plone.z3cform`_,\nusing standard Plone markup for form fields, fieldsets, etc.\n\nAll the macros described in `plone.z3cform`_ are still available. In addition,\nyou can use the ``widget_rendering`` macro to render all the default widgets,\nbut none of the fieldsets (groups) or the fieldset headers (which would be\nrendered with the ``fields`` macro).\n\nEach widget is rendered using the ``@@ploneform-render-widget`` view, which by\ndefault includes the widget's label, required indicator, description, errors,\nand the result of ``widget.render()``. This view may be overridden for\nparticular widget types in order to customize this widget chrome.\n\nCustomizing form behavior\n============================\n\nForm method\n-------------\n\nIf your form instance defines a property called ``method`` it allows\nyou to set whether form is HTTP POST or HTTP GET. The default is POST.\nThis translates to ``
`` attribute.\n\nExample::\n\n class HolidayServiceSearchForm(form.Form):\n \"\"\" Example search form of which results can be bookmarked.\n\n Bookmarking is possible because we use HTTP GET method.\n \"\"\"\n\n method = \"get\"\n\nForm action\n------------\n\nForm ``action`` property defines HTTP target where the form is posted. The default is\nthe same page where the form was rendered, ``request.getURL()``.\n\nExample::\n\n class HolidayServiceSearchForm(form.Form):\n\n def action(self):\n \"\"\" Redefine attribute.\n\n We use URL fragment to define the anchor\n were we directly scroll at the results when the form is posted,\n skipping unnecessary form fields part. The user can scroll\n back there if he/she wants modify the parameters.\n \"\"\"\n\n # Context item URL + form view name + link fragment.\n # This works for HTTP GET forms only.\n # Note that we cannot use request.getURL() as it might contain\n # 1) prior fragment 2) GET query parameters messing up the UrL\n return self.context.absolute_url() + \"/holidayservice_view\" + \"#searched\"\n\nFieldsets and tabs\n--------------------\n\nYou can fieldsets to your form if you subclass the form from z3c.form.group.GroupForm.\nThe default behavior of Plone is to turn these fieldsets to tabs (as seen on\nany *Edit* view of content item).\n\nYou can disable this behavior for your form::\n\n\n\n class ReportForm(z3c.form.group.GroupForm, z3c.form.form.Form):\n\n # Disable turn fieldsets to tabs behavior\n enable_form_tabbing = False\n\nUnload protection\n-----------------\n\nThe default behaviour on Plone is to add a confirm box\nif you leave a form you have modified without having submitted it.\n\nYou can disable this behavior for your form::\n\n class SearchForm(z3c.form.group.GroupForm, z3c.form.form.Form):\n\n # Disable unload protection behavior\n enable_unload_protection = False\n\n\nCSRF Protection\n===============\n\nA common vulnerability affecting web forms is cross-site request forgery (CSRF).\nThis attack occurs when the user of your site visits a third-party site that\nuses Javascript to post to a URL on your site without the user's knowledge,\ntaking advantage of the user's active session.\n\n\n\nplone.app.z3cform can protect against this type of attack by adding a unique\ntoken as a hidden input when rendering the form, and checking to make sure it\nis present as a request parameter when form actions are executed.\n\nTo turn on this protection, enable the form's enableCSRFProtection attribute.\nExample::\n\n class PasswordForm(form.Form):\n \"\"\"Form to set the user's password.\"\"\"\n enableCSRFProtection = True\n\nForm main template override\n=============================\n\nForms are framed by *FormWrapper* views. It places rendered\nform inside Plone page frame. The default *FormWrapper* is supplied automatically,\nbut you can override it.\n\nBelow is a placeholder example with few `