Skip to content
Snippets Groups Projects

Issue #3322482: Switch to README.md

Files
2
README.md 0 → 100644
+ 152
0
# iNotify Realtime Notifications for Drupal
## Contents Of This File
- Introduction
- How It Works
- Requirements
- Installation
- Configuration
- Getting It To Work
- Advanced Usage & Cusomization
- Maintainer
## Introduction
iNotify provides the means to display live notifications based on custom events.
## How It Works
The module provides a custom Notification entity that admins with permissions
can customize its fields and display. Notifications can be created using a
Custom Rules Action that is provided, you can trigger the action on any system
event, and fill the fields with custom data. The module uses NodeJS to
automatically refresh the notifications view whenever it's available on display.
The module also provides a notifications block to place within any region you
want.
*The module does not contain styles, only the basics. You will have to style
the block and write CSS according to your design.*
## Requirements
- [Rules](https://www.drupal.org/project/rules)
- [NodeJS Integration](https://www.drupal.org/project/nodejs)
## Installation
- Open your terminal and download with composer.
`composer require drupal/inotify`
OR
- Download the module to your `DRUPAL_ROOT/modules` directory, or where ever you
install contrib modules on your site.
- Go to `Admin > Extend` and enable the module.
## Configuration
### Enabling Node.js Integration
- Install Node.js on your server, if not installed yet. Download the installer
and follow the instructions on the Node.js website:
(https://nodejs.org/en/download/)
- Install the drupal-node.js server application and ensure that the application
is running.
Follow the instruction on GitHub: (https://github.com/beejeebus/drupal-nodejs)
- Install and enable the **Node.js integration** Drupal module on your site.
- Visit the Node.js configuration page under the Configuration menu, and enter
the connection information for your Node.js server application. The protocol,
port, and service key settings should match the settings you entered in the
config file of the Node.js server application. The host should be set to the
hostname of the server on which you installed the Node.js server application.
This host needs to be publicly accessible (i.e. "localhost" will not work).
- Visit the status page of your Drupal site and ensure that there are no errors.
Node.js should report that it has successfully connected to the Node.js
server.
Note: The Drupal module and Node.js server application are sensitive to version
numbers. The Drupal status page will show an error if the versions are not
compatible. For more information about the module, you can visit the
[Node.js Integration Modules Documentation](https://www.drupal.org/node/1713530)
## Getting It To Work
- After installation, make sure you do all the required configurations.
- Go to `admin/config/workflow/rules` and create a new reaction rule based on
whatever event you want.
- After configuring your reaction rule, make sure to add **Create Notification**
to your actions list.
you can add the title and description values within the action. When you are
done, save you rule.
- Go to your theme block layout and place the **Notifications Block** within the
intended region (usually the header), then save.
- Now you should see the block displayed in the region.To test it out, you can
trigger you reaction rule and see the notification block automatically
refreshing and displaying the new notification.
## Advanced Usage & Cusomization
### Customizing the Notification Entity
- The Notification entity provided is basically like any other content entity
within Drupal. You can visit `admin/structure/inotify_notification_settings`
and add or customize fields, alongside changing form display and content
display modes, just do with it what you do with nodes.
### Customizing the Notification View
- TODO
### Creating a Custom Rules Action
- TODO
### Creating notification programmatically
Just create the inotify_notification entity programmatically:
```
$notification = \Drupal::entityTypeManager()
->getStorage('inotify_notification')
->create({
'title' => 'Test',
'description' => 'Test description',
'target_link' => 'TEST TARGET LINK',
'uid' => 1, // The user that should recieve this notification.
});
$notification->save();
```
### Overriding Notifications Block Template
For modifing the block template, copy the template file
`templates/block--views-block--notifications-notifications-block.html.twig` to
your custome theme or custom module. You can modify the structure of the block
display, just make sure to put your HTML within the `{% block content %}` tags,
and never forget to use `{{ content }}` to render the actual view.
### Overriding Notifications Entity Template
- For modifing the Notification template, copy the template file
`templates/inotify-notification.html.twig` to your custome theme or custom
module. You can modify the structure of the notification display based on the
variable `view_mode` in case you created a view mode for the entity, you can
also use the **content** variable just like any other content entity. You can
always add more variables to the template using the hook
`template_preprocess_inotify_notification`, go to **inotify.module** file to
see how it's implemented.
### Custom CSS Styling
The included CSS file only provides a basic style to make it possible to you to
see how the module works. You should have your own CSS file within your theme or
custom module, just style the block like any other element within your theme.
## Maintainers
- Yasser Samman - https://www.drupal.org/u/yasser-samman
(https://jo.linkedin.com/in/yasseralsamman)
(y.samman@codersme.com)
- Anas Mawlawi (Anas_maw) - https://www.drupal.org/u/anas_maw
Loading