|
1 | | -# pos-module-chat |
| 1 | +# Chat Module |
| 2 | + |
| 3 | +This module serves as a starting point for adding real time chat to your application. Before using the module for the first time, we recommend reading the official platformOS documentation on [WebSockets](https://documentation.platformos.com/use-cases/using-websockets) and on [Example Application](#example-application). |
| 4 | + |
| 5 | +This module follows the [platformOS DevKit best practices](https://documentation.staging.oregon.platform-os.com/developer-guide/modules/platformos-modules) and includes the [core module](https://github.com/Platform-OS/pos-module-core) as a dependency, enabling you to implement patterns such as [Commands](https://github.com/Platform-OS/pos-module-core?tab=readme-ov-file#commands--business-logic) and [Events](https://github.com/Platform-OS/pos-module-core?tab=readme-ov-file#events). It also includes the [user module](https://github.com/Platform-OS/pos-module-user) and [profile module](https://github.com/Platform-OS/pos-module-profile) as a dependency. |
| 6 | + |
| 7 | +For more information, |
| 8 | +- read the documentation about the [built-in User table](https://documentation.platformos.com/developer-guide/users/user), |
| 9 | +- learn about [how platformOS manages sessions](https://documentation.platformos.com/developer-guide/users/session), |
| 10 | +- and gain a high-level overview of [authentication strategies in platformOS](https://documentation.platformos.com/developer-guide/users/authentication). |
| 11 | + |
| 12 | +## Installation |
| 13 | + |
| 14 | +The platformOS Chat Module is available on the [Partner Portal Modules Marketplace](https://partners.platformos.com/marketplace/pos_modules/152). |
| 15 | + |
| 16 | +### Prerequisites |
| 17 | + |
| 18 | +Before installing the module, ensure that you have [pos-cli](https://github.com/mdyd-dev/pos-cli#overview) installed. This tool is essential for managing and deploying platformOS projects. |
| 19 | + |
| 20 | +The platformOS Chat Module is fully compatible with [platformOS Check](https://github.com/Platform-OS/platformos-lsp#platformos-check----a-linter-for-platformos), a linter and language server that supports any IDE with Language Server Protocol (LSP) integration. For Visual Studio Code users, you can enhance your development experience by installing the [VSCode platformOS Check Extension](https://marketplace.visualstudio.com/items?itemName=platformOS.platformos-check-vscode). |
| 21 | + |
| 22 | +### Installation Steps |
| 23 | + |
| 24 | +1. **Navigate to your project directory** where you want to install the Chat Module. |
| 25 | + |
| 26 | +2. **Run the installation command**: |
| 27 | + |
| 28 | +```bash |
| 29 | + pos-cli modules install chat |
| 30 | +``` |
| 31 | + |
| 32 | +This command installs the Chat Module along with its dependencies (such as [pos-module-core](https://github.com/Platform-OS/pos-module-core)) and updates or creates the `app/pos-modules.json` file in your project directory to track module configurations. |
| 33 | + |
| 34 | +### Setup |
| 35 | + |
| 36 | +1. **Install the module** using the [pos-cli](https://github.com/Platform-OS/pos-cli). |
| 37 | + |
| 38 | +2. If you haven't done it already, follow the instructions to setup [pos-module-user-](https://github.com/Platform-OS/pos-module-user?tab=readme-ov-file#setup). During this process, you will create an overwrite of the permissions file `app/modules/user/public/lib/queries/role_permissions/permissions.liquid` |
| 39 | + |
| 40 | +3. Overwrite default views that you would like to customize by following the guide on [overwriting a module file](https://documentation.platformos.com/developer-guide/modules/modules#overwritting-a-module-file). This allows you to add functionality based on your project requirements. At a minimum, you should overwrite the [permissions file](modules/user/public/lib/queries/role_permissions/permissions.liquid), where you will configure [RBAC authorization](#rbac-authorization) roles and permissions for your application - add `chat.inbox` permission to the role(s) that you would like to have access to the chat available at `/inbox`. In our example, the `inbox.chat` permission was added to `authenticated` role, meaning all signed in users have access to the chat. Snippet to create an overwrite to copy-paste into your terminal: |
| 41 | + |
| 42 | +``` |
| 43 | +mkdir -p app/modules/user/public/lib/queries/role_permissions |
| 44 | +cp modules/user/public/lib/queries/role_permissions/permissions.liquid app/modules/user/public/lib/queries/role_permissions/permissions.liquid |
| 45 | +``` |
| 46 | + |
| 47 | +4. Add the following to the `<head>` section of your application layout to get the basic styling provided with the module. To overwrite the colors and spacings you can overwrite the CSS variables in `pos-config.css`. |
| 48 | + |
| 49 | +``` |
| 50 | +<link rel="stylesheet" href="{{ 'modules/common-styling/style/pos-reset.css' | asset_url }}"> |
| 51 | +<link rel="stylesheet" href="{{ 'modules/common-styling/style/pos-config.css' | asset_url }}"> |
| 52 | +<link rel="stylesheet" href="{{ 'modules/common-styling/style/pos-button.css' | asset_url }}"> |
| 53 | +<link rel="stylesheet" href="{{ 'modules/common-styling/style/pos-typography.css' | asset_url }}"> |
| 54 | +<link rel="stylesheet" href="{{ 'modules/common-styling/style/pos-avatar.css' | asset_url }}"> |
| 55 | +<link rel="stylesheet" href="{{ 'modules/common-styling/style/pos-forms.css' | asset_url }}"> |
| 56 | +<link rel="stylesheet" href="{{ 'modules/common-styling/style/pos-page.css' | asset_url }}"> |
| 57 | +<link rel="stylesheet" href="{{ 'modules/chat/style/pos-chat-inbox.css' | asset_url }}"> |
| 58 | +``` |
| 59 | + |
| 60 | +5. Add the following to the `<head>` section of your application layout **before any other `<script>` tag on the page**. Or - if you already using an import map, just extend it with the following: |
| 61 | + |
| 62 | +``` |
| 63 | +<script type="importmap"> |
| 64 | + { |
| 65 | + "imports": { |
| 66 | + "/": "{{ 'modules/chat/js/' | asset_url }}", |
| 67 | + "pos-chat.js": "{{ 'modules/chat/js/pos-chat.js' | asset_url }}", |
| 68 | + "pos-chat-consumer.js": "{{ 'modules/chat/js/pos-chat-consumer.js' | asset_url }}", |
| 69 | + "pos-chat-csrfToken.js": "{{ 'modules/chat/js/pos-chat-csrfToken.js' | asset_url }}", |
| 70 | + "pos-chat-notifications.js": "{{ 'modules/chat/js/pos-chat-notifications.js' | asset_url }}", |
| 71 | + "./": "./" |
| 72 | + } |
| 73 | + } |
| 74 | +</script> |
| 75 | +``` |
| 76 | + |
| 77 | +### Managing Module Files |
| 78 | + |
| 79 | +The default behavior of modules is that **the files are never deleted**. It is assumed that developers might not have access to all of the files, and thanks to this feature, they can still overwrite some of the module's files without breaking them. Since the User Module is fully public, it is recommended to delete files on deployment. To do this, ensure your `app/config.yml` includes the User Module and its dependencies in the list `modules_that_allow_delete_on_deploy`: |
| 80 | + |
| 81 | +``` yaml |
| 82 | +modules_that_allow_delete_on_deploy: |
| 83 | +- core |
| 84 | +- user |
| 85 | +- profile |
| 86 | +- chat |
| 87 | +``` |
| 88 | +
|
| 89 | +## Example application |
| 90 | +
|
| 91 | +We recommend creating a [new Instance](https://partners.platformos.com/instances/new) and deploying this module as an application to get a better understanding of the basics and the functionality this module provides. When you install the module using `pos-cli modules install chat`, only the contents of the `modules/chat` will be available in your project. The `app` directory serves as an example of how you could incorporate the Chat Module into your application. When analyzing the code in the `app` directory, pay attention to the following files: |
| 92 | + |
| 93 | +* ** `app/config.yml`** and **`app/user.yml`**: These files are defined according to the [Setup](#setup) instructions. |
| 94 | +* ** `app/modules/user/public/lib/queries/role_permissions/permissions.liquid`**: Demonstrates how to configure permissions in your application by [overwriting a module file](https://documentation.platformos.com/developer-guide/modules/modules#overwriting-a-module-file). |
| 95 | + |
| 96 | +## Functionality provided by the chat module: |
| 97 | + |
| 98 | +Once the module is installed and you have completed the [setup](#setup), you will immediately gain access to the new endpoints created by this module. For example, you can navigate to `/inbox` for the chat window. |
| 99 | + |
| 100 | +- [x] **[Inbox](#inbox)**: |
| 101 | + |
| 102 | +TODO (Upcoming Features) |
| 103 | + |
| 104 | + |
| 105 | +### Inbox |
| 106 | + |
| 107 | +Inbox |
| 108 | + |
| 109 | +#### Endpoints for the registration |
| 110 | + |
| 111 | +The table below outlines the [resourceful routes](https://documentation.platformos.com/developer-guide/modules/platformos-modules#resourceful-route-naming-convention) provided for registration functionality: |
| 112 | + |
| 113 | +| HTTP method | slug | page file path | description |
| 114 | +|---|---|---|---|---| |
| 115 | +| GET | /inbox | `modules/chat/public/views/pages/inbox.liquid` | Renders a chat | |
| 116 | + |
| 117 | +#### CRUD commands |
| 118 | + |
| 119 | +... |
| 120 | + |
| 121 | + |
| 122 | +## Customizing the looks |
| 123 | + |
| 124 | +The chat module by default uses styling provided by the platformOS Common Styling module. It's built with the intention to easily overwrite the colors, fonts and spacings by overwriting the CSS variables stored in `modules/common-styling/style/pos-config.css`. You can create your own `.css` file and just overwrite any value of any variable. If you need more CSS customization you can obviously just use standard styling techniques and if you need to change the HTML structure even further, you can overwrite any liquid partial used in the chat. |
0 commit comments