Metadata-Version: 2.1
Name: collective.volto.formsupport
Version: 2.4.0
Summary: Add support for customizable forms in Volto
Home-page: https://github.com/collective/collective.volto.formsupport
Author: RedTurtle Technology
Author-email: sviluppo@redturtle.it
License: GPL version 2
Project-URL: PyPI, https://pypi.python.org/pypi/collective.volto.formsupport
Project-URL: Source, https://github.com/collective/collective.volto.formsupport
Project-URL: Tracker, https://github.com/collective/collective.volto.formsupport/issues
Description: .. image:: https://img.shields.io/pypi/v/collective.volto.formsupport.svg
            :target: https://pypi.python.org/pypi/collective.volto.formsupport/
            :alt: Latest Version
        
        .. image:: https://img.shields.io/pypi/status/collective.volto.formsupport.svg
            :target: https://pypi.python.org/pypi/collective.volto.formsupport
            :alt: Egg Status
        
        .. image:: https://img.shields.io/pypi/pyversions/collective.volto.formsupport.svg?style=plastic   :alt: Supported - Python Versions
        
        .. image:: https://img.shields.io/pypi/l/collective.volto.formsupport.svg
            :target: https://pypi.python.org/pypi/collective.volto.formsupport/
            :alt: License
        
        .. image:: https://coveralls.io/repos/github/collective/collective.volto.formsupport/badge.svg
            :target: https://coveralls.io/github/collective/collective.volto.formsupport
            :alt: Coverage
        
        
        ============================
        collective.volto.formsupport
        ============================
        
        Add some helper routes and functionalities for Volto sites with ``form`` blocks provided by `volto-form-block <https://github.com/collective/volto-form-block>`_ Volto plugin.
        
        plone.restapi endpoints
        =======================
        
        @submit-form
        ------------
        
        Endpoint that the frontend should call as a submit action.
        
        You can call it with a POST on the context where the block form is stored like this::
        
        > curl -i -X POST http://localhost:8080/Plone/my-form/@submit-form -H 'Accept: application/json' -H 'Content-Type: application/json' --data-raw '{"block_id": "123456789", "data": [{"field_id": "foo", "value":"foo", "label": "Foo"},{"field_id": "from", "value": "support@foo.com"}, {"field_id":"name", "value": "John Doe", "label": "Name"}]}'
        
        where:
        
        - ``my-form`` is the context where we have a form block
        - ``block_id`` is the id of the block
        - ``data`` contains the submitted form data
        
        Calling this endpoint, it will do some actions (based on block settings) and returns a ``204`` response.
        
        
        @form-data
        ----------
        
        This is an expansion component.
        
        There is a rule that returns a ``form-data`` item into "components" slot if the user can edit the
        context (**Modify portal content** permission) and there is a block that can store data.
        
        Calling with "expand=true", this endpoint returns the stored data::
        
        > curl -i -X GET http://localhost:8080/Plone/my-form/@form-data -H 'Accept: application/json' -H 'Content-Type: application/json' --user admin:admin
        
        
        And replies with something similar::
        
            {
                "@id": "http://localhost:8080/Plone/my-form/@form-data",
                "items": [
                    {
                    "block_id": "123456789",
                    "date": "2021-03-10T12:25:24",
                    "from": "support@foo.com",
                    "id": 912078826,
                    "name": "John Doe"
                    },
                    ...
                ],
                "items_total": 42
            }
        
        @form-data-export
        -----------------
        
        Returns a csv file with all data (only for users that have **Modify portal content** permission)::
        
        > curl -i -X GET http://localhost:8080/Plone/my-form/@form-data-export -H 'Accept: application/json' -H 'Content-Type: application/json' --user admin:admin
        
        If form fields changed between some submissions, you will see also columns related to old fields.
        
        @form-data-clear
        ----------------
        
        Reset the store (only for users that have **Modify portal content** permission)::
        
        > curl -i -X GET http://localhost:8080/Plone/my-form/@form-data-clear -H 'Accept: application/json' -H 'Content-Type: application/json' --user admin:admin
        
        
        Form actions
        ============
        
        Using `volto-form-block <https://github.com/collective/volto-form-block>`_ you can set if the form submit should send data to an email address
        or store it into an internal catalog (or both).
        
        Send
        ----
        
        If block is set to send data, an email with form data will be sent to the recipient set in block settings or (if not set) to the site address.
        
        If ther is an ``attachments`` field in the POST data, these files will be attached to the emal sent.
        
        Store
        -----
        
        If block is set to store data, we store it into the content that has that block (with a `souper.plone <https://pypi.org/project/souper.plone>`_ catalog).
        
        The store is an adapter registered for *IFormDataStore* interface, so you can override it easily.
        
        Only fields that are also in block settings are stored. Missing ones will be skipped.
        
        Each Record stores also two *service* attributes:
        
        - **fields_labels**: a mapping of field ids to field labels. This is useful when we export csv files, so we can labels for the columns.
        - **fields_order**: sorted list of field ids. This can be used in csv export to keep the order of fields.
        
        We store these attributes because the form can change over time and we want to have a snapshot of the fields in the Record.
        
        Block serializer
        ================
        
        There is a custom block serializer for type ``form``.
        
        This serializer removes all fields that start with "\**default_**\" if the user can't edit the current context.
        
        This is useful because we don't want to expose some internals configurations (for example the recipient email address)
        to external users that should only fill the form.
        
        If the block has a field ``captcha``, an additional property ``captcha_props`` is serialized by the ``serialize``
        method provided by the ICaptchaSupport named adapter, the result contains useful metadata for the client, as the
        captcha public_key, ie::
        
            {
                "subblocks": [
                    ...
                ],
                "captcha": "recaptcha",
                "captcha_props": {
                    "provider": "recaptcha",
                    "public_key": "aaaaaaaaaaaaa"
                }
            }
        
        Captcha support
        ===============
        
        Captcha support requires a specific name adapter that implements ``ICaptchaSupport``.
        This product contains implementations for HCaptcha, Google ReCaptcha and questions and answers
        captcha using plone.formwidget.hcaptcha, plone.formwidget.recaptcha and collective.z3cform.norobots
        respectively, which must be included, installed and configured separately.
        
        During the form post, the token captcha will be verified with the defined captcha method.
        
        For captcha support `volto-form-block` version >= 2.4.0 is required.
        
        Examples
        ========
        
        This add-on can be seen in action at the following sites:
        
        - https://www.comune.modena.it/form/contatti
        
        
        
        Translations
        ============
        
        This product has been translated into
        
        - Italian
        
        
        Installation
        ============
        
        Install collective.volto.formsupport by adding it to your buildout::
        
            [buildout]
        
            ...
        
            eggs =
                collective.volto.formsupport
        
        
        and then running ``bin/buildout``
        
        
        Contribute
        ==========
        
        - Issue Tracker: https://github.com/collective/collective.volto.formsupport/issues
        - Source Code: https://github.com/collective/collective.volto.formsupport
        
        
        License
        =======
        
        The project is licensed under the GPLv2.
        
        Authors
        =======
        
        This product was developed by **RedTurtle Technology** team.
        
        .. image:: https://avatars1.githubusercontent.com/u/1087171?s=100&v=4
           :alt: RedTurtle Technology Site
           :target: https://www.redturtle.it/
        
        
        Contributors
        ============
        
        - RedTurtle Technology, sviluppo@redturtle.it
        - Mauro Amico, mauro.amico@gmail.com
        
        Changelog
        =========
        
        2.4.0 (2022-09-08)
        ------------------
        
        - Add collective.z3cform.norobots support
          [erral]
        
        2.3.0 (2022-05-26)
        ------------------
        
        - Breaking change: changed the way to store data keys. Now we use field_id as key for Records.
          [cekk]
        - Fix quoting in csv export.
          [cekk]
        - Generate csv columns with proper field labels, and keep the form order.
          [cekk]
        - Captcha support #13.
          [mamico]
        
        
        2.2.0 (2022-04-07)
        ------------------
        
        - Notify an event on sumbit.
          [mamico]
        
        
        2.1.0 (2022-03-25)
        ------------------
        
        - Support for user_as_bcc field in volto-form-block: send a separate mail for each email field with that flag.
          [cekk]
        
        
        2.0.3 (2021-10-25)
        ------------------
        
        - Fix permission checks in serializer.
          [nzambello]
        
        
        2.0.2 (2021-10-25)
        ------------------
        
        - Fix permission checks.
          [cekk]
        
        
        2.0.1 (2021-10-18)
        ------------------
        
        - [fix] do not send attachments multiple times.
          [cekk]
        
        
        2.0.0 (2021-08-19)
        ------------------
        
        - Convert field types: checkbox => multiple_choice and radio => single_choice
          to follow new schema in volto-form-block (https://github.com/collective/volto-form-block/pull/7).
          [cekk]
        
        
        1.0.5 (2021-05-12)
        ------------------
        
        - Added Brazilian Portuguese (pt_BR) translations.
          [ericof]
        
        
        1.0.4 (2021-04-15)
        ------------------
        
        - Changed the classifiers inside setup.py. This should fix some installation
          issues.
          [arsenico13]
        
        
        1.0.3 (2021-04-08)
        ------------------
        
        - NEW: The @submit-form entry-point now takes into account if a field is "marked"
          with "use_as_reply_to" and use that field for "from" and "reply to".
          [arsenico13]
        
        
        1.0.2 (2021-03-24)
        ------------------
        
        - Fix form_data for anon.
          [cekk]
        
        1.0.1 (2021-03-24)
        ------------------
        
        - Fix README for pypi.
          [cekk]
        
        
        1.0.0 (2021-03-24)
        ------------------
        
        - Initial release.
          [cekk]
        
Keywords: Python Plone CMS
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Framework :: Plone
Classifier: Framework :: Plone :: Addon
Classifier: Framework :: Plone :: 5.2
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v2 (GPLv2)
Requires-Python: >=3.6
Provides-Extra: hcaptcha
Provides-Extra: recaptcha
Provides-Extra: norobots
Provides-Extra: test
