Add admin dashboard setup wizard for first-time system configuration by DawoudIO · Pull Request #7698 · ChurchCRM/CRM

DawoudIO · 2025-12-01T02:37:56Z

What Changed

Create admin dashboard at /admin route with Slim4 MVC pattern
Add 7-step quick start setup checklist with direct links to key config pages
Display system health indicators (file integrity, orphaned files)
Show system info (version, database, admin tools)
Implement demo data import with Sunday School selected by default
Add 'Admin Dashboard' menu entry as first item in Admin menu
Redirect fresh installs to /admin dashboard instead of /v2/dashboard
Remove import demo data from system maintenance page
Follow project standards: use Propel ORM, Slim4 routing, Bootstrap 4.6.2, gettext() localization

Type

Screenshots

Security Check

Introduces new input validation
Modifies authentication/authorization
Affects data privacy/GDPR

Code Quality

Database: Propel ORM only, no raw SQL
No deprecated attributes (align, valign, nowrap, border, cellpadding, cellspacing, bgcolor)
Bootstrap CSS classes used
All CSS bundled via webpack

Pre-Merge

Tested locally
No new warnings
Build passes
Backward compatible (or migration documented)

- Create admin dashboard at /admin route with Slim4 MVC pattern - Add 7-step quick start setup checklist with direct links to key config pages - Display system health indicators (file integrity, orphaned files) - Show system info (version, database, admin tools) - Implement demo data import with Sunday School selected by default - Add 'Admin Dashboard' menu entry as first item in Admin menu - Redirect fresh installs to /admin dashboard instead of /v2/dashboard - Remove import demo data from system maintenance page - Follow project standards: use Propel ORM, Slim4 routing, Bootstrap 4.6.2, gettext() localization

…version

Copilot

Pull request overview

This PR introduces a new admin dashboard at /admin designed to guide administrators through first-time system setup. The dashboard provides a 7-step setup wizard, system health monitoring, and a demo data import feature. Fresh installations (with only 1 person record) are automatically redirected from /v2/dashboard to this new admin dashboard.

Key Changes:

New admin dashboard with quick-start checklist linking to essential configuration pages
System health indicators showing file integrity and orphaned files status
Demo data import feature moved from system maintenance to admin dashboard
Automatic redirect for fresh installations to streamline onboarding

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 10 comments.

Show a summary per file

File	Description
`webpack/admin-dashboard.js`	JavaScript for tooltip initialization and smooth scrolling behavior on the admin dashboard
`webpack/admin-dashboard.css`	Custom styling for dashboard cards, badges, and interactive elements
`webpack.config.js`	Adds `admin-dashboard` entry point to webpack configuration
`src/v2/templates/root/dashboard.php`	Removes demo data import banner from main dashboard (moved to admin dashboard)
`src/v2/routes/root.php`	Adds redirect logic for admin users with no people to new admin dashboard
`src/skin/js/importDemoData.js`	Updates demo data options: disables financial/events, enables Sunday School by default
`src/admin/views/system-maintenance.php`	Removes import demo data button (functionality moved to admin dashboard)
`src/admin/views/dashboard.php`	New admin dashboard template with setup wizard, health monitoring, and system info
`src/admin/routes/dashboard.php`	Slim4 route handler for `/admin` root path
`src/admin/index.php`	Registers new dashboard route in admin router
`src/ChurchCRM/Config/Menu/Menu.php`	Adds "Admin Dashboard" menu item as first entry in Admin menu

Copilot · 2025-12-01T02:41:59Z

src/admin/views/dashboard.php

+                </div>
+                <div class="card-body">
+                    <p><?= gettext('Import sample families, people, groups and optional events/financial records so you can explore ChurchCRM populated with realistic data.') ?></p>
+                    <button type="button" id="importDemoDataV2" class="btn btn-success btn-lg w-100">


The w-100 class is a Bootstrap 5 utility class. According to the coding guidelines, this project uses Bootstrap 4.6.2 and must not use Bootstrap 5 classes. Replace w-100 with btn-block for full-width buttons in Bootstrap 4.6.2.

For example, line 133 should be:

<button type="button" id="importDemoDataV2" class="btn btn-success btn-lg btn-block">

Apply the same change to lines 162, 174, and 209.

Copilot · 2025-12-01T02:41:59Z

src/admin/views/dashboard.php

