README

A Drupal module that provides a dynamic special alerts feed block for Howard University websites. This module fetches real-time alerts from thedig.howard.edu and displays them as dismissible notification bars across your site.

Features
Quick Start
Documentation
Requirements
Installation
Configuration
Usage
API Reference
Styling
Troubleshooting
Contributing
License

Features

Real-time Alerts: Automatically fetches current alerts from thedig.howard.edu
Date-based Filtering: Only displays alerts that are currently active based on start/end dates
Dismissible Alerts: Users can dismiss alerts, with preferences stored in cookies
Responsive Design: Mobile-friendly alert display with responsive padding
Alert Levels: Supports different alert severity levels (low, high) with distinct styling
CORS Support: Handles cross-origin requests securely
Automatic Refresh: Loads fresh alert data on each page load
Accessibility: Screen reader friendly with proper ARIA labels

Quick Start

Install the module:

composer require howard/howard_special_alerts_feed
drush en howard_special_alerts_feed

Place the block:
- Go to Structure > Block Layout
- Find "Howard Special Alerts Feed" block
- Place it in your desired region
Verify it's working:
- Visit your site's frontend
- Check for alerts in the configured region
- Test dismissal functionality

Documentation

This README provides an overview and basic usage information. For comprehensive documentation, see:

Installation Guide - Detailed installation instructions and troubleshooting
API Documentation - Complete JavaScript and PHP API reference
Developer Guide - Development setup, customization, and contribution guidelines
Changelog - Version history and upgrade notes

Quick Links

Need help installing? → Installation Guide
Want to customize? → Developer Guide
Looking for API details? → API Documentation
Upgrading? → Changelog

Requirements

This module requires the following:

Drupal Requirements

Drupal Core: 10.x or 11.x
Modules:
- block (core module)

Server Requirements

PHP: 7.4 or higher
Network: Outbound HTTPS connections to thedig.howard.edu
CORS: Properly configured CORS headers on thedig.howard.edu

Browser Requirements

JavaScript: Modern JavaScript support (ES6+)
APIs: Fetch API support
Cookies: Cookie support for dismissal functionality

Installation

Via Composer (Recommended)

composer require howard/howard_special_alerts_feed

Manual Installation

Download the module and place it in your modules/custom/ directory
Enable the module via Drupal admin interface or Drush:

drush en howard_special_alerts_feed

Post-Installation Steps

Clear caches:
```
drush cr
```
Configure block permissions if needed

Configuration

Block Configuration

Navigate to Structure » Block Layout (/admin/structure/block)
Find the "Howard Special Alerts Feed" block
Click "Place block" in your desired region
Configure block settings:
- Visibility: Set page, role, or other visibility conditions
- Region: Choose where the block appears (typically header or content)

Block Settings

The block provides informational text and links to help documentation. No additional configuration is typically required as the module automatically:

Fetches alerts from thedig.howard.edu
Filters by current date
Handles dismissal via cookies

URL Configuration

The module is configured to fetch alerts from:

https://thedig.howard.edu/jsonapi/node/alert

With automatic filtering parameters for:

Start date ≤ current date
End date ≥ current date
Status = published

Usage

Basic Usage

Once installed and configured, the module automatically:

Fetches Alerts: On page load, queries thedig.howard.edu for active alerts
Displays Alerts: Renders alerts as notification bars
Handles Dismissal: Allows users to dismiss alerts individually
Manages Visibility: Hides dismissed alerts using cookies

Alert Structure

Each alert includes:

Title: Main alert message
Subtitle: Additional details (optional)
Link: Either to the full alert page or custom URL
Level: Alert severity (low, high)
Dates: Start and end dates for visibility

User Interaction

Viewing: Alerts appear as prominent notification bars
Dismissing: Click the X button to dismiss an alert
Persistence: Dismissed alerts remain hidden until cookies expire

API Reference

The module provides both JavaScript and PHP APIs for advanced customization.

JavaScript API

The module exposes a specialAlertsFeed object with methods for:

