State & County Filtering
Relevant source files
The following files were used as context for generating this wiki page:
The State & County Filtering system in Actionmap provides a robust mechanism for users to narrow down geographical data, specifically for viewing political events and representatives. It encompasses both interactive map-based navigation and form-based selection lists. This functionality allows users to drill down from a national level to a specific state, and ultimately to individual counties to view localized information.
The system is built using a combination of a Ruby on Rails backend for data management and a D3.js/jQuery-powered frontend for interactive visualization and dynamic form updates. Key components include specialized JavaScript utilities for handling TopoJSON data and a unified filtering utility that manages the synchronization between state and county selection inputs.
Data Model and Backend Structure
The filtering system relies on a hierarchical relationship between State and County models. These are stored in the database with Federal Information Processing Standards (FIPS) codes to ensure standard geographical identification.
Database Schema
The database maintains the link between states and their constituent counties through a foreign key relationship.
| Table | Field | Type | Description |
|---|---|---|---|
states | id | integer | Primary key |
states | name | string | Full name of the state |
states | symbol | string | Two-letter state abbreviation (e.g., 'PA') |
states | fips_code | integer | Standard state FIPS code |
counties | id | integer | Primary key |
counties | name | string | Full name of the county |
counties | state_id | integer | Foreign key referencing states.id |
counties | fips_code | integer | Standard county FIPS code |
Sources: db/schema.rb:15-22, db/schema.rb:77-88
Map Controller Logic
The MapController handles the retrieval of state and county data for rendering. It provides methods to fetch all states for the national view, a specific state with its counties, or a single specific county.
index: Retrieves all states.state: Finds a state by its symbol and indexes its counties by FIPS code.county: Finds a specific state and county, indexing all state counties for context.
Sources: app/controllers/map_controller.rb:4-26
Frontend Architecture and Map Interaction
The frontend utilizes D3.js to render maps from TopoJSON files. The state_map_utils.js file provides the core logic for parsing geographical data and setting up interaction handlers.
Map Rendering Flow
The rendering process involves fetching a TopoJSON file, parsing it into GeoJSON features, and drawing these as SVG paths.
The diagram above represents the typical lifecycle of a state-level map initialization.
Sources: app/javascript/packs/state_map.js:8-18, app/javascript/packs/state_map_utils.js:7-53
Specialized Projections
The system uses different D3 projections depending on the geography. For instance, Alaska (AK) requires a geoConicEqualArea projection, while other states typically use a geoMercator projection fitted to the available SVG dimensions.
Sources: app/javascript/packs/state_map_utils.js:24-40
State and County Filter Utilities
The form-based filtering, primarily used on the events index page, is managed by state_county_filter_util.js. This utility ensures that when a state is selected, the corresponding counties are dynamically updated in the dependent dropdown.
Dynamic Filtering Logic
The following functions manage the UI state of the filters:
filterByChangedCallback: Toggles the visibility of the county selection list based on whether the user is filtering by state or by county.stateChangedCallback: Triggered when the state selection changes. It initiates an AJAX-style update (via a helper method not fully shown in context but implied) to populate the county dropdown.toggleSubmitButton: Ensures the submit button is only enabled when a valid selection (State or State+County) is made.
Sources: app/javascript/packs/state_county_filter_util.js
Sequence of Filter Interaction
The interaction between the user and the filter controls follows a strict sequence to maintain data integrity.
This diagram shows how selecting a state triggers a cascade of updates to the county list and submit button.
Sources: app/javascript/packs/events_index.js:15-40, app/javascript/packs/state_county_filter_util.js
Navigation and Search
The filtering system ultimately facilitates navigation to detailed data views.
- Map-to-Search: Clicking a county on a state map redirects the user to
/search?&address=[County Name]+[State Symbol]. - Form-to-Events: Selecting a specific state or county in the filter form and submitting navigates the user to filtered event results.
Sources: app/javascript/packs/state_map_utils.js:63-66, app/javascript/packs/events_index.js:42-52
Summary
State and County filtering in Actionmap integrates hierarchical database relations with interactive D3 visualizations and dynamic jQuery UI components. This multi-layered approach ensures that users can navigate geographical data through either an intuitive map interface or a standard search form, with the frontend maintaining synchronization between selections.