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
Environment Switching: Block-level Production/Staging toggle for testing alerts before they go live, proxied server-side through Drupal (no CORS/CSP changes needed)
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
Same-Origin Requests: The browser only ever talks to your own site (via a Drupal proxy route) - no CORS configuration required
Automatic Refresh: Loads fresh alert data on each page load, with a short (60s) server-side cache to protect the upstream API
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 (made server-side by Drupal, not the browser)

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, plus an Environment setting:

Environment: Production (default) or Staging. Choose which thedig.howard.edu environment to pull alerts from - normally this should be "Production" unless you are testing alerts on another environment. Existing block placements that predate this setting automatically default to "Production", no action required.

Beyond that, no additional configuration is typically required as the module automatically:

Fetches alerts from thedig.howard.edu (or stg.thedig.howard.edu, if Staging is selected)
Filters by current date
Handles dismissal via cookies

URL Configuration

The browser never calls thedig.howard.edu directly. Instead, alerts-feed.js fetches from this site's own proxy route:

/howard-special-alerts-feed/proxy

which forwards the request server-side to the configured environment:

https://thedig.howard.edu/jsonapi/node/alert          (Production)
https://stg.thedig.howard.edu/jsonapi/node/alert      (Staging)

This exists because stg.thedig.howard.edu requires Shield HTTP basic auth and currently has a certificate that doesn't match its hostname - neither of which a browser fetch() can work around, but a server-side Guzzle request can. The proxy response is cached for 60 seconds (keyed by environment) so alerts still appear/disappear promptly as their date ranges start/end, without hammering the upstream API on every page view.

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 via this site's /howard-special-alerts-feed/proxy route, using the block's configured environment (drupalSettings.howard_special_alerts_feed.environment)
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 - configuration form (Environment select), passes settings to drupalSettings
Controller: AlertsProxyController - proxies JSON:API requests to the configured thedig.howard.edu environment server-side
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 Drupal server (not the browser) can reach thedig.howard.edu
```
curl -I https://thedig.howard.edu/jsonapi/node/alert
```
Proxy Route: Confirm /howard-special-alerts-feed/proxy returns a 200 response and valid JSON - if Staging is selected, this route also needs to reach stg.thedig.howard.edu (Shield basic auth is handled automatically)
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

Package info

Security

Statistics