+                    <?php endif; ?>
+
+                    <hr class="my-3">
+                    <a href="<?= SystemURLs::getRootPath() ?>/admin/system/debug" class="btn btn-sm btn-outline-secondary w-100">


The w-100 class is a Bootstrap 5 utility class. Replace with btn-block for full-width buttons in Bootstrap 4.6.2.

Copilot · 2025-12-01T02:41:59Z

src/admin/views/dashboard.php

+                            </div>
+                        </li>
+                        <li class="mt-3">
+                            <a href="https://github.com/ChurchCRM/CRM/wiki" target="_blank" rel="noopener noreferrer" class="btn btn-sm btn-outline-info w-100">


The w-100 class is a Bootstrap 5 utility class. Replace with btn-block for full-width buttons in Bootstrap 4.6.2.

Copilot · 2025-12-01T02:42:00Z

src/admin/views/dashboard.php

+                        </li>
+                        <li class="mb-3">
+                            <strong><?= gettext('Admin Tools:') ?></strong><br>
+                            <div class="btn-group w-100 mt-2" role="group">


The w-100 class is a Bootstrap 5 utility class. For btn-group, consider using Bootstrap 4.6.2's d-flex class instead to achieve full width, or restructure without w-100.

Copilot · 2025-12-01T02:42:00Z

webpack/admin-dashboard.js

