This package provides support for writing forms using the Zope Formlib
library and registering them directly in Python (without ZCML).
.. contents::
Setting up ``grokcore.formlib``
===============================
This package is essentially set up like the `grokcore.component`_
package, please refer to its documentation for details. The
additional ZCML lines you will need are::
<include package="grokcore.formlib" file="meta.zcml" />
<include package="grokcore.formlib" />
Put the first line somewhere near the top of your root ZCML file.
Examples
========
We need an example interface::
from zope import interface, schema
class IMammoth(interface.Interface):
name = schema.TextLine(title=u"Name")
age = schema.Int(title=u"Age", min=0)
Edit forms
----------
You can provide an edit form for ``IMammoth`` like this::
from grokcore import formlib
class Edit(formlib.EditForm):
formlib.context(IMammoth)
If your content object is defined in the same Python file and
implements ``grokcore.formlib.IContext``, then it will be the default
context for your form.
Display forms
-------------
Display forms are as easy as edit forms::
class Index(formlib.DisplayForm):
formlib.context(IMammoth)
Generic forms
-------------
You can build more generic forms, providing your own actions for a form::
class ISearch(interface.Interface):
search = schema.TextLine(title=u"Text")
After this, you define your form. It's applied to a mammoth, but uses
the ``ISearch`` interface to generate fields::
class Search(formlib.Form):
formlib.context(IMammoth)
form_fields = formlib.Fields(ISearch)
def update(self):
# Default search results are None
self.search_result = None
@formlib.action(u"Search")
def search(self, text):
self.search_result = 'something found with text'
Create a custom template ``search.pt`` to render your form (in a
directory ``modulename_templates``).
Add forms
---------
Add forms work like generic forms, you have to provide your action
``Add``.
Customization
-------------
Since a Grok form is a Grok view, all configuration directives and
attributes available on a Grok view are available as well on a Grok
form.
This means that you can customize your form by associating a template
with it. The template is responsible for displaying widgets and
actions. The API to access them is the same as on a Zope Formlib form.
You can't customize a form by providing a ``render()`` method on it,
but you can still use the ``update()`` method if you want.
Please refer to the documentation of `grokcore.view`_ for more
details.
API Overview
============
Base classes
------------
``EditForm``
Extends ``Form`` to create an edit form for your content.
``DisplayForm``
Creates simple display forms.
``Form``
Is a base class to create generic forms.
``AddForm``
Extends ``Form`` to create add forms. You have to provide the *add*
action which is going to create the new object.
Decorators
----------
``action``
Is a decorator to create an action on the form. Your action only has
to accept values from the form as parameters.
Helpers
-------
``AutoFields``
Create form fields from the given context. If the context is an
interface, Zope fields defined in that interface are going to be
used to build form fields.
If the context is a regular object, Zope fields of all implemented
interfaces of that object are going to used to build form fields.
``Fields``
Create and reorder fields on the form.
Additionally, the ``grokcore.formlib`` package exposes the
`grokcore.component`_, `grokcore.security`_ and `grokcore.view`_ APIs.
.. _grokcore.component: https://pypi.org/project/grokcore.component
.. _grokcore.formlib: https://pypi.org/project/grokcore.formlib
.. _grokcore.security: https://pypi.org/project/grokcore.security
.. _grokcore.view: https://pypi.org/project/grokcore.view
Changes
=======
4.0 (2023-08-28)
----------------
- Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.
- Drop support for Python 2.7, 3.4, 3.5, 3.6.
3.0.1 (2018-01-12)
------------------
- Rearrange tests such that Travis CI can pick up all functional tests too.
3.0.0 (2018-01-04)
------------------
- Python 3 compatibility.
1.11 (2016-06-20)
-----------------
- ``grok.action`` will now trigger validation errors
``RequiredMissing`` for required fields that not present at all in
the request.
1.10.1 (2016-02-15)
-------------------
- Update tests.
1.10 (2015-04-01)
-----------------
- Forms now notify the ObjectEditedEvent instead of the ObjectModifiedEvent.
1.10a1 (2013-11-22)
-------------------
- Add compatibility for CSRF protection feature in zope.formlib.
1.9 (2012-05-01)
----------------
- Nothing changed yet.
1.8 (2010-11-03)
----------------
- The context directive now has its own default computation.
1.7 (2010-11-01)
----------------
- Update version requirements for martian, grokcore.component, grokcore.security
grokcore.view.
1.6 (2010-10-18)
----------------
- Made package comply to zope.org repository policy.
- Update functional tests to zope.app.wsgi Browser instead of zope.app.testing
one.
- Don't depend anymore on zope.app.zcmlfiles for tests.
1.5 (2009-12-13)
----------------
- Use zope.container instead of zope.app.container (in tests and in the
configure.zcml).
- Fixed up missing dependencies and splitted regular and test dependencies.
1.4 (2009-09-17)
----------------
* Reflect the changes in ``grokcore.view`` 1.12 where ``View`` and ``CodeView``
become a single ``View`` again. This reverts to the View situation of
``grokcore.formlib`` 1.1.
1.3 (2009-09-16)
----------------
* Remove the reference to the grok.View permission that is no longer in
grokcore.security 1.2
* Use 1.0b1 versions.cfg in Grok's release info instead of a local
copy; a local copy for all grokcore packages is just too hard to
maintain.
1.2 (2009-07-20)
----------------
* Adapted tests to the grokcore.view split of View and CodeView.
* Fixed forms to use self.template.render() directly instead of using a
removed private method from grokcore.view.
* Add grok.View permissions for functional tests.
1.1 (2009-01-07)
----------------
* Have GrokForm define an empty actions attribute by default, in order
for "action-less" forms to work easily.
1.0 (2008-09-25)
----------------
* Created ``grokcore.formlib`` in July 2008 by factoring
``zope.formlib``-based components, grokkers and directives out of
Grok.
Raw data
{
"_id": null,
"home_page": "https://github.com/zopefoundation/grokcore.formlib",
"name": "grokcore.formlib",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "",
"author": "Grok Team",
"author_email": "zope-dev@zope.dev",
"download_url": "https://files.pythonhosted.org/packages/38/ca/ceb5ed79b4748cea3d64a91c728ab36e7c51e8247039a7816c87c66c03e9/grokcore.formlib-4.0.tar.gz",
"platform": null,
"description": "This package provides support for writing forms using the Zope Formlib\nlibrary and registering them directly in Python (without ZCML).\n\n.. contents::\n\nSetting up ``grokcore.formlib``\n===============================\n\nThis package is essentially set up like the `grokcore.component`_\npackage, please refer to its documentation for details. The\nadditional ZCML lines you will need are::\n\n <include package=\"grokcore.formlib\" file=\"meta.zcml\" />\n <include package=\"grokcore.formlib\" />\n\nPut the first line somewhere near the top of your root ZCML file.\n\nExamples\n========\n\nWe need an example interface::\n\n from zope import interface, schema\n\n class IMammoth(interface.Interface):\n\n name = schema.TextLine(title=u\"Name\")\n age = schema.Int(title=u\"Age\", min=0)\n\nEdit forms\n----------\n\nYou can provide an edit form for ``IMammoth`` like this::\n\n\n from grokcore import formlib\n\n class Edit(formlib.EditForm):\n\n formlib.context(IMammoth)\n\n\nIf your content object is defined in the same Python file and\nimplements ``grokcore.formlib.IContext``, then it will be the default\ncontext for your form.\n\n\nDisplay forms\n-------------\n\nDisplay forms are as easy as edit forms::\n\n class Index(formlib.DisplayForm):\n\n formlib.context(IMammoth)\n\n\nGeneric forms\n-------------\n\n\nYou can build more generic forms, providing your own actions for a form::\n\n\n class ISearch(interface.Interface):\n\n search = schema.TextLine(title=u\"Text\")\n\n\nAfter this, you define your form. It's applied to a mammoth, but uses\nthe ``ISearch`` interface to generate fields::\n\n class Search(formlib.Form):\n\n formlib.context(IMammoth)\n\n form_fields = formlib.Fields(ISearch)\n\n def update(self):\n # Default search results are None\n self.search_result = None\n\n @formlib.action(u\"Search\")\n def search(self, text):\n self.search_result = 'something found with text'\n\n\n\nCreate a custom template ``search.pt`` to render your form (in a\ndirectory ``modulename_templates``).\n\n\nAdd forms\n---------\n\nAdd forms work like generic forms, you have to provide your action\n``Add``.\n\nCustomization\n-------------\n\nSince a Grok form is a Grok view, all configuration directives and\nattributes available on a Grok view are available as well on a Grok\nform.\n\nThis means that you can customize your form by associating a template\nwith it. The template is responsible for displaying widgets and\nactions. The API to access them is the same as on a Zope Formlib form.\n\nYou can't customize a form by providing a ``render()`` method on it,\nbut you can still use the ``update()`` method if you want.\n\nPlease refer to the documentation of `grokcore.view`_ for more\ndetails.\n\nAPI Overview\n============\n\nBase classes\n------------\n\n``EditForm``\n Extends ``Form`` to create an edit form for your content.\n\n``DisplayForm``\n Creates simple display forms.\n\n``Form``\n Is a base class to create generic forms.\n\n``AddForm``\n Extends ``Form`` to create add forms. You have to provide the *add*\n action which is going to create the new object.\n\nDecorators\n----------\n\n``action``\n Is a decorator to create an action on the form. Your action only has\n to accept values from the form as parameters.\n\nHelpers\n-------\n\n``AutoFields``\n Create form fields from the given context. If the context is an\n interface, Zope fields defined in that interface are going to be\n used to build form fields.\n If the context is a regular object, Zope fields of all implemented\n interfaces of that object are going to used to build form fields.\n\n``Fields``\n Create and reorder fields on the form.\n\n\nAdditionally, the ``grokcore.formlib`` package exposes the\n`grokcore.component`_, `grokcore.security`_ and `grokcore.view`_ APIs.\n\n.. _grokcore.component: https://pypi.org/project/grokcore.component\n.. _grokcore.formlib: https://pypi.org/project/grokcore.formlib\n.. _grokcore.security: https://pypi.org/project/grokcore.security\n.. _grokcore.view: https://pypi.org/project/grokcore.view\n\n\n\nChanges\n=======\n\n4.0 (2023-08-28)\n----------------\n\n- Add support for Python 3.7, 3.8, 3.9, 3.10, 3.11.\n\n- Drop support for Python 2.7, 3.4, 3.5, 3.6.\n\n\n3.0.1 (2018-01-12)\n------------------\n\n- Rearrange tests such that Travis CI can pick up all functional tests too.\n\n3.0.0 (2018-01-04)\n------------------\n\n- Python 3 compatibility.\n\n1.11 (2016-06-20)\n-----------------\n\n- ``grok.action`` will now trigger validation errors\n ``RequiredMissing`` for required fields that not present at all in\n the request.\n\n1.10.1 (2016-02-15)\n-------------------\n\n- Update tests.\n\n1.10 (2015-04-01)\n-----------------\n\n- Forms now notify the ObjectEditedEvent instead of the ObjectModifiedEvent.\n\n1.10a1 (2013-11-22)\n-------------------\n\n- Add compatibility for CSRF protection feature in zope.formlib.\n\n1.9 (2012-05-01)\n----------------\n\n- Nothing changed yet.\n\n1.8 (2010-11-03)\n----------------\n\n- The context directive now has its own default computation.\n\n1.7 (2010-11-01)\n----------------\n\n- Update version requirements for martian, grokcore.component, grokcore.security\n grokcore.view.\n\n1.6 (2010-10-18)\n----------------\n\n- Made package comply to zope.org repository policy.\n\n- Update functional tests to zope.app.wsgi Browser instead of zope.app.testing\n one.\n\n- Don't depend anymore on zope.app.zcmlfiles for tests.\n\n1.5 (2009-12-13)\n----------------\n\n- Use zope.container instead of zope.app.container (in tests and in the\n configure.zcml).\n\n- Fixed up missing dependencies and splitted regular and test dependencies.\n\n\n1.4 (2009-09-17)\n----------------\n\n* Reflect the changes in ``grokcore.view`` 1.12 where ``View`` and ``CodeView``\n become a single ``View`` again. This reverts to the View situation of\n ``grokcore.formlib`` 1.1.\n\n1.3 (2009-09-16)\n----------------\n\n* Remove the reference to the grok.View permission that is no longer in\n grokcore.security 1.2\n\n* Use 1.0b1 versions.cfg in Grok's release info instead of a local\n copy; a local copy for all grokcore packages is just too hard to\n maintain.\n\n1.2 (2009-07-20)\n----------------\n\n* Adapted tests to the grokcore.view split of View and CodeView.\n\n* Fixed forms to use self.template.render() directly instead of using a\n removed private method from grokcore.view.\n\n* Add grok.View permissions for functional tests.\n\n1.1 (2009-01-07)\n----------------\n\n* Have GrokForm define an empty actions attribute by default, in order\n for \"action-less\" forms to work easily.\n\n1.0 (2008-09-25)\n----------------\n\n* Created ``grokcore.formlib`` in July 2008 by factoring\n ``zope.formlib``-based components, grokkers and directives out of\n Grok.\n",
"bugtrack_url": null,
"license": "ZPL",
"summary": "Grok-like configuration for zope.formlib components",
"version": "4.0",
"project_urls": {
"Download": "https://pypi.org/project/grokcore.formlib",
"Homepage": "https://github.com/zopefoundation/grokcore.formlib"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0ffe750ee2cdf66ca192f5f1f6d2eb1ae108f31736992b98faa1a2f1ce2921ed",
"md5": "a54a11cfafeb25ed29602b16f6823f0c",
"sha256": "5af32e882f18fd935f9b906bc9863cba3c9cd3e244c649486a821e0b55a4357e"
},
"downloads": -1,
"filename": "grokcore.formlib-4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a54a11cfafeb25ed29602b16f6823f0c",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 37428,
"upload_time": "2023-08-28T11:38:36",
"upload_time_iso_8601": "2023-08-28T11:38:36.838414Z",
"url": "https://files.pythonhosted.org/packages/0f/fe/750ee2cdf66ca192f5f1f6d2eb1ae108f31736992b98faa1a2f1ce2921ed/grokcore.formlib-4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "38caceb5ed79b4748cea3d64a91c728ab36e7c51e8247039a7816c87c66c03e9",
"md5": "8cc428360e3c2b4b1f0ffd1a8650bbed",
"sha256": "0d89038dfb9aec586080244f9ea1d651eea99fe128fd927876e71a32462ea3d8"
},
"downloads": -1,
"filename": "grokcore.formlib-4.0.tar.gz",
"has_sig": false,
"md5_digest": "8cc428360e3c2b4b1f0ffd1a8650bbed",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 25945,
"upload_time": "2023-08-28T11:38:38",
"upload_time_iso_8601": "2023-08-28T11:38:38.760796Z",
"url": "https://files.pythonhosted.org/packages/38/ca/ceb5ed79b4748cea3d64a91c728ab36e7c51e8247039a7816c87c66c03e9/grokcore.formlib-4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-08-28 11:38:38",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "zopefoundation",
"github_project": "grokcore.formlib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "grokcore.formlib"
}
JSON