loadEventData() - Fetches alert data from thedig.howard.edu
checkAlerts(data, site) - Processes and filters alert data
setAlertBars(data) - Renders alerts to the page
hideAlerts() - Hides alerts when none are active
setDismiss() - Handles alert dismissal
setCookie(key, value, days) - Stores dismissal preferences
getCookie(key) - Retrieves dismissal preferences

Drupal Integration

The module integrates with Drupal through:

Block Plugin: SpecialAlertsFeedBlock class
Hooks: hook_help() and hook_theme()
Libraries: CSS and JavaScript asset management

Complete API Documentation

For detailed API documentation including parameters, return values, and examples, see the API Documentation.

Styling

CSS Classes

The module provides the following CSS classes for styling:

Container Classes

.alerts-feed-wrapper: Main container for all alerts
.alerts-active: Added to body when alerts are present
.no-alerts: Added to body when no alerts are active

Alert Classes

.newsroom-alert: Individual alert link
.newsroom-alert--low: Low severity alert
.newsroom-alert--high: High severity alert
.newsroom-alert-dismiss: Dismiss button

State Classes

.hidden: Applied to dismissed alerts

Responsive Design

The module includes responsive breakpoints:

Mobile (1px - 1000px): Adjusted padding for smaller screens
Tablet (1000px - 1700px): Percentage-based padding
Desktop (1700px+): Maximum padding for large screens

Customization

To customize alert styling:

Override CSS: Add custom styles to your theme
Template Override: Copy the Twig template to your theme
JavaScript Extension: Extend the JavaScript object for custom behavior

Example CSS customization:

/* Custom alert colors */
.alerts-feed-wrapper .newsroom-alert--low {
  background: #your-color;
}

.alerts-feed-wrapper .newsroom-alert--high {
  background: #your-urgent-color;
}

Troubleshooting

Quick Fixes

No Alerts Appearing

Check Network: Verify your server can reach thedig.howard.edu
```
curl -I https://thedig.howard.edu/jsonapi/node/alert
```
CORS Issues: Ensure CORS headers are properly configured on thedig.howard.edu
JavaScript Errors: Check browser console for JavaScript errors
Block Placement: Verify the block is placed in a visible region

Alerts Not Dismissing

Cookie Settings: Check if cookies are enabled in the browser
JavaScript Errors: Verify no JavaScript errors are preventing execution
Event Handlers: Ensure click handlers are properly attached

Complete Troubleshooting Guide

For comprehensive troubleshooting including:

Detailed diagnostic steps
Common installation issues
Performance optimization
Debug mode instructions
Server configuration problems

See the Installation Guide for complete troubleshooting documentation.

Contributing

We welcome contributions to the Howard Special Alerts Feed module!

Quick Start for Contributors

Fork the repository on GitHub
Create a feature branch from the main branch
Make your changes following our coding standards
Test thoroughly across different browsers and devices
Submit a pull request with a clear description

Development Guidelines

Follow Drupal coding standards
Add tests for new functionality
Update documentation for changes
Ensure backward compatibility

Complete Developer Guide

For comprehensive development information including:

Development Environment Setup
Module Architecture
Coding Standards
Testing Strategies
Customization Examples
Performance Optimization
Security Best Practices

See the Developer Guide for complete development documentation.

Reporting Issues

When reporting issues, please include:

Drupal version and module version
Browser and version
Steps to reproduce
Expected vs actual behavior
Any error messages or screenshots

Submit issues on GitHub Issues.

Support

Issues: GitHub Issues
Source: GitHub Repository
Maintainer: Dan Rogers
Documentation: Complete Documentation - See the docs folder for comprehensive guides

Changelog

Version 11.0.2

Comprehensive documentation suite with organized docs/ folder
Enhanced JavaScript and CSS documentation following Drupal standards
Improved code structure and error handling
Added coding standards document and developer guides

For complete version history, upgrade notes, and migration information, see the Changelog.

License

This project is licensed under the GPL-2.0+ License - see the LICENSE file for details.

howard / howard_special_alerts_feed

Maintainers

Details