+document.addEventListener('DOMContentLoaded', function () {
+    // Initialize tooltips if Bootstrap is available
+    if (typeof bootstrap !== 'undefined') {
+        const tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'));


Bootstrap 5 uses data-bs-toggle for tooltips, but Bootstrap 4.6.2 uses data-toggle. This code checks for [data-bs-toggle="tooltip"] which is the Bootstrap 5 syntax. Change to [data-toggle="tooltip"] to match Bootstrap 4.6.2. Additionally, verify that the tooltip API is compatible with Bootstrap 4.6.2 (should be new bootstrap.Tooltip() or jQuery's $().tooltip()).

Copilot · 2025-12-01T02:42:00Z

webpack/admin-dashboard.css

+.list-group-item .badge {
+    min-width: 2.5rem;
+    height: 2.5rem;
+    display: flex;


[nitpick] The CSS property display: flex on .badge (line 33) may not render correctly for badges in Bootstrap 4.6.2. Badges are inline elements by default. If flex layout is needed for the badge content, consider using display: inline-flex instead to maintain inline flow while enabling flexbox for children.

Suggested change

display: flex;

display: inline-flex;

Copilot · 2025-12-01T02:42:01Z

webpack/admin-dashboard.css

+
+.card:hover {
+    transform: translateY(-2px);
+    box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15) !important;


[nitpick] The !important flag on box-shadow should generally be avoided unless absolutely necessary to override other styles. Consider removing it and ensuring proper CSS specificity instead. If this is needed to override Bootstrap's default card hover styles, add a comment explaining why.

Suggested change

box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15) !important;

box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);

Copilot · 2025-12-01T02:42:01Z

src/admin/views/dashboard.php

+                        <p class="mb-2"><strong><?= gettext('Orphaned Files:') ?></strong></p>
+                        <span class="badge bg-danger"><?= count($orphanedFiles) ?> <?= gettext('files') ?></span>
+                        <p class="text-muted small mt-2"><?= gettext('Orphaned files may pose security risks.') ?></p>
+                        <a href="<?= SystemURLs::getRootPath() ?>/admin/system/orphaned-files" class="btn btn-sm btn-outline-danger w-100 mt-2">


The w-100 class is a Bootstrap 5 utility class. Replace with appropriate Bootstrap 4.6.2 approach. For buttons, use btn-block. For btn-group, you can use d-flex instead of w-100 if you want it to stretch to full width.

Copilot · 2025-12-01T02:42:01Z

src/v2/routes/root.php

        ->count();

+    // Redirect admin users with no people to the setup dashboard
+    if (AuthenticationManager::getCurrentUser()->isAdmin() && $dashboardCounts['People'] == 1) {


Use strict equality comparison (===) instead of loose equality (==) for type-safe comparison. This ensures the comparison checks both value and type, preventing unexpected behavior when $dashboardCounts['People'] is a string "1" vs integer 1.

Suggested change

if (AuthenticationManager::getCurrentUser()->isAdmin() && $dashboardCounts['People'] == 1) {

if (AuthenticationManager::getCurrentUser()->isAdmin() && $dashboardCounts['People'] === 1) {

Copilot · 2025-12-01T02:42:02Z

src/admin/views/dashboard.php

+
+// Get system status info
+$integrityStatus = AppIntegrityService::getIntegrityCheckStatus();
+$integrityPassed = $integrityStatus === gettext('Passed');


Comparing $integrityStatus directly to gettext('Passed') is fragile because it relies on the translated string value. If the language changes or the translation is modified, this comparison will fail. Consider having AppIntegrityService::getIntegrityCheckStatus() return a boolean or constant value instead of a translated string, or compare against the English constant before translation.

Suggested change

$integrityPassed = $integrityStatus === gettext('Passed');

$integrityPassed = $integrityStatus === 'Passed';

- Move Restore Database and Reset Database cards from maintenance page to dashboard - Add Advanced Operations section below main dashboard content - Update menu: System Maintenance now points to admin dashboard - Remove /admin/system/maintenance route and view file - Update redirect links in orphaned-files and system-reset to go to dashboard - All system admin tools now accessible from single dashboard page

…Dashboard

- Replace numbered list with responsive 6-card grid layout - Reorder cards: Settings, Users, Groups, Sunday School, Import, Funds - Add Force Import functionality when initial import fails - Display inline error messages with clear formatting - Fix force parameter name to match API (force vs forceImport) - Update references from System Maintenance to Admin Dashboard - Compact CSS styling for better visual hierarchy

- Test dashboard page loads and displays key sections - Verify all 6 Quick Start cards are present - Verify System Info, System Health, Demo Data cards - Test Import Demo Data overlay opens and cancels correctly - Test navigation from Quick Start cards to target pages

- Replace Bootstrap 5 w-100 utility with Bootstrap 4.6.2 btn-block for full-width buttons - Use d-flex flex-fill for btn-group layout instead of w-100 - Fix Bootstrap tooltip syntax from data-bs-toggle (v5) to data-toggle (v4.6.2) - Use jQuery $().tooltip() instead of bootstrap.Tooltip() for Bootstrap 4.6.2 - Use strict equality === instead of == for type-safe comparison - Compare integrity status to 'Passed' instead of gettext('Passed') to avoid i18n issues

DawoudIO added this to the 6.3.0 milestone Dec 1, 2025

Copilot AI review requested due to automatic review settings December 1, 2025 02:37

DawoudIO requested a review from a team as a code owner December 1, 2025 02:37

DawoudIO added the Installation / Upgrade label Dec 1, 2025

DawoudIO requested review from DAcodedBEAT, MrClever, bigtigerku, grayeul and respencer and removed request for a team December 1, 2025 02:37

Copilot started reviewing on behalf of DawoudIO December 1, 2025 02:38 View session

Reorganize sidebar: move System Info to top and remove v prefix from …

0f18007

…version

Copilot finished reviewing on behalf of DawoudIO December 1, 2025 02:41

Copilot AI reviewed Dec 1, 2025

View reviewed changes

DawoudIO added 6 commits November 30, 2025 18:42

Remove System Maintenance menu item - all functionality now in Admin …

3a9e398

…Dashboard

Update messages.po

99b74c3

DawoudIO merged commit d5c36d5 into master Dec 1, 2025
7 checks passed

DawoudIO deleted the feature/admin-dashboard-setup-wizard branch December 1, 2025 03:41

DawoudIO mentioned this pull request Dec 1, 2025

Add a guided tour for 1st login #5345

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add admin dashboard setup wizard for first-time system configuration#7698

Add admin dashboard setup wizard for first-time system configuration#7698
DawoudIO merged 8 commits intomasterfrom
feature/admin-dashboard-setup-wizard

DawoudIO commented Dec 1, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Copilot AI Dec 1, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15) !important;
	box-shadow: 0 0.5rem 1rem rgba(0, 0, 0, 0.15);

	if (AuthenticationManager::getCurrentUser()->isAdmin() && $dashboardCounts['People'] == 1) {
	if (AuthenticationManager::getCurrentUser()->isAdmin() && $dashboardCounts['People'] === 1) {

	$integrityPassed = $integrityStatus === gettext('Passed');
	$integrityPassed = $integrityStatus === 'Passed';

Uh oh!

Conversation

DawoudIO commented Dec 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What Changed

Type

Screenshots

Security Check

Code Quality

Pre-Merge

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

DawoudIO commented Dec 1, 2025 •

edited

Loading