Requirements:
- CKAN 2.5+
- Python 2.6 or 2.7
- JavaScript enabled in user browsers
Installation:
Activate CKAN virtualenv:
. /usr/lib/ckan/default/bin/activate
Install extension:
pip install ckanext-message
Or from source:
git clone https://github.com/yamhochi/ckanext-message.git
cd ckanext-message
python setup.py develop
Install dependencies:
pip install -r dev-requirements.txt
Add plugin to ckan.plugins in production.ini:
ckan.plugins = … message …
Restart CKAN:
sudo service apache2 reload
Configuration:
Optional configuration settings in production.ini:
Example configuration setting
(optional, default: 24)
ckanext.message.some_setting = some_default_value
Note: Specific configuration options for customizing popup behavior,
message content, and display settings should be documented in the
extension’s configuration.
Usage:
Popup Message Display:
When users attempt to download a resource:
- User clicks resource download link
- Popup message appears with configured content
- User reads message (terms, disclaimer, notice)
- User clicks acceptance button (e.g., “I Agree”, “Continue”)
- Download proceeds
Typical Use Cases:
Terms of Use:
Display licensing terms and usage conditions before download.
Ensure users acknowledge data usage restrictions.
Data Quality Notice:
Warn users about data quality issues or limitations.
Inform about data currency, accuracy, or completeness.
Privacy Disclaimer:
Notify users about personal data in datasets.
Remind users of privacy obligations.
Attribution Requirements:
Display citation requirements.
Show how to properly attribute data sources.
Format Warnings:
Warn about file size or special format requirements.
Inform about software needed to open files.
Customization:
Customize Popup Content:
Edit message templates to customize:
- Message text and formatting
- Button labels (“Accept”, “I Agree”, “Continue”, etc.)
- Popup styling (colors, size, position)
- Additional information links
Example message template:
Per-Resource Messages:
Configure different messages for different resource types:
- PDF resources: format notice
- CSV resources: encoding notice
- Large files: size warning
- Restricted data: access terms
Styling the Popup:
Customize popup appearance with CSS:
.download-message-popup {
max-width: 600px;
padding: 20px;
border: 2px solid #ccc;
border-radius: 5px;
background: white;
box-shadow: 0 4px 6px rgba(0,0,0,0.1);
}
.download-message-popup h3 {
color: #333;
margin-top: 0;
}
.download-message-popup button {
margin: 10px 5px 0 0;
}
JavaScript Behavior:
Customize popup behavior:
- Modal vs. inline display
- Auto-dismiss after time period
- Require scroll to bottom before accept
- Remember user acceptance (session/permanent)
- Track acceptance for analytics
Development:
Clone repository:
git clone https://github.com/yamhochi/ckanext-message.git
cd ckanext-message
Install for development:
python setup.py develop
pip install -r dev-requirements.txt
Create test.ini from template
Run tests:
nosetests –nologcapture –with-pylons=test.ini
Run with coverage:
pip install coverage
nosetests –nologcapture –with-pylons=test.ini –with-coverage –cover-package=ckanext.message –cover-inclusive –cover-erase –cover-tests
Troubleshooting:
Popup not appearing:
- Verify plugin is in ckan.plugins list
- Check JavaScript is enabled in browser
- Inspect browser console for errors
- Clear browser cache
- Verify templates are loading
Download proceeding without popup:
- Check JavaScript event handlers are attached
- Verify download links have correct class/attributes
- Check for JavaScript conflicts with other extensions
- Review browser console for errors
Styling issues:
- Check CSS is loading correctly
- Verify no CSS conflicts with theme
- Inspect element in browser dev tools
- Clear template cache
Mobile display problems:
- Ensure popup is responsive
- Test on various screen sizes
- Add mobile-specific CSS media queries
- Consider touch-friendly button sizes
Advanced Features:
User Acknowledgment Tracking:
Optionally track which users have acknowledged messages:
- Store acknowledgments in database
- Show popup only on first download
- Require re-acknowledgment periodically
- Track for compliance/audit purposes
Conditional Display:
Show popup based on conditions:
- User role (show for anonymous, skip for logged-in)
- Resource type (only for specific formats)
- Dataset metadata (restricted datasets only)
- User’s previous acknowledgments
Multilingual Support:
Provide translated messages:
- Use CKAN’s i18n system
- Detect user’s language preference
- Display popup in appropriate language
- Support RTL languages
Accessibility:
Ensure popup is accessible:
- Keyboard navigation support
- Screen reader compatible
- Sufficient color contrast
- Focus management
- ARIA labels and roles
Integration Examples:
With Terms of Use Extension:
Link to full terms document
Require acceptance for legal compliance
With Analytics:
Track popup views and acceptances
Monitor download conversion rates
With Access Control:
Different messages for different user roles
Integration with restricted access extensions
Best Practices:
- Keep messages concise and clear
- Use plain language
- Provide link to full terms if needed
- Make buttons clearly labeled
- Test on mobile devices
- Consider user experience
- Don’t overuse - only for important notices
- Ensure legal review for terms/disclaimers
Development Status: Beta (4)
License: AGPL v3.0 or later
Keywords: CKAN, popup, alert, download, message, disclaimer, terms
Developer: Andie Yam / Informed
Related Extensions:
- ckanext-termsofuse: Comprehensive terms management
- ckanext-reminder: User notifications
- ckanext-showcase: Data story presentation
PyPI:
Package available at:
https://pypi.python.org/pypi/ckanext-message
Install via pip:
pip install ckanext-message
CI/CD:
- Travis CI: https://travis-ci.org/yamhochi/ckanext-message
- Coveralls: https://coveralls.io/r/yamhochi/ckanext-message