Frontend Newsletter Integration
Relevant source files
The following files were used as context for generating this wiki page:The Frontend Newsletter Integration provides a client-side mechanism for users to subscribe to newsletters directly from the portfolio website. The system is designed to be lightweight, relying on a JavaScript-driven form that creates a GitHub Issue for each subscription request. This approach offloads the subscription processing to a backend system, likely powered by GitHub Actions, which listens for and processes these issues.
The integration features robust, real-time form validation, user feedback, accessibility enhancements, and optional analytics tracking. It is configured through the theme's _config.yml file and managed by the NewsletterManager class, which handles all frontend logic from rendering to submission.
Architecture and Subscription Flow
The subscription process is initiated and handled entirely on the client-side, culminating in the creation of a GitHub Issue. This decouples the frontend from the subscriber management backend.
The following diagram illustrates the high-level subscription flow:
This flow ensures a responsive user experience with immediate feedback, while using GitHub's infrastructure to handle the subscription request asynchronously.
Sources: themes/matrix-flow/source/js/newsletter.js:400-432, themes/matrix-flow/README-newsletter.md:28-39
Frontend Component: NewsletterManager
The core of the frontend logic is encapsulated within the NewsletterManager class. This class is responsible for event handling, state management, validation, and interacting with GitHub.
Sources: themes/matrix-flow/source/js/newsletter.js:6-12
Class Structure
The diagram below shows the key properties and methods of the NewsletterManager class.
Key Methods
| Method | Description |
|---|---|
init() | Initializes the component by setting up event listeners, validation, and accessibility features. |
handleSubmit(event) | The primary handler for form submission. It orchestrates validation, state changes, data collection, and issue creation. |
validateForm() | Triggers validation for all required fields (email, frequency, consent) and returns a boolean indicating validity. |
validateEmail() | Performs enhanced validation on the email field, including regex checks, typo suggestions, and checks for disposable domains. |
createGitHubIssue(formData) | Generates the GitHub issue URL with pre-filled data and opens it in a new browser tab. |
trackEvent(...) | If analytics are enabled, sends events to Google Analytics (gtag) or a custom tracker. |
Sources: themes/matrix-flow/source/js/newsletter.js
Configuration
The newsletter widget is configured via the newsletter object in the theme's _config.yml file. These values are then passed to the frontend JavaScript via a global window.NEWSLETTER_CONFIG object.
Sources: themes/matrix-flow/_config.yml:18-29, themes/matrix-flow/source/js/newsletter.js:15-32
# themes/matrix-flow/_config.yml
newsletter:
# GitHub repository for issue-based subscriptions
github_owner: thomas-iniguez-visioli
github_repo: portfolio
# Use GitHub redirect method (true) or API endpoint (false)
use_github_redirect: true
# Optional: API endpoint for backend processing
# api_endpoint: https://your-api.com/newsletter/subscribe
# Widget placement
enabled: true
position: sidebar # sidebar, footer, or header
Sources: themes/matrix-flow/_config.yml:18-29
The NewsletterManager class also defines internal configuration defaults for analytics, validation, and UI behavior, which can be overridden by the window.NEWSLETTER_CONFIG object.
Sources: themes/matrix-flow/source/js/newsletter.js:15-32
Validation Logic
Client-side validation is a key feature, providing immediate feedback to the user. It includes real-time validation on input, debouncing to prevent excessive checks, and a final validation on submission.
The validation flow for the email field is as follows:
The form fully validates the email, frequency selection, and consent checkbox before allowing submission.
Sources: themes/matrix-flow/source/js/newsletter.js:435-460
GitHub Issue Integration
The primary integration method is to redirect the user to a pre-filled GitHub Issue creation page. This avoids exposing any API tokens on the client side.
Submission Sequence
This sequence diagram shows how the frontend interacts with GitHub upon a successful form submission.
Issue Body Format
The NewsletterManager constructs a detailed Markdown body for the issue, which is then processed by the backend.
// From themes/matrix-flow/source/js/newsletter.js
generateIssueBody(formData) {
const topicsList = formData.topics.length > 0
? formData.topics.map(topic => `- [x] ${this.getTopicLabel(topic)}`).join('\\n')
: '- [ ] Aucun sujet spécifique sélectionné';
return `### Email Address
${formData.email}
### Newsletter Frequency
${formData.frequency}
### Topics of Interest
${topicsList}
### Email Format
${formData.format}
### Consent & Privacy
- [x] I consent to receiving newsletters at the provided email address
- [x] I understand that my email will be encrypted and stored securely
- [x] I understand I can unsubscribe at any time
### Additional Information (Optional)
Subscription automatique via le formulaire du site web.
Timestamp: ${formData.timestamp}`;
}
This structured format allows for easy parsing by the backend automation. The structure is confirmed by integration tests.
Sources: themes/matrix-flow/source/js/newsletter.js:534-566, newsletter-program/src/tests/integration/newsletter-subscription-flow.test.js:201-222
UI State and User Feedback
The NewsletterManager class actively manages the UI to provide clear feedback to the user.
- Loading State: The submit button is disabled, and its text changes to "Traitement..." during submission. A
.loadingclass is added to the form. - Error Handling: Network errors, rate limiting, and validation failures are caught, and user-friendly messages are displayed in the
#newsletter-messagecontainer. - Success State: Upon successful generation of the GitHub URL, the form is hidden, and a success message is displayed from the
#newsletter-successcontainer. Focus is programmatically moved to the success message title for accessibility. - Accessibility: The form is progressively enhanced. It includes
aria-liveregions for announcing status changes and errors, andaria-describedbyto link inputs with their error containers.
Sources: themes/matrix-flow/source/js/newsletter.js:176-190, themes/matrix-flow/source/js/newsletter.js:568-632