FAQ - hackforla/tdm-calculator GitHub Wiki

FAQ Form

• FAQ page helps user to understand the TDM website better as well as help to get answers to all frequently asked questions and if it is not answered, user can checkout guidelines page or reach us out at our feedback page.
• For browsing FAQ page, user do not need access to the website.
• Editing is only available to the admin
• Once you click on the "Edit FAQ Page" button the screen switches from screenshots 2 to 3 (below).

URLS

• Dev URL: https://tdm-dev.azurewebsites.net/faqs
• Prod URL: https://tdm.ladot.lacity.org/faqs
• GitHub location:
• Figma Design:
  • WIKI TDM Calculator Figma Pages and Structure
  • Figma [TDM Calculator Figma Pages and Structure, User-Facing Screens]
  • Figma [TDM Calculator Handoff, User-Facing Screens]

Issue label

• Issue Label on Issue tab: p-feature: FAQ screen
• Issue label on Project Board: p-feature: FAQ screen

Screen shots of page

Technical Details

Overview

The FAQ system is a React-based implementation that allows both viewing and administrative management of Frequently Asked Questions organized by categories. The system provides a dynamic, interactive user interface with drag-and-drop capabilities for reordering both categories and FAQs within each category.

Key Components Architecture

The FAQ page is built using a hierarchical component structure:

1. FaqView (FaqView.jsx) - The main container component that manages the overall state and functionality
2. FaqCategoryList (FaqCategoryList.jsx) - Renders the list of FAQ categories
3. FaqCategory (FaqCategory.jsx) - Handles individual category display and editing
4. FaqList (FaqList.jsx) - Manages the list of FAQs within a category
5. Faq (Faq.jsx) - Handles individual FAQ display and editing
6. CategoryInputContainer (CategoryInputContainer.jsx) - Provides a container wrapper for category input fields with delete and drag controls
7. CategoryInput (CategoryInput.jsx) - Manages the editable input field for category names and toggles between view/edit modes
8. FaqButtonContainer (FaqButtonContainer.jsx) - Houses the interactive buttons for each FAQ, including expand/collapse, delete, and drag controls
9. ExpandButtons (ExpandButtons.jsx) - Provides global expand/collapse functionality for all FAQs
10. NewFaqButton (NewFaqButton.jsx) - Renders the button to add a new FAQ to a category
11. NewFaqContainer (NewFaqContainer.jsx) - Manages the form interface for creating new FAQs
12. Question (Question.jsx) and Answer (Answer.jsx) components - Handle the display and editing of individual FAQs

The architecture follows a parent-child data flow pattern where state is managed at higher levels and passed down to child components via props.

State Management

The FAQ state is primarily managed in the FaqView component using React's useState hooks:

• faqCategoryList - The main state array containing all FAQ categories and their associated FAQs
• admin - Boolean flag determining if the page is in admin/edit mode
• expanded - Boolean flag tracking if all FAQs are expanded or collapsed
• formHasSaved - Boolean tracking if there are unsaved changes
• Various modal states for confirmations and warnings

Data is fetched from and saved to a backend service using the faqCategoryService methods.

Core Functionality

Viewing FAQs (User Mode)

When a user visits the FAQ page, they can:

1. View categories of FAQs
2. Expand/collapse individual FAQs by clicking on questions
3. Use "Expand All" or "Collapse All" buttons to show/hide all answers at once
4. Follow links in answers, which will open in a new tab (external links are marked with an icon)

Managing FAQs (Admin Mode)

When an administrator activates admin mode via the edit toggle button, they can:

1. Create new FAQ categories
2. Edit category names by clicking on them
3. Reorder categories via drag-and-drop
4. Delete categories
5. Add new FAQs to categories
6. Edit FAQ questions and answers
7. Reorder FAQs within and between categories via drag-and-drop
8. Delete FAQs
9. Save all changes to the backend

Rich Text Editing

The Answer component uses a Quill rich text editor to allow formatting in answers, including:

• Text styling (bold, italic, etc.)
• Links (with special handling for external links)
• Lists and other formatting options

Data Structure

The FAQ data follows this structure:

// Category structure
{
  id: Number,
  name: String,
  displayOrder: Number,
  faqs: Array // Array of FAQ objects
}

// FAQ structure
{
  id: Number,
  question: String,
  answer: String, // Can contain HTML markup
  faqCategoryId: Number,
  displayOrder: Number,
  expand: Boolean // UI state only, not stored in database
}

Drag and Drop Functionality

The system uses react-beautiful-dnd for drag-and-drop functionality:

1. Categories can be reordered via drag-and-drop
2. FAQs can be:
   • Reordered within the same category
   • Moved between categories

The DragDropContext in FaqView.jsx manages this functionality, with Droppable areas defined for both categories and FAQs.

Workflow and User Experience

User Flow

1. Users can browse categories of FAQs
2. Users can expand FAQs by clicking questions
3. Users can expand/collapse all FAQs with dedicated buttons
4. External links in answers open in new tabs

Admin Flow

1. Admin toggles edit mode with the EditToggleButton
2. Admin can add/edit/delete categories and FAQs
3. Admin can reorder items via drag-and-drop
4. When leaving edit mode:
   • Changes are submitted to the backend
   • If navigating away without saving, a confirmation dialog appears

Navigation Guards

The system uses React Router's useBlocker hook to prevent accidental navigation away from the page when there are unsaved changes. A confirmation dialog appears allowing the user to:

1. Stay on the page (to save changes)
2. Continue navigating (discarding changes)

Key Components In Detail

FaqView

The main container component that:

• Fetches and manages the FAQ data
• Handles saving changes to the backend
• Manages admin mode state
• Provides functions for managing categories and FAQs to child components
• Implements drag-and-drop context

FaqCategory

Manages a single category, including:

• Editing the category name
• Managing the FAQs within the category
• Adding new FAQs
• Handling hover states for delete functionality

Faq

Manages a single FAQ, including:

• Editing question and answer
• Expanding/collapsing
• Hover states for admin actions

Question and Answer

Handle the display and editing of individual questions and answers:

• The Question component toggles between view and edit mode
• The Answer component integrates with the Quill rich text editor
• External links in answers are transformed to open in new tabs

Technical Implementation Notes

Styling

The application uses JSS (JavaScript Style Sheets) via react-jss for styling. Styles are defined with the createUseStyles function and applied to components through the classes object.

State Propagation

The application follows a top-down state management approach where:

1. State is primarily maintained in the FaqView component
2. Update functions are passed down to child components
3. Child components call these functions to update the parent state

Form Handling

Form fields are controlled components with their values managed in React state. Changes trigger state updates, which in turn update the UI.

Rich Text Handling

The Quill editor is used for rich text editing in answers. The Interweave component is used to render HTML content safely in the view mode.

Event Handling

Event handlers throughout the application follow React's pattern of:

1. Defining handler functions
2. Passing them to components via props
3. Components invoking them in response to user interactions

Optimizations

1. useCallback is used for functions that are passed as props to prevent unnecessary re-renders
2. Component updates are minimized by careful state management
3. The application uses conditional rendering to show/hide components based on state

Backend Integration

The FAQ system integrates with backend services via:

1. faqCategoryService for fetching and saving category and FAQ data
2. Data is transformed before being sent to ensure only necessary data is included

Known Technical Considerations

1. FAQ editing in admin mode requires careful state management across multiple components
2. The Quill editor integration in the Answer component includes special handling for blur events and link transformations
3. The drag-and-drop functionality requires specific component structure for proper functioning
4. Navigation guards are implemented to prevent accidental data loss