internal/flutter_notification_center
5
0
Fork 0
mirror of https://github.com/Iconica-Development/flutter_notification_center.git synced 2025-05-18 08:33:45 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions

chore: update the documentation

Browse source
This commit is contained in:
HammadAsiif 2024-10-14 14:35:52 +02:00 committed by Freek van de Ven
parent 406589194f
commit dce9ac0b4f
1 changed files with 281 additions and 41 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

322
README.md
View file

@ -1,60 +1,300 @@
# flutter_notification_center
A Flutter package for creating notification center displaying a list of notifications.
`flutter_notification_center` is a comprehensive and flexible notification management package for Flutter applications. It allows developers to integrate real-time notifications, schedule messages, and provide an interactive notification center, with support for Firebase and local data storage. The package is highly customizable, enabling developers to adjust the UI, translate notification messages, and configure notifications to enhance user engagement.
---
## Table of Contents
- [Features](#features)
- [Getting Started](#getting-started)
- [Installation](#installation)
- [Usage](#usage)
- [Setting Up Firebase](#setting-up-firebase)
- [Configuring the Notification Center](#configuring-the-notification-center)
- [Displaying Notifications](#displaying-notifications)
- [Customization](#customization)
- [UI Customization](#ui-customization)
- [Translations](#translations)
- [API Reference](#api-reference)
- [Examples](#examples)
- [Issues](#issues)
- [Contributing](#contribute)
- [Author](#author)
---
## Features
- Notification center: A page containing a list of notifications.
- Notification bell: A clickable bell icon that can be placed anywere showing the amound of unread notifications. Clicking the bell takes the user to the notification center.
- Pinned notifications: A pinned notification can't be dismissed by the user from the notification center.
- Dismissable notifications: A dismissable notification can be dismissed by the user from the notification center.
- Notification detail page: Clicking on a notification takes the user to a notification detail page.
- Notification types: Notification types that can be created are: instant, scheduled, recurring.
- Notification popups: If a notification is pushed a popup can appear in form of a dialog or snackbar.
- **Real-time Notifications**: Fetch and display active notifications in real-time.
- **Scheduled and Recurring Notifications**: Set notifications for future delivery or create recurring notifications.
- **Interactive Notification Center**: Display notifications with interactive options to dismiss, pin, or mark them as read.
- **Customizable UI**: Adjust UI elements like icons, colors, and layout of the notification center.
- **Localization**: Easily translate notification messages for multiple languages.
- **Modular Architecture**: Compatible with Firebase and local storage solutions, allowing flexibility in backend configuration.
## Setup
---
To use this package, add `flutter_notification_center` as a dependency in your pubspec.yaml file.
## Getting Started
- Provide a `NotificationService` to the userstory to define and alter behaviour, this service accepts and `NotificationRepositoryInterface` as repository (data source)
### Core Components
1. **Notification Center**: Provides a UI for displaying notifications.
2. **Notification Bell**: Displays the count of active notifications with animation support.
3. **Notification Service**: Manages notifications, including adding, deleting, and retrieving notifications.
- For custom notification styling provide the optional notificationWidgetBuilder with your own implementation.
### Requirements
1. **Firebase**: Firebase should be initialized for storing notifications in Firestore.
2. **User Identification**: Each user requires a unique `userId` for personalized notifications.
The `NotificationConfig` has its own parameters, as specified below:
| Parameter | Explanation |
|-----------|-------------|
| seperateNotificationsWithDivider | If true notifications will be seperated with dividers within the notification center |
| translations | The translations that will be used |
| notificationWidgetBuilder | The widget that defines the styles and logic for every notification |
| enableNotificationPopups | If set to false no popups will be shown if a new notification is pushed |
| showAsSnackBar | If true notifications popups will show as snackbar. If false shown as dialog|
---
If you set `enableNotificationPopups` to true, you can use `PopupHandler` in the `newNotificationCallback` to display popups in case a new notification is pushed.
## Installation
The `notificationWidgetBuilder` expects the following parameters, as specified below:
| Parameter | Explanation |
|-----------|-------------|
| notification | The notification that is being defined |
| style | The styling that will be used for the notification |
| notificationService | The notification service that will be used |
| notificationTranslations | The translations that will be used for the notification|
| context | The provided context |
1. **Add Dependencies**: Add required dependencies in `pubspec.yaml`.
```yaml
dependencies:
firebase_notification_center_repository:
git:
url: https://github.com/Iconica-Development/flutter_notification_center.git
path: packages/firebase_notification_center_repository
ref: 5.0.0
notification_center_repository_interface:
git:
url: https://github.com/Iconica-Development/flutter_notification_center.git
path: packages/notification_center_repository_interface
ref: 5.0.0
flutter_notification_center:
git:
url: https://github.com/Iconica-Development/flutter_notification_center.git
path: packages/flutter_notification_center
ref: 5.0.0
firebase_core: ^latest_version
cloud_firestore: ^latest_version
intl: ^latest_version
```
2. **Firebase Setup**:
- Follow [Firebase setup instructions](https://firebase.google.com/docs/flutter/setup) for both Android and iOS.
- Ensure Firestore is configured with `active_notifications` and `planned_notifications` collections for immediate and scheduled notifications, respectively.
3. **Asset Configuration**:
- Some icons, like `unpin_icon.svg`, may need to be referenced in `pubspec.yaml`.
```yaml
flutter:
assets:
- assets/unpin_icon.svg
```
4. **Initialize Firebase**:
- Initialize Firebase in the `main.dart` file.
```dart
import 'package:firebase_core/firebase_core.dart';
import 'package:flutter/material.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
await Firebase.initializeApp();
runApp(MyApp());
}
```
---
## Usage
Create instant notification:
- Make a call to pushNotification() and provide a NotificationModel with the required attributes.
Create scheduled notification:
- Make a call to createScheduledNotification() and provide a NotificationModel with the required attributes + scheduledFor.
### Setting Up Firebase
Create recurring notification:
- Make a call to createRecurringNotification() and provide a NotificationModel with the required attributes and the following additional attributes:
- scheduledFor
- recurring = true
- occuringInterval with the pre defined interval (daily, weekly, monthly)
1. **Initialize FirebaseNotificationRepository**:
- This repository interacts with Firebase Firestore for managing notifications.
To create a pinned notification, set isPinned = true when creating the notification.
```dart
final notificationRepository = FirebaseNotificationRepository(
activeNotificationsCollection: "active_notifications",
plannedNotificationsCollection: "planned_notifications",
);
```
### Example
2. **Firestore Configuration**:
- Ensure Firestore is correctly set up with appropriate collections.
### Configuring the Notification Center
1. **NotificationBell Widget**:
- Displays the count of active notifications.
```dart
final notificationBell = NotificationBell(
config: NotificationConfig(),
service: notificationService, // An instance of NotificationService
onTap: () {
// Define behavior when tapped, e.g., navigate to NotificationCenter
},
);
```
2. **NotificationCenter Widget**:
- Displays a list of notifications, allowing users to interact with each one.
```dart
final notificationCenter = NotificationCenter(
config: NotificationConfig(
translations: NotificationTranslations(appBarTitle: "Notifications"),
showAsSnackBar: true,
enableNotificationPopups: true,
),
service: notificationService,
);
```
### Displaying Notifications
1. **Adding Notifications**:
- Use `addNotification` to add new notifications to the repository.
```dart
final newNotification = NotificationModel(
id: "123",
title: "New Alert",
body: "You have a new notification",
scheduledFor: DateTime.now().add(Duration(days: 1)),
);
notificationRepository.addNotification("user_id", newNotification, ["recipient_id"]);
```
2. **Streaming Notifications**:
- Use `getNotifications` to listen to real-time updates of active notifications.
```dart
notificationRepository.getNotifications("user_id").listen((notifications) {
for (var notification in notifications) {
print(notification.title);
}
});
```
3. **Deleting Notifications**:
- Remove a notification by calling `deleteNotification`.
```dart
notificationRepository.deleteNotification("user_id", "notification_id", false);
```
---
## Customization
### UI Customization
1. **Notification Bell Styling**:
- Customize the `NotificationBell` appearance with `AnimatedNotificationBellStyle`.
```dart
final notificationBell = NotificationBell(
animatedIconStyle: AnimatedNotificationBellStyle(
color: Colors.blue,
size: 24,
),
onTap: () { /* Navigate to NotificationCenter */ },
);
```
2. **Notification Display Layout**:
- Customize the `NotificationCenter` layout with `NotificationConfig`, adjusting elements like the app bar title, icon color, and UI interactions.
```dart
final notificationConfig = NotificationConfig(
showAsSnackBar: true,
enableNotificationPopups: true,
pinnedIconColor: Colors.green,
);
```
### Translations
1. **Localized Translations**:
- `NotificationTranslations` provides customizable text for various notification messages.
```dart
final translations = NotificationTranslations(
appBarTitle: "Mis Notificaciones",
notificationDismissed: "Notificación descartada",
notificationPinned: "Notificación fijada",
notificationUnpinned: "Notificación desmarcada",
);
final notificationConfig = NotificationConfig(translations: translations);
```
2. **Dialog Customization**:
- Adjust dialog text within `NotificationDialog` using custom translations, ideal for supporting multiple languages.
---
## API Reference
### Classes
- **NotificationService**: Manages notifications, with methods for adding, updating, deleting, and scheduling.
- **NotificationModel**: Represents a notification structure with fields like `id`, `title`, `body`, and `scheduledFor`.
- **NotificationConfig**: Customization class for notifications, allowing display options like snackbar or dialog.
- **NotificationRepositoryInterface**: Defines the required methods for a notification repository, enabling various backend implementations.
- **LocalNotificationRepository**: In-memory implementation, useful for testing.
### Key Methods
- `addNotification(userId, notification, recipientIds)`: Adds a new notification.
- `deleteNotification(userId, id, planned)`: Deletes a notification.
- `getNotifications(userId)`: Streams active notifications.
- `getPlannedNotifications(userId)`: Streams scheduled notifications.
- `updateNotification(userId, notification)`: Updates an existing notification.
---
## Examples
### Basic Usage
```dart
final firebaseRepo = FirebaseNotificationRepository();
final notification = NotificationModel(
id: "notif_01",
title: "Welcome!",
body: "Thank you for signing up.",
scheduledFor: DateTime.now().add(Duration(hours: 1)),
);
// Adding a notification
await firebaseRepo.addNotification("user_123", notification, ["user_123"]);
// Listening to active notifications
firebaseRepo.getNotifications("user_123").listen((notifications) {
notifications.forEach((notif) => print(notif.title));
});
```
---
### Advanced Usage With Custom Translations
```dart
final translations = NotificationTranslations(
appBarTitle: "My Custom Notifications",
noNotifications: "No notifications at this time.",
);
final notificationConfig = NotificationConfig(
translations: translations,
showAsSnackBar: true,
);
// Using the config in a custom notification center setup
final notificationCenter = NotificationCenter(
config: notificationConfig,
service: firebaseRepo,
);
```
See [Example Code](example/lib/main.dart) for more info.
@ -62,7 +302,7 @@ See [Example Code](example/lib/main.dart) for more info.
Please file any issues, bugs or feature request as an issue on our [GitHub](https://github.com/Iconica-Development/flutter_notification_center/pulls) page. Commercial support is available if you need help with integration with your app or services. You can contact us at [support@iconica.nl](mailto:support@iconica.nl).
## Want to contribute
## Contribute
If you would like to contribute to the plugin (e.g. by improving the documentation, solving a bug or adding a cool new feature), please carefully review our [contribution guide](./CONTRIBUTING.md) and send us your [pull request](https://github.com/Iconica-Development/flutter_notification_center/pulls).