Document custom dashboard creation

[edmofro]

Issue #: N/A

Changes:

• Added a new end-user guide (packages/admin-panel/doc/customDashboardGuide.md) detailing how to create custom dashboard items in Tupaia's Admin Panel using the Visualisation Builder.
• The guide covers the full process from initial setup to placing items on a dashboard, written from an end-user perspective.
• Explicitly clarifies which tasks are achievable through the application interface and which require developer support.

---

Screenshots:

N/A

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[gemini-code-assist]

Summary of Changes

Hello @edmofro, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a comprehensive end-user guide for creating custom dashboard items within Tupaia's Admin Panel. The new documentation, located at packages/admin-panel/doc/customDashboardGuide.md, provides step-by-step instructions on utilizing the Visualisation Builder, covering everything from gaining access and defining data transformations to previewing, saving, and publishing dashboard elements. It also clearly distinguishes between actions achievable through the user interface and those requiring developer assistance, aiming to empower users while managing expectations.

Highlights

• New Documentation: A new end-user guide, customDashboardGuide.md, has been added to detail the process of creating custom dashboard items in Tupaia's Admin Panel.
• End-User Focus: The guide is written from an end-user perspective, covering the entire workflow from initial setup to placing items on a dashboard using the Visualisation Builder.
• Clarity on Capabilities: The documentation explicitly clarifies which tasks can be achieved through the application interface and which require developer support, providing clear boundaries for users.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a new user guide for creating custom dashboards in the Admin Panel. The guide is well-structured and provides clear, step-by-step instructions. My review focuses on ensuring the terminology used in the guide perfectly matches the UI elements in the application for an optimal end-user experience. I've suggested a few minor text changes to align the documentation with the field labels found in the code.

[gemini-code-assist]

The documentation mentions clicking View in Visualisation Builder to open an existing item. Based on the code in packages/admin-panel/src/routes/visualisations/dashboardItems.jsx, the link text for editing an existing item from the list is Edit using Visualisation Builder. To ensure consistency with the UI, it's best to update the text in the guide.

Suggested change

	- Go to **Visualisations → Dashboard items** and choose **Add dashboard item** (or open an existing item and click **View in Visualisation Builder**).
	- Go to **Visualisations → Dashboard items** and choose **Add dashboard item** (or open an existing item and click **Edit using Visualisation Builder**).

[gemini-code-assist]

The documentation refers to "the target projects" when creating a dashboard relation. In the UI, this field is labeled "Project codes" (as seen in packages/admin-panel/src/routes/visualisations/dashboardRelations.js). To avoid confusion for the user, it's best to use the exact terminology from the application interface.

Suggested change

	- Saving a visualisation does not automatically show it to end users. Back in **Visualisations → Dashboard relations**, create a relation that links your new dashboard item to a dashboard code, the entity types (e.g. country, facility), the permission groups, the target projects, and an optional sort order.
	- Saving a visualisation does not automatically show it to end users. Back in **Visualisations → Dashboard relations**, create a relation that links your new dashboard item to a dashboard code, the entity types (e.g. country, facility), the permission groups, the project codes, and an optional sort order.

[gemini-code-assist]

The documentation mentions setting the "root entity" for a new dashboard. The corresponding field in the UI is labeled "Organisation unit code" (as defined in packages/admin-panel/src/routes/visualisations/dashboards.js). Using the UI label will make the guide clearer for end-users.

Suggested change

	- If you also need a brand new dashboard tab, add it under **Visualisations → Dashboards** before creating the relation. Set the dashboard’s code, name, and root entity (the top-level location that owns the dashboard).
	- If you also need a brand new dashboard tab, add it under **Visualisations → Dashboards** before creating the relation. Set the dashboard’s code, name, and organisation unit code (the top-level location that owns the dashboard).