Commons Assessment Library

This library provides a comprehensive set of tools and components to create and manage assessments (Maker module), as well as to facilitate users in taking assessments (Taker module) within an Angular application.

Version Compatibility

• Version 12: For Angular 12 to 15 usage.
• Version 16: For Angular 16+ usage.

Dependencies

The library uses Bootstrap styles and requires the following modules to be imported in your application:

• BrowserAnimationsModule
• HttpClientModule
• CommonsAssessmentModule
• AssessmentMakerModule (If creating assessments)
• AssessmentTakerModule (If rendering assessments)

Installation & Configuration

1. Import Modules

Import the appropriate modules in your app.module.ts. You must configure CommonsAssessmentModule with forRoot() to provide the backend base URL.

import { CommonsAssessmentModule, AssessmentMakerModule, AssessmentTakerModule } from 'commons-assessment';

@NgModule({
  imports: [
    CommonsAssessmentModule.forRoot({
      baseURL: 'https://dev.platformcommons.org', // Use your backend API base URL
    }),
    AssessmentMakerModule,
    AssessmentTakerModule
  ]
})

2. Configure angular.json

Add the necessary assets and global styles in your angular.json file inside the architect.build.options block.

Assets: Add the library assets and angular-editor icons to the assets array.

"assets": [
  {
    "glob": "**/*",
    "input": "node_modules/commons-assessment/src/lib/assets",
    "output": "assets/commons-assessment"
  },
  {
    "glob": "**/*",
    "input": "node_modules/@kolkov/angular-editor/assets/icons",
    "output": "assets/ae-icons/"
  }
]

Styles: Include the library's global styles and third-party dependencies in the styles array.

"styles": [
  "src/styles.scss",
  "node_modules/commons-assessment/src/lib/assets/theme/styles.global.scss",
  "node_modules/@kolkov/angular-editor/themes/default.scss"
]

3. Theming Setup (styles.scss)

The library provides a mixin to easily customize the theme, including fonts and color variables. Set this up in your application's global styles.scss:

// Import the library's theme mixin
@use "/node_modules/commons-assessment/src/lib/assets/theme/theme.global" as theme;
// Import Bootstrap and Material core styles
@import "~bootstrap/dist/css/bootstrap.min.css";
@import "@angular/material/prebuilt-themes/indigo-pink.css";

// Include customized variables into the theme
:root {
    @include theme.assessment-theme(
        (
            font-family: "Poppins",
            // You can override library palette by uncommenting and modifying below:
            // primary-one: #2e7d32,
            // primary-four: #1b5e20,
            // palette-EDF3FD: #e8f5e9,
            // grey-one: #fff,
        )
    );
}

Component Usage

Assessment Maker

To render the assessment maker interface, use the <lib-assessment-maker> component in your template.

component.ts:

export class Component {
  // Define default structure or data payload for the assessment
  createAssessmentDTO: Assessment = {
    assessmentCode: 'TEST_ASSESSMENT_CODE',
    domain: 'domain.test',
    assessmentName: [{
      id: 0,
      text: 'test assessment',
      language: {
        code: 'ENG',
      }
    }],
    tenant: 123
  };
}

component.html:

  <lib-assessment-maker 
    [defaultAssessmentDTO]="createAssessmentDTO"
    [assessmentId]="2298"
    [showFooter]="true">
  </lib-assessment-maker>

Maker Inputs and Outputs

| Property | Type (@Input / @Output) | Data Type | Description | | --- | --- | --- | --- | | [labelConfig] | @Input | { [key: string]: string } | (Optional) Configuration strings to overwrite internal labels. | | [imageConfig] | @Input | { [key: string]: string } | (Optional) Configuration paths/URLs to overwrite internal icons or images. | | [questionTypes] | @Input | QuestionType[] | (Optional) Restrict or customize the array of available question types. | | [showFooter] | @Input | boolean | (Optional) Toggles visibility of the assessment component footer actions. | | [customRules] | @Input | any | (Optional) Pass your custom question builder rules overrides. | | [assessmentId] | @Input | number | Provide the ID of an existing assessment to edit or attach questions to. Default is 0. | | [assessmentInstanceId] | @Input | number | Current assessment instance identifier, if the assessment is already published. Default is 0. | | [defaultAssessmentDTO] | @Input | Assessment | The default contextual configuration object for creating new assessments. | | (assessmentIdChange) | @Output | EventEmitter<number> | Emits the new assessmentId when an assessment is successfully created. | | (assessmentInstanceIdChange) | @Output | EventEmitter<number> | Emits the new instance ID integer when an assessment is published. | | (snackbarMessage) | @Output | EventEmitter<{ message: string, type: 'success' \| 'error' \| 'info' }> | Emits message status updates representing errors and workflow successes from the service. |

