@pazznetwork/ngx-chat
Version:
[](https://travis-ci.com/pazznetwork/ngx-chat) [](https://coveralls.io/github/pazzn
221 lines (160 loc) • 7.38 kB
Markdown
# [Get Started](https://pazznetwork.github.io/ngx-chat-ghpages/documentation/#get-started) | [Get Help](https://pazznetwork.github.io/ngx-chat-ghpages/documentation/#get-help) | [Get Involved](https://pazznetwork.github.io/ngx-chat-ghpages/documentation/#get-involved)
[](https://travis-ci.com/pazznetwork/ngx-chat) [](https://coveralls.io/github/pazznetwork/ngx-chat)  [](https://pazznetwork.github.io/ngx-chat-ghpages/documentation/) [](https://typescriptlang.org) [](https://nodejs.org) [](https://angular.io/)
[](https://pazznetwork.github.io/ngx-chat-ghpages/documentation/)
This library provides an out-of-the-box usable XMPP chat component. It is customizable and offers an API to integrate it with your
application.
This library provides an out-of-the-box usable XMPP chat component. It is customizable and offers an API to integrate it with your application.
## Features
* connect to XMPP servers via websocket
* send and receive messages
* load messages from message history (XEP-0313)
* use the server side buddy list or use your own data source for that, API methods for adding / removing buddies available
* supports multi-user chat
[Have a look at our demo (valid XMPP credentials required)](https://pazznetwork.github.io/ngx-chat-ghpages/)
* 🌋 build in XMPP server support
* send and receive messages, load messages from message history (XEP-0313), supports multi user chat
* 🔥 fully featured angular chat components
* 💉 open for injection
* use the server side buddy list or use your own data source for that, API methods for adding / removing buddies available
* replace the chat service with an own interface implementations to change the chat server
## Table of Contents
* Get Started
* Compatibility
* Installation and usage
* Get Help
* Documentation
* FAQ
* Get Involved
* Development
* Build the plugin
* Run the plugin tests
* Releasing
## Get Started
### Compatibility
* Angular 14 (ngx-chat 0.14.x)
* Angular 13 (ngx-chat 0.13.x)
* Angular 12 (ngx-chat 0.12.x)
* Angular 11 (ngx-chat 0.11.x)
* Angular 10 (ngx-chat 0.10.x)
* Angular 9 (ngx-chat 0.9.x)
* Angular 8 (ngx-chat 0.4.x)
* Angular 6 (ngx-chat 0.3.x)
* requires node >= 16.16 && npm >= 8.11 for build
### Installation and usage
These instructions require Angular 12.
First install ngx-chat and its dependencies via npm:
```bash
npm install --save @pazznetwork/ngx-chat @xmpp/client@~0.9.2 @angular/cdk@~14.0.5
```
After that, import ngx-chat in your root module:
```
@NgModule({
...
imports: [
...
NgxChatModule.forRoot(),
BrowserAnimationsModule, // alternatively NoopAnimationsModule
],
...
})
```
Add the `ngx-chat`-component at the end of your root component template:
```html
<ngx-chat></ngx-chat>
```
You are now ready to go. You will not see anything until you log in. Log in via `ngx-chat` wherever you want (e.g. in a component or a
service)
by injecting `ChatService` and calling `login`:
```
constructor(@Inject(CHAT_SERVICE_TOKEN) chatService: ChatService) {
chatService.logIn({
domain: 'ngx-chat.example',
service: 'wss://ngx-chat.example:5280/websocket',
password: 'password',
username: 'someuser',
});
}
```
Add the following to polyfills.ts:
```
/***************************************************************************************************
* APPLICATION IMPORTS
*/
(window as any).global = window;
```
*Optional*: body padding when roster list is expanded
Add css styling like the following to your main styles.css if you want to resize your main content when the roster is expanded.
```css
body {
transition-property: padding-right;
transition-duration: 0.4s;
padding-right: 0;
}
body.has-roster {
padding-right: 14em;
}
```
## Get Help
### Documentation
Below you will find some instructions to getting
started. [Have a look at the wiki for more FAQ's and abstract documentation.](https://github.com/pazznetwork/ngx-chat/wiki)
For a api, architecture and code overview checkout our [**
compo**doc documentation](https://pazznetwork.github.io/ngx-chat-ghpages/documentation/).
### FAQ
**Q: Which browsers are supported?**
A: It is tested in Chrome, Safari and Firefox.
**Q: Does ngx-chat work with self-signed certificates?**
A: Yes, if the following criteria are met:
* the certificate has to be trusted by the browser you are using. Chrome uses the operating system trust store for certificates while
Firefox has a custom implementation.
* the common name (CN) matches the uri of the service you are connecting to
**Q: Can ngx-chat be used without the UI?**
A: Yes. Inject the chat service via `@Inject(CHAT_SERVICE_TOKEN) public chatService: ChatService`, login via `logIn` and start sending
messages via the `sendMessage` method.
**Q: My question is not answered**
A: [No problem, feel free to raise an issue](https://github.com/pazznetwork/ngx-chat/issues/new).
## Get Involved
### Development
**WARNING**
Pay attention to your imports in the testing app:
`'@pazznetwork/ngx-chat'` instead
of `'../../../projects/pazznetwork/ngx-chat/src/lib/services/adapters/xmpp/plugins/multi-user-chat.plugin'`
**Pull requests are welcome!**
The source code for ngx-chat can be found in the `projects/pazznetwork/ngx-chat` folder. The demo application is in the `src` folder in the
project root.
```bash
# clone this repository
git clone git@github.com:pazznetwork/ngx-chat.git
cd ngx-chat
# install dependencies
npm install
# build the library continuously
ng build @pazznetwork/ngx-chat --watch
# (in another terminal) build the sample app continuously
# will run the demo application on
# http://localhost:4200
ng serve
```
### Build the plugin
`npm run build-lib`
### Test the integration of your project with the plugin
`$fileOutDirPath` is your `npm run build` out-dir path
`npm install $fileOutDirPath`
### Run the plugin tests
`npm run test:once`
### Committing
For clean and standardised commit messages we use commit lint, for the format see: https://www.conventionalcommits.org/en/v1.0.0/.
### Releasing
`npm run build-lib` is necessary because otherwise creates a package with ngcc and throws on publish the following error:
`trying to publish a package that has been compiled by ngcc`
```bash
# increment version number in projects/pazznetwork/ngx-chat/package.json
VERSION=0.14.13 # change accordingly
npm run changelog
git add .
git commit -m "docs: release $VERSION"
git tag v$VERSION
git push origin master --tags
./push-release.sh
```