jsoltys/CGW-Quote-Builder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add quote bridge and quote handoff flow

Browse Source
This commit is contained in:
jsoltys
2026-06-29 18:41:45 -05:00
parent be1475dd8e
commit a329168765
17 changed files with 1707 additions and 509 deletions
Download Patch File Download Diff File Expand all files Collapse all files
information/URL_IMPLEMENTATION_SUMMARY.md
+70 -206
View File
@@ -1,230 +1,94 @@
# Implementation Summary - URL State Management
# URL State Management
## 🎯 What You Get
## Current Status
Your application will support **shareable URLs** that preserve:
- ✅ User's navigation progress (bitwise value)
- ✅ Current question position
- ✅ Direct product links
- ✅ Browser refresh without data loss
- ✅ Browser back/forward buttons
- ✅ Copy/share functionality
URL state management is implemented in the current frontend.
## 🔗 URL Examples
The quiz now supports:
- Shareable URLs for in-progress quiz state
- Direct links to product detail views
- Browser refresh without losing the current route context
- Browser back/forward support
- Share buttons on results and product-detail views
```
# Initial state (no params)
https://yoursite.com/
## Current URL Parameters
# After selecting Door + Storm Door + Aluminum
https://yoursite.com/?b=16401&q=q-dimensions
↑ ↑
| Current question
Accumulated bit value (Door + Aluminum + Storm Door)
- `b` - accumulated bitwise state for the user selections
- `q` - current question key or `results`
- `p` - product code for direct product-detail views
# Viewing specific product
https://yoursite.com/?p=BGIST&b=16401
↑
Product code
Examples:
# Bit value 16401 decodes to:
# Bit 0 (1) = Door
# Bit 4 (16) = Aluminum
# Bit 14 (16384) = Storm Door subtype
# Total: 1 + 16 + 16384 = 16401
```text
/quiz/?b=16401&q=results
/quiz/?p=404&b=16401
/quiz/product/404
```
## 📋 Implementation Checklist
## What Is Implemented
### Phase 1: Core URL Functionality (Essential)
- [ ] Add bitwise data loading to `init()` function
- [ ] Add `accumulatedBitValue` variable
- [ ] Add `BIT_DEFINITIONS` constants
- [ ] Implement `updateURL()` function
- [ ] Implement `updateBitValue()` function
- [ ] Update `handleAnswer()` to call `updateBitValue()`
- [ ] Implement `initFromURL()` function
- [ ] Implement `restoreStateFromBitValue()` function
- [ ] Update `startOver()` to clear URL
### Core State Handling
- `accumulatedBitValue` is tracked in the frontend
- `BIT_DEFINITIONS` constants are present in `script.js`
- `product_bitwise.json` is loaded during startup
- `updateBitValue()` updates the accumulated bitmask from answer filters
- `updateURL()` writes `b` and `q` params without reloading the page
- `initFromURL()` restores the app from query params or direct product routes
- `restoreStateFromBitValue()` rebuilds the key quiz selections from the bitmask
- `startOver()` clears the URL state
### Phase 2: Product Deep Linking (Recommended)
- [ ] Implement `showProductByCode()` function
- [ ] Update `showProductDetail()` to update URL
- [ ] Make product cards clickable
- [ ] Add URL params when viewing products
### Product Deep Linking
- Product cards open detail views through `showProductByCode()`
- Product detail views push the selected product code into the URL
- Direct query-string product links are supported with `?p=<code>`
- Direct Flask routes are supported with `/quiz/product/<product_code>`
### Phase 3: Share Functionality (Nice to Have)
- [ ] Implement `shareCurrentPage()` function
- [ ] Add `showNotification()` helper
- [ ] Add "Share" buttons to UI
- [ ] Add CSS for notification animations
### Share and Navigation Support
- `shareCurrentPage()` copies the current URL to the clipboard when supported
- A notification helper is shown after successful copy
- Share buttons exist on results and product detail screens
- A `popstate` listener handles browser back/forward navigation
### Phase 4: Browser Navigation (Polish)
- [ ] Add `popstate` event listener
- [ ] Test browser back button
- [ ] Test browser forward button
- [ ] Test refresh behavior
## Implementation Notes
## 🚀 Quick Start
The current implementation restores the primary quiz state used by filtering:
- base type
- subtype
- material
- color
### Step 1: Add Global Variables
Add to top of `js/script.js`:
```javascript
let accumulatedBitValue = 0;
let bitwiseData = {};
That is enough to reopen result sets and product-detail pages consistently.
const BIT_DEFINITIONS = {
'base_door': 0, 'base_window': 1,
'material_aluminum': 4, 'material_vinyl': 5,
'color_black': 6, 'color_white': 7, 'color_bronze': 8,
'color_tan': 9, 'color_mill': 10, 'color_sandstone': 11,
'subtype_patio_door': 12, 'subtype_primary_window': 13,
'subtype_storm_door': 14, 'subtype_storm_window': 15
};
```
Dimension data is still primarily driven by the current session flow rather than fully
reconstructed from the URL alone.
### Step 2: Load Bitwise Data
Update `init()` to load `product_bitwise.json`:
```javascript
Promise.all([
fetch('data/navigation.json').then(r => r.json()),
fetch('data/products.json').then(r => r.json()),
fetch('data/accessories.json').then(r => r.json()),
fetch('data/product_bitwise.json').then(r => r.json()) // ADD THIS
])
.then(([questions, products, accessories, bitwise]) => {
// ... existing code ...
// Index bitwise data
bitwiseData = {};
bitwise.forEach(item => {
bitwiseData[item.PROD_CODE] = item.BIT_VALUE;
});
// Check for URL state
initFromURL();
});
```
## Validation Checklist
### Step 3: Add URL Functions
Copy these three key functions from [URL_STATE_MANAGEMENT.md](URL_STATE_MANAGEMENT.md):
1. `updateURL()` - Updates browser URL
2. `updateBitValue()` - Calculates bit value from selection
3. `initFromURL()` - Restores state from URL on load
- [x] Bitwise data loads at startup
- [x] URLs update as quiz answers are selected
- [x] Results pages can be shared with `b` and `q`
- [x] Product pages can be shared with `p`
- [x] Browser refresh restores route context
- [x] Browser back button is handled in code
- [x] Browser forward button is handled in code
- [ ] Full manual regression testing across all quiz paths
### Step 4: Update handleAnswer
Add one line to `handleAnswer()`:
```javascript
function handleAnswer(currentKey, answerValue, answerIndex) {
// ... existing code ...
updateBitValue(answerObject); // ADD THIS LINE
const nextKey = resolveNextQuestion(currentKey, answerValue, answerObject);
history.push(nextKey);
updateURL(nextKey); // ADD THIS LINE
loadContent(nextKey);
}
```
## Known Limits
### Step 5: Test
1. Run your app
2. Navigate through questions
3. Check URL updates after each selection
4. Copy URL and paste in new tab
5. Should restore to same state ✅
- URL restoration is designed around the current bitwise filter model, not a complete
replay of every form interaction.
- Conditional question metadata exists in the navigation data, but the frontend does
not yet use a fully generic conditional-resolution engine.
## 📖 Documentation Files
## Related Files
All details are in these files:
- **[URL_STATE_MANAGEMENT.md](URL_STATE_MANAGEMENT.md)** - Complete implementation guide
- **[REQUIRED_CODE_CHANGES.md](REQUIRED_CODE_CHANGES.md)** - Updated with URL features
- **[BITWISE_USAGE_GUIDE.md](BITWISE_USAGE_GUIDE.md)** - How bitwise system works
- `app/static/js/script.js`
- `app/data/product_bitwise.json`
- `information/BITWISE_USAGE_GUIDE.md`
- `information/REQUIRED_CODE_CHANGES.md`
## 🔧 Key Functions Reference
## Recommended Next Steps
| Function | Purpose | When Called |
|----------|---------|-------------|
| `initFromURL()` | Read URL params on page load | Once at startup |
| `updateURL()` | Write current state to URL | After each answer |
| `updateBitValue()` | Add selection to bit value | After each answer |
| `restoreStateFromBitValue()` | Decode bit value to selections | On page load from URL |
| `shareCurrentPage()` | Copy URL to clipboard | User clicks "Share" |
## 🎨 URL Format Design
### Why Bitwise?
- **Compact**: `?b=16401` vs `?door=true&aluminum=true&storm=true`
- **Fast**: Single integer comparison
- **Flexible**: Easy to add new attributes
- **Shareable**: Short URLs
- **Reversible**: Can decode back to selections
### Parameters Chosen
- `b` = bit value (short, recognizable)
- `q` = question (short, clear purpose)
- `p` = product (short, clear purpose)
### Alternative Considered
Could use hash fragments instead:
```
https://yoursite.com/#/door/storm-door/aluminum
```
But query params are better for:
- Server-side rendering
- Analytics tracking
- SEO (if products are indexed)
## ⚠️ Important Notes
1. **Bit Definitions Must Match**: The `BIT_DEFINITIONS` in JavaScript must match the Python script
2. **URL Length Limits**: URLs have practical limits (~2000 chars), but bit values are small
3. **No Sensitive Data**: Don't put sensitive info in URL (it's visible and loggable)
4. **Test Thoroughly**: Test all navigation paths and browser actions
## 🐛 Troubleshooting
### URL Not Updating
- Check `updateURL()` is called after `handleAnswer()`
- Check browser console for errors
- Verify `accumulatedBitValue` is being set
### State Not Restoring
- Check `initFromURL()` is called in `init()`
- Verify URL has `b` and `q` parameters
- Check `restoreStateFromBitValue()` logic
### Wrong Bit Values
- Verify `BIT_DEFINITIONS` matches `generate_bitwise_helper.py`
- Check `bitwise_legend.json` for correct bit positions
- Use browser console: `console.log(accumulatedBitValue)`
### Share Button Not Working
- Check clipboard API support: `navigator.clipboard`
- Fallback to `prompt()` for older browsers
- Test in HTTPS (clipboard API requires secure context)
## 📈 Benefits Summary
| Feature | User Benefit | Business Benefit |
|---------|-------------|------------------|
| Shareable URLs | Share configurations | Viral marketing |
| Bookmarks | Save favorites | Return visitors |
| Refresh-safe | No data loss | Better UX |
| Deep linking | Direct to product | SEO indexing |
| Browser nav | Back/forward works | Expected behavior |
| Short URLs | Easy to share | More sharing |
## 🎯 Next Steps
1. ✅ Implement Phase 1 (core URL functionality)
2. ✅ Test basic URL state restoration
3. ✅ Add Phase 2 (product deep linking)
4. ✅ Add Phase 3 (share buttons)
5. ✅ Add Phase 4 (browser navigation)
6. ✅ Test all scenarios thoroughly
7. ✅ Add analytics tracking (optional)
Good luck! 🚀
1. Manually test refresh and back/forward behavior on all major quiz branches.
2. Extend restoration if dimension-specific deep linking becomes a requirement.
3. Finish generic conditional navigation so URL restoration and question skipping use the same rules.