search

rpaschoal / ng-chat

💬 A simple facebook/linkedin lookalike chat module for Angular applications.
MIT License
155 stars 92 forks source link
angular angular-applications chat chat-application ng-chat

readme

⚠️ This project has been archived and is no longer maintained

ng-chat

npm npm downloads Build Status codecov

A simple facebook/linkedin lookalike chat module for Angular applications.

Buy Me A Coffee

Getting started

Installation

npm install ng-chat

Setup

Import NgChatModule on your AppModule (EG: app.module.ts):

...
import { NgChatModule } from 'ng-chat';

@NgModule({
  declarations: [
    AppComponent
  ],
  imports: [
    BrowserModule,
    FormsModule,
    HttpClientModule,
    NgChatModule
  ],
  providers: [],
  bootstrap: [AppComponent]
})
export class AppModule { }

Add the component to your AppComponent template:

<ng-chat [adapter]="adapter" [userId]="userId"></ng-chat>

And in your app.component.ts:

import { Component } from '@angular/core';
import { ChatAdapter } from 'ng-chat';
import { MyAdapter } from 'my-adapter';

@Component({
  selector: 'app-root',
  templateUrl: './app.component.html',
  styleUrls: ['./app.component.css']
})
export class AppComponent {
  title = 'app';
  userId = 999;

  public adapter: ChatAdapter = new MyAdapter();
}

Required Settings

Additional Settings

Localization

Events

Implement your ChatAdapter:

In order to instruct this module on how to send and receive messages within your software, you will have to implement your own ChatAdapter. The class that you will be implementing is the one that you must provide as an instance to the [adapter] setting of the module discussed above.

This package exposes a ChatAdapter abstract class which you can import on your new class file definition:

import { ChatAdapter } from 'ng-chat';

After importing it to your custom adapter implementation (EG: MyAdapter.ts), you must implement at least 3 methods which are abstract in the ChatAdapter base class which are:

public abstract listFriends(): Observable<ParticipantResponse[]>;

public abstract getMessageHistory(destinataryId: any): Observable<Message[]>;

public abstract sendMessage(message: Message): void;

These methods will be performed via the client integration. Apart from the client integration and actions, you must also instruct the adapter on how to receive push notifications from the server using the following methods:

public onMessageReceived(participant: IChatParticipant, message: Message): void
public onFriendsListChanged(participantsResponse: ParticipantResponse[]): void

Please note there is no need to override the 2 methods above. You must call them within your adapter implementation just to notify the module that a message was received or that the friends list was updated. The second one could be ignored if you decide to use the "pollFriendsList" feature.

If in doubt, here are 2 adapter example implementations:

Add support for group chat:

An IChatParticipant can be a User or a Group but in order to enable group chat you must implement and supply to ng-chat an instance of IChatGroupAdapter. You will have to implement the following contract:

groupCreated(group: Group): void;

ng-chat generates a guid every time a new group is created and invokes the method above so you can handle it on your application to persist the newly generated Group (Id, Participants, etc).

Once you have an implementation of IChatGroupAdapter, just supply it to your ng-chat instance:

<ng-chat [groupAdapter]="myGroupAdapterInstance" ... ></ng-chat>

File Upload:

ng-chat supports attachment of any type of files. To do so you need to implement an API endpoint on your application that can receive a POST with a form file.

On your ng-chat instance make sure you provide a valid URI for the fileUploadUrl parameter. This will enable the default file upload adapter and each chat window will render at the bottom right an attachment action which will trigger an input of type=file.

Along with a request form file ng-chat will also send a field named as ng-chat-destinatary-userid containing the id of the user in which the file will be sent to. Make sure you use this value to compose a response message as your API endpoint will have to return a FileMessage. This FileMessage instance will be sent to the destinatary user automatically by ng-chat as soon as the file upload ends successfully.

You can check some backend file upload implementation examples here:

Triggering ng-chat actions from elsewhere:

Certain ng-chat actions can be triggered from your application by using the exported IChatController interface.

Assuming you have a ng-chat instance declared on your template file, add an Angular unique identifier to it:

<ng-chat #ngChatInstance ... />

Then on your component's code, declare a ViewChild property in order to bind your ng-chat instance:

@ViewChild('ngChatInstance')
protected ngChatInstance: IChatController;

You can now trigger some ng-chat actions such as opening a chat window from elsewhere using the following code:

this.ngChatInstance.triggerOpenChatWindow(user);

Paged History Chat Adapter:

This adapter is similar to ChatAdapter but provides a pagination button to load older messages from your message history. You have to implement one additional method: getMessageHistoryByPage. You can check a sample implementation for this under the demo project with the DemoAdapterPagedHistory class.

If you like this feature and believe it should be the default behavior and implementation for ng-chat, please open an issue and vote for it here so we can potentially introduce it as the default chat adapter on subsequent versions of ng-chat.

Showing an image as a message:

If you'd like to display an image thumbnail on a chat window message just set the message type to Image. The content of the message should point to a valid image URL:

const imageMessage: Message = {
    fromId: 1,
    toId: 999,
    type: MessageType.Image,
    message: "https://valid.url/image.jpg",
    dateSent: new Date()
};

Troubleshooting

Please follow this guideline when reporting bugs and feature requests:

  1. Use GitHub Issues board to report bugs and feature requests.
  2. Please always write the steps to reproduce the error. This will make it easier to reproduce, identify and fix bugs.

Thanks for understanding!

License

The MIT License (see the LICENSE file for the full text)