Step-wise Setup Wizard

src/app/core/admin/admin-entity-details/admin-entity-details/admin-entity-details.component.html

@@ -1,6 +1,12 @@
 <app-view-title [disableBackButton]="true" [displayInPlace]="true">
   &lt;Name of displayed {{ this.entityConstructor?.label }}&gt;
 </app-view-title>
+<p i18n>
+  You can edit how users will see the details of a single record of this type.
+  Drag and drop fields and sections in this preview of a profile view and group
+  them as appropriate. We recommend to keep things simple: Only add fields that
+  you really need for your work.
+</p>
 
 <app-admin-tabs [tabs]="config?.panels" [newTabFactory]="newPanelFactory">
   <ng-template [appAdminTabTemplate]="config?.panels" let-item>

src/app/core/admin/admin-entity/admin-entity-general-settings/admin-entity-general-settings.component.html

@@ -15,8 +15,8 @@ <h2 i18n>General Settings of "{{ entityConstructor.label }}" Records</h2>
           </mat-form-field>
 
           <mat-form-field floatLabel="always">
-            <mat-label i18n>
-              Label (Plural)
+            <mat-label>
+              <span i18n>Label (Plural)</span>
               <fa-icon
                 icon="question-circle"
                 matTooltip="Optionally you can define how multiple records of this entity should be called, e.g. in lists."
@@ -31,8 +31,8 @@ <h2 i18n>General Settings of "{{ entityConstructor.label }}" Records</h2>
           </mat-form-field>
 
           <mat-form-field floatLabel="always">
-            <mat-label i18n>
-              Icon
+            <mat-label>
+              <span i18n>Icon</span>
               <fa-icon
                 icon="question-circle"
                 matTooltip="The icon to represent this entity type, e.g. when displaying records as a small preview block. [see fontawesome.com/icons]"
@@ -49,8 +49,8 @@ <h2 i18n>General Settings of "{{ entityConstructor.label }}" Records</h2>
 
         <div class="entity-form-cell">
           <mat-form-field>
-            <mat-label i18n>
-              Generated Title of Record
+            <mat-label>
+              <span i18n>Generated Title of Record</span>
               <fa-icon
                 icon="question-circle"
                 matTooltip="Select the fields that should be used (in that order) to generate a simple name/title for a record. This generated title is used in previews, search and for form fields that allow to select a record of this type. (Only text fields can be used here)"

src/app/core/admin/admin-entity/admin-entity.component.ts

