{
    "info": {
        "author": "Christian Hess",
        "author_email": "",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "# Shuup Admin Channel\n\n:warning ALPHA VERSION\n\nAdds a generic and extendable channel to Admin module using [Shuup Channels](https://github.com/chessbr/shuup-channels).\n\nThis adds an optional consumer that will warn logged staff users when a new order is created through a notification, without the need of a page reload.\n\nYou can also create your own custom admin consumer and plug it in this channel.\n\n1. Install `pip install shuup-admin-channel`\n2. Add `shuup-admin-channel` to your `INSTALLED_APPS` settings\n3. Profit! This will make Shuup load the scripts on each admin page load and connect with the Admin channel.\n\n## How it works\n\nThis addon will provide a websocket consumer to Django Channels on the `ws://HOST/ws/admin/(?P<shop_id>\\d+)/` URL pattern.\n\nYou must connect to it using the shop ID you want to receive Admin related messages. This addon already provides a JS lib to connect and listen and send messages to the channel.\n\nXTheme resource injection is used to append the small lib to each Shuup Admin request. If you don't want that to be injected, you must blacklist the `\"shuup_admin_channel.resources:add_resources\"` provide entry in your settings ([see how to do that here](https://shuup.readthedocs.io/en/latest/ref/provides.html#blacklisting-provides).)\n\n### Listening channel messages\n\nTo listen to Admin channel, do the following:\n\n```js\n// Listen for 'alert' command messages\nShuupAdminChannel.events.on(\"received\", (payload) => {\n    if (payload.command === \"alert\") {\n        Messages.enqueue({\n            tags: payload.level,\n            text: payload.message\n        });\n    }\n});\n```\n\nThe `payload` is a JSON object sent by the channel. `payload.command` will contain the command sent from the channel and you can check that for custom commands.\n\n### Sending messages\n\nTo send messages to the channel using JavaScript, you can do the following:\n\n```js\nShuupAdminChannel.send({\n    handler: \"send_alert\",\n    message: \"Hello staff users!\",\n    level: \"info\"\n});\n```\n\nThis will send an info message to all logged staff users. `handler` is the existing the consumer handler. If no handler with that name exists, nothing will be executed.\n\n### Extending Consumers\n\nIt is possible to extend the current Admin channel to receive and handle all sort of messages from the frontend (JavaScript) and make it fit to your project needs.\n\nYou first must understand Django Channels to understand our handlers.\n\nTo make it simple: we basically have two types of messages:\n\n- Those sent from JavaScript to a Consumer\n- Those sent from the backend to be broadcasted to all consumers (or a set of them)\n\nImagine that you are a staff user and want to send a message to all other staff users (like an internal message). You then send a websocket message to be broadcasted and here we cover those 2 possible messages listed above.\n\n1. Staff user send a message to the channel\n2. The channel received the message and retransmit to all connected users\n\nNow imagine you want a report that takes some time to complete but you don't want to keep the page loading for a long time. You can write a consumer to handle this message and send a message back to the user when the report is completed. This won't need to distribute the message to other consumers, you just must implement a receiver handler.\n\nAll kinds of possibilities can be created, just use your imagination :)\n\n### Handling messages from the socket\nIf you want to handle a message that came from the socket (from JS for example), you must implement a Receiver Handler object and add it to the `admin_channel_receiver_handler` provide key.\n\n\n```py\nclass SendAlertReceiverHandler(object):\n    name = \"send_alert\"\n\n    @classmethod\n    async def handle(cls, consumer, payload):\n        message = payload.get(\"message\")\n        level = payload.get(\"level\")\n        if not (message and level):\n            return\n\n        # Send message to room group using the `handle_send_alert` type\n        await consumer.channel_layer.group_send(consumer.shop_room_name, {\n            \"type\": \"handle_send_alert\",\n            \"message\": message,\n            \"level\": level\n        })\n```\n\nThis receiver handler will receive messages that contains `handler: \"send_alert\"` in the payload.\n\nOn this example, the andler will check for other payload values and if all of expected parameters are valid, it will broadcast a message to all consumers of the Admin Channel where the handler name should be `handle_send_alert`. It is basically a message broadcaster, it receives a message and retransmit to all consumers. It could just return something to the user directly but on this example we are passing that to other consumers.\n\n### Handling messages received from other consumers\n\nIn cases like above where a consumer wants to broadcast messages to all consumers, you want to add handlers to behave to those messages. For those, you must implement a Consumer Handler object and add it to `admin_channel_consumer_handler` provides key.\n\n```py\nclass OrderReceivedConsumerHandler(object):\n    name = \"handle_order_received\"\n\n    async def handle(self, payload):\n        await self.send(text_data=json.dumps({\n            \"command\": \"alert\",\n            \"message\": ugettext(\"New order received!\"),\n            \"level\": \"info\"\n        }))\n\n```\n\nOn this example, we are handling messages that were sent by the system, other consumer of anywhere in our python code which passed the type `handle_order_received`. This particular one is sent when a new order by a Django Signal.\n\nEach user is connected to a consumer and all them will receive this same message.\n\nFor examples of handlers and consumers, check [`handlers.py`](./shuup_admin_channel/handlers.py).\n\n## Settings\n\n- `SHUUP_ADMIN_CHANNEL_ORDER_RECEIVED_ENABLED`  Enable/disable the new order received notification\n- `SHUUP_ADMIN_CHANNEL_LAYER` - The name of the channel layer to use while sending messages\n- `SHUUP_ADMIN_CHANNEL_SETTINGS_PROVIDER` - The object that will provide configuration to the admin channel.\n\n## Features\n\n- Add notifications to warn users about new orders received\n- Add websocket command to dispatch a notification to all logged staff users through JavaScript\n- Add a way of exentending the channel\n\n# Copyright\n\nCopyright (C) 2019 by Christian Hess\n\n# License\n\nMIT\n\n\n",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/chessbr/shuup-admin-channel",
        "keywords": "shuup websocket channels",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "shuup-admin-channel",
        "package_url": "https://pypi.org/project/shuup-admin-channel/",
        "platform": "",
        "project_url": "https://pypi.org/project/shuup-admin-channel/",
        "project_urls": {
            "Homepage": "https://github.com/chessbr/shuup-admin-channel"
        },
        "release_url": "https://pypi.org/project/shuup-admin-channel/1.0.0/",
        "requires_dist": [
            "shuup",
            "shuup-channels"
        ],
        "requires_python": "",
        "summary": "Adds a generic and extendable channel to Admin module using Shuup Channels.",
        "version": "1.0.0"
    },
    "last_serial": 5185415,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "64f74bb6f5650e327bedac2ca5404f87",
                    "sha256": "7261426d9c956e03afca74710c3073b6eefc66d79791d114481a6d964ab9d74a"
                },
                "downloads": -1,
                "filename": "shuup_admin_channel-1.0.0-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "64f74bb6f5650e327bedac2ca5404f87",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 15355,
                "upload_time": "2019-04-25T00:22:25",
                "url": "https://files.pythonhosted.org/packages/9b/ef/434a1eda7540263dc022cf5d8ca4fa2c70a0c274dc9e5bac0b6e9be93a7a/shuup_admin_channel-1.0.0-py2.py3-none-any.whl"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "64f74bb6f5650e327bedac2ca5404f87",
                "sha256": "7261426d9c956e03afca74710c3073b6eefc66d79791d114481a6d964ab9d74a"
            },
            "downloads": -1,
            "filename": "shuup_admin_channel-1.0.0-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "64f74bb6f5650e327bedac2ca5404f87",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 15355,
            "upload_time": "2019-04-25T00:22:25",
            "url": "https://files.pythonhosted.org/packages/9b/ef/434a1eda7540263dc022cf5d8ca4fa2c70a0c274dc9e5bac0b6e9be93a7a/shuup_admin_channel-1.0.0-py2.py3-none-any.whl"
        }
    ]
}