{"id":24973301,"url":"https://github.com/bluedynamics/bda.plone.orders","last_synced_at":"2025-04-11T08:13:40.014Z","repository":{"id":4177919,"uuid":"5294376","full_name":"bluedynamics/bda.plone.orders","owner":"bluedynamics","description":"Orders persistence and backoffice UI for bda.plone.shop","archived":false,"fork":false,"pushed_at":"2024-04-25T11:45:32.000Z","size":1630,"stargazers_count":1,"open_issues_count":9,"forks_count":7,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-04-25T14:21:03.939Z","etag":null,"topics":["hacktoberfest"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bluedynamics.png","metadata":{"files":{"readme":"README.rst","changelog":"CHANGES.rst","contributing":null,"funding":null,"license":"LICENSE.rst","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2012-08-04T09:04:44.000Z","updated_at":"2024-04-25T14:21:03.939Z","dependencies_parsed_at":"2024-04-24T09:43:29.146Z","dependency_job_id":"a1f8d412-34cd-4a31-ae8e-3a51b99120d0","html_url":"https://github.com/bluedynamics/bda.plone.orders","commit_stats":null,"previous_names":[],"tags_count":22,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fbda.plone.orders","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fbda.plone.orders/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fbda.plone.orders/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bluedynamics%2Fbda.plone.orders/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bluedynamics","download_url":"https://codeload.github.com/bluedynamics/bda.plone.orders/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248360492,"owners_count":21090705,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest"],"created_at":"2025-02-03T18:27:09.915Z","updated_at":"2025-04-11T08:13:39.996Z","avatar_url":"https://github.com/bluedynamics.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"bda.plone.orders\n================\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n    :target: https://github.com/ambv/black\n\n.. image:: https://travis-ci.org/bluedynamics/bda.plone.orders.svg?branch=master\n    :target: https://travis-ci.org/bluedynamics/bda.plone.orders\n\nShop order storage and management.\n\nThis package is part of the ``bda.plone.shop`` stack. Please refer to\n`bda.plone.shop \u003chttps://github.com/bluedynamics/bda.plone.shop\u003e`_ for\ninstallation instructions.\n\n\nIntegration notes\n-----------------\n\n- The order actions are done with background images in CSS, so if you have your\n  own theme that is not based on Sunburst, you will have to add the \"icons.on\"\n  part of Sunburst's base.css.\n\n\nCustomizing Orders\n------------------\n\nIf you've added custom fields to the checkout (see\n`bda.plone.checkout`_), chances are high you want to add them to the\norder emails, order summaries or the order export.\n\n.. _`bda.plone.checkout`: https://github.com/bluedynamics/bda.plone.checkout\n\nPlease follow the instructions in `Customizing the shop` in the\n`bda.plone.shop`_ Readme first to setup the patch infrastructure.\n\n.. _`bda.plone.shop`: https://github.com/bluedynamics/bda.plone.shop\n\nAfter that you can start customizing the order process:\n\n.. code-block:: python\n\n    def patchShop():\n        patchMailTemplates()\n        patchOrderExport()\n\n\nMail notifications\n~~~~~~~~~~~~~~~~~~\n\nOrder related notification is done by sending multipart mails containing a\ntext and a HTML version of the notification payload.\n\nWhen customizing mail notification, both text and HTML templates needs to be\ncustomized.\n\nWARNING:\n\n    As of ``bda.plone.orders`` 1.0a1, signatue of\n    ``bda.plone.orders.MailNotify.send`` changed. It accepts now\n    ``subject``, ``receiver`` and ``text`` as positional arguments and an\n    optional ``html`` argument.\n\n\nHTML Templates\n^^^^^^^^^^^^^^\n\nDefault HTML templates are located at ``bda.plone.orders:mailtemplates``.\nTo customize them, copy the entire template folder to your integration package\nand patch ``bda.plone.orders.mailnotify.MAIL_TEMPLATES_DIRECTORY`` like so:\n\n.. code-block:: python\n\n    from bda.plone.orders import mailnotify\n    import os\n\n    mailnotify.MAIL_TEMPLATES_DIRECTORY = os.path.join(\n        os.path.dirname(__file__),\n        'mailtemplates'\n    )\n\n\nText Templates\n^^^^^^^^^^^^^^\n\nCopy the messages you need to customize from\n``bda.plone.orders.mailtemplates`` and change the text to your needs.\nThere are two dictionaries containing all the strings, ``ORDER_TEMPLATES``\nand ``RESERVATION_TEMPLATES``. Its a nested dict. On the first level is the\nlangugae code, the second level is ``subject``, ``body`` and\n``delivery_address``. Change them i.e. like this:\n\n.. code-block:: python\n\n    from bda.plone.orders.mailtemplates import ORDER_TEMPLATES\n    from bda.plone.orders.mailtemplates import RESERVATION_TEMPLATES\n\n    ORDER_TEMPLATES['en']['body'] = \"\"\"\n    This is my heavily customized confirmation mail.\"\"\"\n\n    RESERVATION_TEMPLATES['de']['body'] = \"Ihre Reservierung ist da!\"\n\nWhen updating ``bda.plone.order`` to a new version, make sure to keep them\nin sync with the original templates and check if all stock variables\n(such as ``global_text`` or the ``@@showorder`` link which have been\nadded in version 0.4 are present.)\n\n\nCustomize notification mechanism\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nAlternativly you add/replace the notification methods and implement your\nown very custom. To do provide your own two functions similar to\n``bda.plone.orders.mailnotify.notify_checkout_success`` and\n``bda.plone.orders.mailnotify.notify_payment_success``. Then\n\n.. code-block:: python\n\n    from bda.plone.orders.mailnotify import NOTIFICATIONS\n\n    # register as additional action\n    NOTIFICATIONS['checkout_success'].append(my_notify_checkout_success)\n    NOTIFICATIONS['payment_success'].append(my_notify_payment_success)\n\n    # OR\n    # register as replacement:\n    NOTIFICATIONS['checkout_success'] = [my_notify_checkout_success]\n    NOTIFICATIONS['payment_success'] = [my_notify_payment_success]\n\n\nOrder Export\n~~~~~~~~~~~~\n\nTo make a new field show up in the export, just add it to the\nlist ``ORDER_EXPORT_ATTRS``.\n\nIn this example we include the company uid we added in the example for\ncustomizing ``bda.plone.checkout`` right after the company name:\n\n.. code-block:: python\n\n    from bda.plone.orders.browser.export import ORDER_EXPORT_ATTRS\n\n    def patchOrderExport():\n        idx = ORDER_EXPORT_ATTRS.index('personal_data.company')\n        ORDER_EXPORT_ATTRS.insert(idx+1, 'personal_data.uid')\n\n\nOrder details\n~~~~~~~~~~~~~\n\nTo show the data of the new field in the detail view of the order\ncustomize ``bda/plone/orders/browser/templates/order.pt`` using\n`z3c.jbot \u003chttps://pypi.python.org/pypi/z3c.jbot\u003e`_ or by registering\nthe browser page for your policy package's browserlayer or themelayer:\n\n.. code-block:: xml\n\n    \u003cbrowser:page\n      for=\"zope.component.interfaces.ISite\"\n      name=\"order\"\n      template=\"my-order.pt\"\n      class=\"bda.plone.orders.browser.order.OrderView\"\n      permission=\"bda.plone.orders.ViewOrders\"\n      layer=\"my.package.interfaces.IMyBrowserLayer\"/\u003e\n\nWARNING:\n\n    as of ``bda.plone.orders`` 1.0a1 the template location changed from\n    browser package to templates folder in browser package. Please adopt\n    the location if you customized the template via ``z3c.jbot`` in your\n    integration package.\n\n\nInvoice view\n~~~~~~~~~~~~\n\nThe invoice template is ``bda/plone/orders/browser/templates/invoice.pt``.\nIt can be customized via `z3c.jbot \u003chttps://pypi.python.org/pypi/z3c.jbot\u003e`_ or\nby registering the browser page for your policy package's browserlayer or\nthemelayer:\n\n.. code-block:: xml\n\n      \u003cbrowser:page\n        for=\"zope.component.interfaces.ISite\"\n        name=\"invoice\"\n        template=\"my-invoice.pt\"\n        class=\"bda.plone.orders.browser.invoice.InvoiceView\"\n        permission=\"bda.plone.orders.ViewOrders\"\n        layer=\"my.package.interfaces.IMyBrowserLayer\" /\u003e\n\n\nRestrictions with souper.plone\n------------------------------\n\n- Make sure you do not move orders or bookings soup away from portal root. This\n  will end up in unexpected behavior and errors.\n\n\nVendor support\n--------------\n\n``bda.plone.orders`` supports the concept of vendors. A vendor is able to\nmanage his products and view orders and booking related to this products.\n\nA vendor has his own area, which is a container somewhere in the portal.\nTo enable vendor support for a container, navigate to it and apply\n``Enable vendor area`` action on it. Then navigate to local roles management\nview of this container and grant ``Vendor`` role to the desired users.\n\nThe users granted the ``Vendor`` role is now able to see order related views\nand perform order related actions in the context of this container.\n\n\nPermissions\n-----------\n\nIn general, custom shop deployments are likely to configure the permission and role settings according to their use cases.\n\nThe Permissions ``bda.plone.orders.ViewOrderDirectly`` and ``bda.plone.orders.ViewOwnOrders`` are granted to default Plone roles rather than Customer role.\nThe Customer role is intended to be granted as a local role contextually.\nThe ``@@orders`` and ``@@showorder`` and ``@@showinvoice`` views should be callable on ``ISite`` root.\nSo a possible customer might be no customer on the site root.\n\nFollowing as listing of the permissions and its purpose:\n\n\n``bda.plone.orders.ViewOrderDirectly``\n    Grants view access to single order data related views,\n    which are protected by ordernumber and related email address.\n\n    Currently order details and invoice are implemented as such views.\n    A link to them is sent in the order confirmation mail after successful checkout.\n\n    By default, this permission is set for roles:\n\n    * Manager\n    * Site Administrator\n    * Authenticated\n\n    In order to expose this views to all visitors by default, add ``Anonymous``\n    role via generic setup's ``rolemap.xml`` of your integration package.\n\n\n``bda.plone.orders.ViewOwnOrders``\n    Grants permission to view orders made by the currently authenticated user.\n\n    By default, this permission is set for roles:\n\n    * Manager\n    * Site Administrator\n    * Authenticated\n\n    To customize this, edit ``rolemap.xml`` in your integration package as needed.\n\n\n``bda.plone.orders.ViewOrders``\n    Grants permission to view all orders in a given context or globally.\n\n    By default, this permission is set for roles:\n\n    * Manager\n    * Site Administrator\n    * Vendor\n\n    To customize this, edit ``rolemap.xml`` in your integration package as needed.\n\n\n``bda.plone.orders.ModifyOrders``\n    Grants the user to modify orders.\n    This includes to perform state transitions on orders and bookings, and to modify booking comments.\n\n    By default, this permission is set for roles:\n\n    * Manager\n    * Site Administrator\n    * Vendor\n\n    To customize this, edit ``rolemap.xml`` in your integration package as needed.\n\n\n``bda.plone.orders.ExportOrders``\n    Grants the user to export orders in CSV format.\n\n    By default, this permission is set for roles:\n\n    * Manager\n    * Site Administrator\n    * Vendor\n\n    To customize this, edit ``rolemap.xml`` in your integration package as needed.\n\n\n``bda.plone.orders.ManageTemplates``\n    Grants the user to manage notification mail templates for existing orders.\n\n    By default, this permission is set for roles:\n\n    * Manager\n    * Site Administrator\n    * Vendor\n\n    To customize this, edit ``rolemap.xml`` in your integration package as needed.\n\n\n``bda.plone.orders.DelegateCustomerRole``\n    Grant the ``Customer`` role to other users via the localroles view.\n\n    By default, this permission is set for roles:\n\n    * Manager\n    * Site Administrator\n\n    To customize this, edit ``rolemap.xml`` in your integration package as needed.\n\n\n``bda.plone.orders.DelegateVendorRole``\n    Grants the user to grant the ``Vendor`` role to other users via the localroles view.\n\n    By default, this permission is set for no roles.\n\n    To customize this, edit ``rolemap.xml`` in your integration package as needed.\n\n\nHow To allow anonymous users to buy items\n-----------------------------------------\n\nIn your Generic Setup's profile, add to ``rolemap.xml``:\n\n.. code-block:: xml\n\n    \u003c!-- Allow Anonymous to buy items --\u003e\n    \u003cpermission name=\"bda.plone.orders: View Order Directly\" acquire=\"True\"\u003e\n      \u003crole name=\"Manager\" /\u003e\n      \u003crole name=\"Site Administrator\" /\u003e\n      \u003crole name=\"Authenticated\" /\u003e\n      \u003crole name=\"Anonymous\"/\u003e\n    \u003c/permission\u003e\n    \u003cpermission name=\"bda.plone.shop: View Buyable Info\" acquire=\"True\"\u003e\n      \u003crole name=\"Manager\" /\u003e\n      \u003crole name=\"Site Administrator\" /\u003e\n      \u003crole name=\"Reviewer\" /\u003e\n      \u003crole name=\"Editor\" /\u003e\n      \u003crole name=\"Customer\" /\u003e\n      \u003crole name=\"Anonymous\"/\u003e\n    \u003c/permission\u003e\n    \u003cpermission name=\"bda.plone.shop: Modify Cart\" acquire=\"True\"\u003e\n      \u003crole name=\"Manager\" /\u003e\n      \u003crole name=\"Site Administrator\" /\u003e\n      \u003crole name=\"Customer\" /\u003e\n      \u003crole name=\"Anonymous\"/\u003e\n    \u003c/permission\u003e\n    \u003cpermission name=\"bda.plone.checkout: Perform Checkout\" acquire=\"True\"\u003e\n      \u003crole name=\"Manager\" /\u003e\n      \u003crole name=\"Site Administrator\" /\u003e\n      \u003crole name=\"Customer\" /\u003e\n      \u003crole name=\"Anonymous\"/\u003e\n    \u003c/permission\u003e\n\n\nREST-API\n--------\n\nThere is a REST API available.\nIt is based on `plone.rest \u003chttps://pypi.org/project/plone.rest/\u003e`_ endpoints.\n\nThe REST API is work in progress and will be enhanced over time.\n\nWe provide the following endpoints:\n\nGET ``@shop-order/${ORDER-UID}``\n    The order data of the order with the given order-uid.\n    It includes bookings and the booking-data.\n\n\nCreate translations\n-------------------\n\n::\n\n    $ cd src/bda/plone/orders/\n    $ ./i18n.sh\n\n\nContributors\n------------\n\n- Robert Niederreiter (Author)\n- Johannes Raggam\n- Peter Holzer\n- Harald Frießnegger\n- Ezra Holder\n- Benjamin Stefaner (benniboy)\n- Jens Klein\n\n\nIcons used are `Silk-Icons by FamFamFam \u003chttp://www.famfamfam.com/lab/icons/silk/\u003e`_\nunder CC-BY 2.5 license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluedynamics%2Fbda.plone.orders","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbluedynamics%2Fbda.plone.orders","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbluedynamics%2Fbda.plone.orders/lists"}