@@ -64,7 +64,7 @@ export class AdminEntityComponent implements OnInit {
   configDetailsView: EntityDetailsConfig;
   configListView: EntityListConfig;
   configEntitySettings: EntityConfig;
-  protected mode: "details" | "list" | "general" = "list";
+  protected mode: "details" | "list" | "general" = "details";
 
   @ContentChild(TemplateRef) templateRef: TemplateRef<any>;
 

src/app/core/admin/admin.routing.ts

@@ -5,6 +5,7 @@ import { ConfigImportComponent } from "../../features/config-setup/config-import
 import { ConflictResolutionListComponent } from "../../features/conflict-resolution/conflict-resolution-list/conflict-resolution-list.component";
 import { UserRoleGuard } from "../permissions/permission-guard/user-role.guard";
 import { EntityPermissionGuard } from "../permissions/permission-guard/entity-permission.guard";
+import { SetupWizardComponent } from "./setup-wizard/setup-wizard.component";
 
 export const adminRoutes: Routes = [
   {
@@ -15,6 +16,10 @@ export const adminRoutes: Routes = [
       permittedUserRoles: ["admin_app"],
     },
   },
+  {
+    path: "setup-wizard",
+    component: SetupWizardComponent,
+  },
   {
     path: "entity/:entityType",
     component: RoutedViewComponent,

src/app/core/admin/admin/admin.component.html

@@ -16,6 +16,10 @@ <h2>Shortcuts</h2>
   <mat-list-item [routerLink]="['/admin/conflicts']" i18n="admin menu item">
     Database Conflicts
   </mat-list-item>
+
+  <mat-list-item [routerLink]="['/admin/setup-wizard']" i18n="admin menu item">
+    Setup Wizard
+  </mat-list-item>
 </mat-nav-list>
 
 <hr />

src/app/core/admin/setup-wizard/setup-wizard-button/setup-wizard-button.component.html

@@ -0,0 +1,13 @@
+@if (showSetupWizard) {
+  <button
+    mat-flat-button
+    routerLink="/admin/setup-wizard"
+    class="button"
+    color="accent"
+    style="border-radius: 0"
+    i18n
+  >
+    <fa-icon icon="person-digging"></fa-icon>
+    Setup Wizard
+  </button>
+}

src/app/core/admin/setup-wizard/setup-wizard-button/setup-wizard-button.component.scss

@@ -0,0 +1,7 @@
+
+.button {
+  border-top: solid 1px rgba(0, 0, 0, 0.12);
+  border-radius: 0;
+  overflow: hidden;
+  width: 100%;
+}

src/app/core/admin/setup-wizard/setup-wizard-button/setup-wizard-button.component.spec.ts

@@ -0,0 +1,27 @@
+import { ComponentFixture, TestBed } from "@angular/core/testing";
+
+import { SetupWizardButtonComponent } from "./setup-wizard-button.component";
+import { EntityMapperService } from "../../../entity/entity-mapper/entity-mapper.service";
+import { mockEntityMapper } from "../../../entity/entity-mapper/mock-entity-mapper-service";
+
+describe("SetupWizardButtonComponent", () => {
+  let component: SetupWizardButtonComponent;
+  let fixture: ComponentFixture<SetupWizardButtonComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [SetupWizardButtonComponent],
+      providers: [
+        { provide: EntityMapperService, useValue: mockEntityMapper() },
+      ],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(SetupWizardButtonComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it("should create", () => {
+    expect(component).toBeTruthy();
+  });
+});

src/app/core/admin/setup-wizard/setup-wizard-button/setup-wizard-button.component.ts

@@ -0,0 +1,46 @@
+import { Component } from "@angular/core";
+import { FaIconComponent } from "@fortawesome/angular-fontawesome";
+import { MatButton } from "@angular/material/button";
+import { RouterLink } from "@angular/router";
+import { EntityMapperService } from "../../../entity/entity-mapper/entity-mapper.service";
+import { Config } from "../../../config/config";
+import {
+  CONFIG_SETUP_WIZARD_ID,
+  SetupWizardConfig,
+} from "../setup-wizard-config";
+import { UntilDestroy, untilDestroyed } from "@ngneat/until-destroy";
+import { filter } from "rxjs/operators";
+import { LoggingService } from "../../../logging/logging.service";
+
+@UntilDestroy()
+@Component({
+  selector: "app-setup-wizard-button",
+  standalone: true,
+  imports: [FaIconComponent, MatButton, RouterLink],
+  templateUrl: "./setup-wizard-button.component.html",
+  styleUrls: ["./setup-wizard-button.component.scss"],
+})
+export class SetupWizardButtonComponent {
+  showSetupWizard: boolean;
+
+  constructor(entityMapper: EntityMapperService, logger: LoggingService) {
+    entityMapper
+      .load(Config, CONFIG_SETUP_WIZARD_ID)
+      .then((r: Config<SetupWizardConfig>) => {
+        this.updateStatus(r.data);
+      })
+      .catch((e) => logger.debug("No Setup Wizard Config found"));
+
+    entityMapper
+      .receiveUpdates<Config<SetupWizardConfig>>(Config)
+      .pipe(
+        untilDestroyed(this),
+        filter(({ entity }) => entity.getId() === CONFIG_SETUP_WIZARD_ID),
+      )
+      .subscribe((update) => this.updateStatus(update.entity.data));
+  }
+
+  private updateStatus(config: SetupWizardConfig) {
+    this.showSetupWizard = !config.finished;
+  }
+}

src/app/core/admin/setup-wizard/setup-wizard-config.ts

@@ -0,0 +1,106 @@
+import { MenuItem } from "../../ui/navigation/menu-item";
+
+export const CONFIG_SETUP_WIZARD_ID = "Config:SetupWizard";
+
+export interface SetupWizardConfig {
+  /** index of the current (last visited) step, to be opened when user returns to the wizard **/
+  currentStep?: number;
+
+  /** whether the wizard has been completed overall and should be hidden */
+  finished?: boolean;
+
+  steps: SetupWizardStep[];
+}
+
+export interface SetupWizardStep {
+  title: string;
+  text: string;
+  actions?: MenuItem[];
+
+  /** whether the user(s) have completed this step yet */
+  completed?: boolean;
+}
+
+export const defaultSetupWizardConfig: SetupWizardConfig = {
+  steps: [
+    {
+      title: $localize`:Setup Wizard Step Title:Welcome`,
+      text: $localize`:Setup Wizard Step Text:
+# Welcome to Aam Digital!
+We are here to help you manage your participants' or beneficiaries' details
+and your team's interactions with them.
+
+The Aam Digital platform is very flexible and you can customize the structures and views
+to exactly fit your project needs.
+The following steps guide you through the most important configuration options for this.
+And you can start working with your data within a few minutes already.
+
+We also have some short video guides for you: [Aam Digital Video Guides (YouTube)](https://www.youtube.com/channel/UCZSFOX_MBa8zz5Mtfv_qlnA/videos)
+
+Feel free to leave this setup wizard in between to explore the existing system first.
+You can always come back to this view through the "Setup Wizard" button at the bottom of the main menu on the left.
+To dismiss and hide this wizard, go to the last step of the wizard and "finish" the setup process.`,
+    },
+    {
+      title: $localize`:Setup Wizard Step Title:Profiles & Fields`,
+      text: $localize`:Setup Wizard Step Text:
+The system already holds some basic structures for your case management.
+You can adapt the fields and how the details are displayed.
+
+If you have further requirements, don't hesitate to reach out to us at [support@aam-digital.com](mailto:support@aam-digital.com).
+
+_Please note that the setup wizard and form builder is still under active development ("beta" version).
+Some advanced configuration options are not available here yet for you to configure yourself and may need assistance from the tech support team.
+We are currently extending and optimizing the user interfaces for these steps._
+`,
+      actions: [
+        {
+          label: $localize`:Setup Wizard Step Action:Customize Child profile`,
+          link: "/admin/entity/Child",
+        },
+        {
+          label: $localize`:Setup Wizard Step Action:Customize School profile`,
+          link: "/admin/entity/School",
+        },
+      ],
+    },
+    {
+      title: $localize`:Setup Wizard Step Title:User Accounts`,
+      text: $localize`:Setup Wizard Step Text:
+You can collaborate on Aam Digital as a team.
+Data is synced and all users have access to the latest information.`,
+      actions: [
+        {
+          label: $localize`:Setup Wizard Step Action:Manage User Accounts`,
+          link: "/user",
+        },
+      ],
+    },
+    {
+      title: $localize`:Setup Wizard Step Title:Import Data`,
+      text: $localize`:Setup Wizard Step Text:
+If you have exising data from a previous system, you can easily import it.
+Save the data in ".csv" format (e.g. from MS Excel).
+You do not need any specific column names in your file to be imported.
+The Import Module helps your map your spreadsheet data to the relevant fields in your Aam Digital profiles.`,
+      actions: [
+        {
+          label: $localize`:Setup Wizard Step Action:Import Data`,
+          link: "/import",
+        },
+      ],
+    },
+    {
+      title: $localize`:Setup Wizard Step Title:Done!`,
+      text: $localize`:Setup Wizard Step Text:
+That's it. You are ready to explore your system and start work!
+
+You can always adapt your setup further, after you started using it.
+We recommend to keep things simple in the beginning,
+start using it for some of your tasks
+and then add further fields and adjust your setup.
+
+Feel free to reach out to us with your questions or feedback: [support@aam-digital.com](mailto:support@aam-digital.com)`,
+    },
+  ],
+};

src/app/core/admin/setup-wizard/setup-wizard.component.html

@@ -0,0 +1,45 @@
+<mat-stepper [(selectedIndex)]="currentStep">
+  <!-- overwrite icons to keep simple numbered steps -->
+  <ng-template matStepperIcon="edit" let-index="index">
+    {{ index + 1 }}
+  </ng-template>
+  <ng-template matStepperIcon="done" let-index="index">
+    {{ index + 1 }}
+  </ng-template>
+
+  @for (step of config?.steps; track step; let last = $last) {
+    <mat-step [label]="step.title" [completed]="step.completed">
+      <markdown>{{ step.text }}</markdown>
+
+      <mat-action-list>
+        @for (action of step.actions; track action.link) {
+          <button mat-list-item [routerLink]="action.link">
+            {{ action.label }}
+          </button>
+        }
+      </mat-action-list>
+
+      @if (!last) {
+        <button
+          mat-stroked-button
+          matStepperNext
+          (click)="step.completed = true"
+          i18n
+        >
+          Continue
+        </button>
+      } @else {
+        <button
+          mat-stroked-button
+          routerLink=""
+          (click)="step.completed = true; config.finished = true"
+          matTooltip="We will hide the setup wizard from the main menu as you finish it here. You can still access it from the admin screen."
+          i18n-matTooltip
+          i18n
+        >
+          Finish
+        </button>
+      }
+    </mat-step>
+  }
+</mat-stepper>

src/app/core/admin/setup-wizard/setup-wizard.component.spec.ts

@@ -0,0 +1,27 @@
+import { ComponentFixture, TestBed } from "@angular/core/testing";
+
+import { SetupWizardComponent } from "./setup-wizard.component";
+import { EntityMapperService } from "../../entity/entity-mapper/entity-mapper.service";
+import { mockEntityMapper } from "../../entity/entity-mapper/mock-entity-mapper-service";
+
+describe("SetupWizardComponent", () => {
+  let component: SetupWizardComponent;
+  let fixture: ComponentFixture<SetupWizardComponent>;
+
+  beforeEach(async () => {
+    await TestBed.configureTestingModule({
+      imports: [SetupWizardComponent],
+      providers: [
+        { provide: EntityMapperService, useValue: mockEntityMapper() },
+      ],
+    }).compileComponents();
+
+    fixture = TestBed.createComponent(SetupWizardComponent);
+    component = fixture.componentInstance;
+    fixture.detectChanges();
+  });
+
+  it("should create", () => {
+    expect(component).toBeTruthy();
+  });
+});