forked from jsnbuchanan/crowd-funder-for-time-pwa
3d124e13bb
- Add NOTIFY_CONTACT_LOADING_ISSUE, NOTIFY_FEED_LOADING_ISSUE, and NOTIFY_CONFIRMATION_ERROR constants to notifications.ts - Update HomeView.vue to import and use notification constants instead of literal strings - Update migration templates to document constants vs literal strings pattern - Add comprehensive documentation for notification constants usage Ensures consistency with established pattern used in ActivityListItem.vue and other migrated components. Linter passes without errors.
119 lines
3.9 KiB
Markdown
119 lines
3.9 KiB
Markdown
# HomeView.vue Notification Constants Migration
|
|
|
|
## Overview
|
|
This document describes the proper pattern for using notification constants in TimeSafari migrations, demonstrated through the HomeView.vue migration.
|
|
|
|
## Pattern: Constants vs Literal Strings
|
|
|
|
### Use Constants For
|
|
- **Static, reusable messages** that appear in multiple components
|
|
- **Standard user-facing notifications** with consistent wording
|
|
- **Error messages** that are used across the application
|
|
|
|
### Use Literal Strings For
|
|
- **Dynamic messages** with variables or user input
|
|
- **Contextual error messages** that include specific details
|
|
- **Messages that are truly one-off** and unlikely to be reused
|
|
|
|
## Implementation Example
|
|
|
|
### 1. Define Constants in `src/constants/notifications.ts`
|
|
```typescript
|
|
export const NOTIFY_CONTACT_LOADING_ISSUE = {
|
|
title: "Contact Loading Issue",
|
|
message: "Some contact information may be unavailable.",
|
|
};
|
|
|
|
export const NOTIFY_FEED_LOADING_ISSUE = {
|
|
title: "Feed Loading Issue",
|
|
message: "Some feed data may be unavailable. Pull to refresh.",
|
|
};
|
|
|
|
export const NOTIFY_CONFIRMATION_ERROR = {
|
|
title: "Error",
|
|
message: "There was a problem submitting the confirmation.",
|
|
};
|
|
```
|
|
|
|
### 2. Import Constants in Component
|
|
```typescript
|
|
import {
|
|
NOTIFY_CONTACT_LOADING_ISSUE,
|
|
NOTIFY_FEED_LOADING_ISSUE,
|
|
NOTIFY_CONFIRMATION_ERROR,
|
|
} from "@/constants/notifications";
|
|
```
|
|
|
|
### 3. Use Constants in Notification Calls
|
|
```typescript
|
|
// ✅ CORRECT - Using constants for static messages
|
|
this.notify.warning(
|
|
NOTIFY_CONTACT_LOADING_ISSUE.message,
|
|
TIMEOUTS.LONG
|
|
);
|
|
|
|
// ✅ CORRECT - Using literal strings for dynamic messages
|
|
this.notify.error(
|
|
userMessage || "There was an error loading your data. Please try refreshing the page.",
|
|
TIMEOUTS.LONG
|
|
);
|
|
```
|
|
|
|
## Benefits
|
|
|
|
### Consistency
|
|
- Ensures consistent wording across the application
|
|
- Reduces typos and variations in messaging
|
|
- Makes UI text easier to review and update
|
|
|
|
### Maintainability
|
|
- Changes to notification text only need to be made in one place
|
|
- Easier to track which messages are used where
|
|
- Better support for future internationalization
|
|
|
|
### Type Safety
|
|
- TypeScript can catch missing constants at compile time
|
|
- IDE autocompletion helps prevent errors
|
|
- Structured approach to notification management
|
|
|
|
## Migration Checklist
|
|
|
|
When migrating notifications to use constants:
|
|
|
|
1. **Identify reusable messages** in the component
|
|
2. **Add constants** to `src/constants/notifications.ts`
|
|
3. **Import constants** in the component
|
|
4. **Replace literal strings** with constant references
|
|
5. **Preserve dynamic messages** as literal strings
|
|
6. **Test notifications** to ensure they still work correctly
|
|
|
|
## Examples From HomeView.vue
|
|
|
|
| Type | Message | Constant Used |
|
|
|------|---------|---------------|
|
|
| Warning | "Some contact information may be unavailable." | `NOTIFY_CONTACT_LOADING_ISSUE.message` |
|
|
| Warning | "Some feed data may be unavailable. Pull to refresh." | `NOTIFY_FEED_LOADING_ISSUE.message` |
|
|
| Error | "There was a problem submitting the confirmation." | `NOTIFY_CONFIRMATION_ERROR.message` |
|
|
| Dynamic | `userMessage \|\| "fallback message"` | *(literal string - dynamic content)* |
|
|
|
|
## Best Practices
|
|
|
|
1. **Use descriptive constant names** that clearly indicate the message purpose
|
|
2. **Group related constants** together in the notifications file
|
|
3. **Include both title and message** in constant objects for consistency
|
|
4. **Document why** certain messages remain as literal strings (dynamic content)
|
|
5. **Consider future reusability** when deciding whether to create a constant
|
|
|
|
## Integration with Existing Pattern
|
|
|
|
This approach builds on the existing notification helper pattern:
|
|
- Still uses `createNotifyHelpers()` for method abstraction
|
|
- Still uses `TIMEOUTS` constants for consistent timing
|
|
- Adds message constants for better content management
|
|
- Maintains compatibility with existing notification infrastructure
|
|
|
|
## Author
|
|
Matthew Raymer
|
|
|
|
## Date
|
|
2024-01-XX |