forked from jsnbuchanan/crowd-funder-for-time-pwa
db5da0cdfc
- Create logical sub-folder classification for all documentation - Organize 91 migration files into component-specific folders - Separate user guides, build system, migration, and development docs - Maintain maximum 7 items per folder for easy navigation - Add comprehensive README and reorganization summary - Ensure all changes tracked in git with proper versioning Structure: - user-guides/ (3 items): user-facing documentation - build-system/ (3 items): core, platforms, automation - migration/ (6 items): assessments, testing, templates - development/ (4 items): tools and standards - architecture/, testing/, examples/ (ready for future docs) Total: 24 folders created, all within 7-item limits
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 |