Dynamic Sidebars
Relevant source files
The following files were used as context for generating this wiki page:
- src/js/views/patients/sidebar/flow/flow-sidebar_views.js
- src/js/views/programs/sidebar/flow/flow-sidebar_views.js
- src/js/views/programs/sidebar/program/programs-sidebar_views.js
- src/js/views/patients/sidebar/flow/flow-sidebar-activity-views.js
- test/integration/clinicians/clinician-sidebar.js
- test/integration/programs/sidebar/flow-sidebar.js
Dynamic Sidebars are specialized Marionette views that provide contextual information and editing capabilities for various entities such as Patients, Flows, Actions, and Programs. These sidebars are typically anchored to the side of the main application frame, allowing users to view details, modify states, and track activity logs without leaving their current list or dashboard view.
The system utilizes a modular architecture where different sidebar views are composed of sub-views and components (e.g., NameView, DetailsView, TimestampsView) that react to model changes and user interactions. This allows for a consistent user experience while tailoring the specific fields and actions available to the type of resource being viewed.
Architectural Overview
The sidebar architecture follows standard Marionette patterns, utilizing regions to manage nested views and modelEvents to ensure the UI remains in sync with the underlying data.
Component Structure
Sidebars are divided into logical regions that handle specific data facets:
- Header/Name: Displays and allows editing of the resource name.
- Details: Provides a text area for extended descriptions or notes.
- Configuration/Status: Includes toggles for visibility (Published/Archived) or dropdowns for State and Owner.
- Activity Log: A collection-based view showing historical events related to the resource.
- Timestamps: Read-only display of creation and update times.
Sources: src/js/views/patients/sidebar/flow/flow-sidebar_views.js:84-93, src/js/views/programs/sidebar/flow/flow-sidebar_views.js:148-157
Data Flow and Synchronization
The sidebar views listen for changes on their assigned models (e.g., change:name, change:details) to trigger partial re-renders or updates to child views. When a user modifies a field, the sidebar typically triggers a save or performs a direct model update that propagates back to the server and the rest of the UI.
This diagram shows the flow from user interaction through the model to the API and back to the view.
Sources: src/js/views/patients/sidebar/flow/flow-sidebar_views.js:100-105, src/js/views/programs/sidebar/flow/flow-sidebar_views.js:180-185
Core Sidebar Implementations
Patient Flow Sidebar
The Patient Flow Sidebar focuses on the operational state of a flow within a patient's care plan. It features specialized components for FlowState and Owner management.
| View Component | Responsibility | Relevant Model Field |
|---|---|---|
NameView | Displays the flow's name. | name |
DetailsView | Displays flow descriptions or empty state. | details |
FlowStateComponent | Interactive state selection (e.g., To Do, Done). | _state |
OwnerComponent | Assigns teams or clinicians to the flow. | _owner |
ActivitiesView | Renders a list of historical events. | N/A (Collection) |
Sources: src/js/views/patients/sidebar/flow/flow-sidebar_views.js:48-81, src/js/views/patients/sidebar/flow/flow-sidebar-activity-views.js:63-65
Program and Program Flow Sidebars
Sidebar views in the "Programs" domain include management toggles for publication and archiving status, which are critical for template management.
This diagram illustrates the sequence for toggling the published status of a program.
Sources: src/js/views/programs/sidebar/program/programs-sidebar_views.js:150-162, src/js/views/programs/sidebar/flow/flow-sidebar_views.js:201-213
Key Implementation Patterns
Interaction Handling
Sidebars often use an InputWatcherBehavior to manage real-time text input and Optionlist for context menus (ellipses menus). This allows for complex behaviors like auto-resizing textareas and dropdown menus for deleting resources.
- Menu Interaction:
MenuViewtriggers a standarddeleteconfirmation modal. - Save/Cancel Logic: Views like
SaveViewandDisabledSaveViewmanage the lifecycle of an edit, disabling the save button if the model is invalid.
Sources: src/js/views/patients/sidebar/flow/flow-sidebar_views.js:33-46, src/js/views/programs/sidebar/flow/flow-sidebar_views.js:33-46, src/js/views/programs/sidebar/program/programs-sidebar_views.js:66-83
Activity Logging
The ActivitiesView for Patient Flows uses a CollectionView to render different event types (e.g., FlowProgramStarted, FlowClinicianAssigned). It uses intl (Internationalization) to generate human-readable strings based on the event source (API or System).
Sources: src/js/views/patients/sidebar/flow/flow-sidebar-activity-views.js:34-51, src/js/i18n/en-US.yml:338-360
Testing and Integration
Sidebar functionality is verified through integration tests that simulate user workflows, such as:
- Editing Clinician Details: Verifying that fields like email and role are correctly patched.
- State Transitions: Ensuring that changing a flow's state updates the UI and sends the correct payload to the API.
- Validation: Confirming that error messages (e.g., "name error") are displayed when API validation fails.
Sources: test/integration/clinicians/clinician-sidebar.js:58-95, test/integration/programs/sidebar/flow-sidebar.js:154-170, test/integration/programs/sidebar/program-sidebar.js:80-92
Conclusion
Dynamic Sidebars serve as the primary interface for detailed resource management in the RoundingWell frontend. By leveraging Marionette's region-based composition and a robust event-driven architecture, they provide a responsive and extensible way to manage complex data entities while maintaining a unified visual language across different application modules.