[Sprint 4d]: Parameterizing URL from Filters on Graphs 🔗 - Anne & Jack

[danglorioso]

💻 Summary

For this sprint, you’ll be directly embedding the filters that are used to configure the graphs into the URL of the web app so that a specific graph can be bookmarked. Currently, every time that someone refreshes or navigates to the graphs page, the graphs are reset and therefore must be reconfigured. The objective of this sprint is to dynamically add the filters to the URL as they are selected and also extract any parameters from the URL to create the graph if they exist.

Goals of this sprint:

• Embed graph type, “measured as,” “group by,” “filter by,” and year range to the URL as users select and deselect them.
• If users attempt to go to a page with some graph configuration embedded in the URL, the parts of the configuration should be parsed from the URL and applied to the graph to create the desired graph configuration.

⚙️ Setup

Before starting:

1. Pull the latest changes from main.
2. Create a new branch for this sprint.
3. Install dependencies.
4. Run the dev server and verify the site builds.
5. Confirm everything runs.
   If you experience problems, check your .env is up to date!

🧭 Implementation

Step 1: Evaluate how the graphs can be configured.

• Currently, users can customize a graph by selecting which type of graph they want (line or bar), what they want to be measured on the graph (student count, project count, teacher count, etc.), what the data should be grouped by (region, implementation type, etc.), any filters that should be applied to the data, and the year range of the data (as configured in the top right of the graph).
• Each of these options should correspond to a part of the query parameters that are included in the URL. If one of these options is not configured (i.e. no filters are applied), then you can optionally remove it from the query parameters or include it with a value to indicate that it is not selected. Either option works as long as you configure your parser correctly and document how you do it.

Step 2: Implement parameterization logic

• Next, you should begin parameterizing the URL (meaning adding parameters to the query string) each time a user specifies an option for the graph.
• It is fine to have some form of default configuration for the graph (for example, line graph by default measuring total student count grouped by region over the past five years) as long as it makes sense (i.e., you should not have any filters enabled by default).
• How you encode these parameters in the URL is up to you, but it should be type safe.
• See nuqs documentation for how to manage query state from within your Next.js app.

Step 3: Implement parsing logic

• The next part of the sprint is to implement parsing logic for when users enter a custom URL with a graph configuration. This logic is the opposite of what your embedding logic should be. As such, it shouldn’t be too difficult to implement once you have your parameterization done.
• When loading the page, you should parse the parameters from the URL and apply them to the graph. This show all be done before showing the graph. While parameters are being parsed, you can render a skeleton of the box that will contain the graph. There are plenty of examples of skeletons in the repo.
• Again, it would make sense to have some form of default state so that when users navigate to /graphs, something useful is shown. Make sure you test this before submitting your PR.
• Here is the Next.js documentation on how to extract searchParams from the URL on a page.

Step 4: TEST

• This is the most important step of the sprint. You should test your embedder and parser thoroughly dealing with default states, combining parsing and embedding (e.g. parsing and creating a particular graph and then changing options that should be reflected in the URL), loading states, etc.
• We will be running very similar tests, so it is important that you test in detail and ensure that any minor errors are addressed.

Step 5: Connect with Share Button

• Add functionality to the existing “Share” button in the top right of the Charts page so users can click the button and copy the parametrized URL of the current graph to their clipboard (⌘ + C). Look online for docs on how to do this.

🙌 Acceptance Criteria

• Test as many combinations of parsing and embedding as you can. Full functionality is expected from the embedder/parser at the end of the ticket
• Default configuration does not include any active filters
• Test share button to ensure that the correct URL is copied to clipboard
• UI matches Figma
• Code runs locally without errors and builds successfully
• Merge via PR

⁉️ Questions

If you get stuck or have questions:

• DM Dan or Shayne on Slack
• Come to office hours or ask during a hack night
• Ask questions during team meetings – we’re here to help!

📝 Resources

• Figma:
• Tailwind CSS
• shadcn/ui
• npm package manager
• nuqs
• Next.js searchParams