howard / howard_special_alerts_feed
This module is designed to provide a special alerts feed block for Howard University
Installs: 216
Dependents: 0
Suggesters: 0
Security: 0
Stars: 0
Watchers: 2
Forks: 0
Open Issues: 0
Language:JavaScript
Type:drupal-module
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.
Table of Contents
- 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.educheckAlerts(data, site)
- Processes and filters alert datasetAlertBars(data)
- Renders alerts to the pagehideAlerts()
- Hides alerts when none are activesetDismiss()
- Handles alert dismissalsetCookie(key, value, days)
- Stores dismissal preferencesgetCookie(key)
- Retrieves dismissal preferences
Drupal Integration
The module integrates with Drupal through:
- Block Plugin:
SpecialAlertsFeedBlock
class - Hooks:
hook_help()
andhook_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.