Assessment Taker

To render the assessment taker interface, use the <lib-assessment-taker> component in your template.

component.html:

  <lib-assessment-taker
    [labelConfig]="{}"
    [imageConfig]="{}"
    [assessmentId]="2298"
    [assessmentInstanceId]="1135"
    [assesseeData]="assesseeData"
    [assessorData]="assessorData"
    [showFooter]="true"
    [disabled]="false"
    [previewMode]="false"
    [verticalView]="false"
    [enableMarks]="false"
    [assessmentContext]="assessmentContext"
    (submitAssessment)="onSubmit($event)"
    (snackbarMessage)="onSnackbarMessage($event)">
  </lib-assessment-taker>

Taker Inputs and Outputs

| Property | Type (@Input / @Output) | Data Type | Description | | --- | --- | --- | --- | | [labelConfig] | @Input | { [key: string]: string } | (Optional) Configuration strings to overwrite internal labels. | | [imageConfig] | @Input | { [key: string]: string } | (Optional) Configuration paths/URLs to overwrite internal icons or images. | | [assessmentId] | @Input | number | Required. Provide the ID of an existing assessment to take. | | [assessmentInstanceId] | @Input | number | Required. The published instance ID of the assessment. | | [assesseeData] | @Input | AssesseeDTO | Required. Data concerning the person taking the assessment. | | [assessorData] | @Input | AssessorDTO | Required. Data concerning the entity or person grading/creating the assessment. | | [showFooter] | @Input | boolean | (Optional) Toggles visibility of the assessment component footer actions. | | [disabled] | @Input | boolean | (Optional) Disables the form to prevent interaction. | | [previewMode] | @Input | boolean | (Optional) Disables interaction and enables preview functionality. | | [verticalView] | @Input | boolean | (Optional) Displays the assessment sections vertically instead of tabs. | | [enableMarks] | @Input | boolean | (Optional) Enables ability to view or provide marks. | | [assessmentContext] | @Input | AssessmentContextDTO | (Optional) Pre-loaded assessment context data to bypass the initial data load API call. | | [assesseeResponse] | @Input | AssessmentInstanceAssesseDTO | (Optional) Pre-loaded assessee response data to bypass the initial data load API call. | | [hideSectionTabs] | @Input | boolean | (Optional) Hides the section tabs. | | [markAsCompleted] | @Input | boolean | (Optional) Marks the assessment as completed when the last section is submitted. Default is true. | | [sectionWiseScore] | @Input | { [sectionId: number]: SectionScore } | (Optional) Shows section wise score. Default is null. | | [showOverallRemarks] | @Input | boolean | (Optional) Shows overall remarks field. Default is false. | | [enableSkillsToQuestionMapping] | @Input | boolean | (Optional) Enables ability to map skills to questions. Default is false. | | (stepChanged) | @Output | EventEmitter<{ currentStepIndex: number, totalSteps: number, isLastStep: boolean }> | Emits initially and on every step change. Provides the current step index, total steps, and indicating boolean. | | (submitAssessment) | @Output | EventEmitter<{ assesseeId: number, completed: boolean }> | Emits when the assessment is submitted, containing the assesseeId and a completed flag indicating if the taker finished the entire assessment. | | (snackbarMessage) | @Output | EventEmitter<{ message: string, type: 'success' \| 'error' \| 'info' }> | Emits message status updates representing errors and workflow successes from the service. |

Development Commands

• Run npm run build or ng build commons-assessment to build the library project. The build artifacts will be stored in the dist/ directory.
• Run ng test commons-assessment to execute the unit tests via Karma.