commons-assessment

v12.1.0

Published

a month ago

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.

0High
0Medium
0Low

huzaifmalik

Commons Assessment Library

Version Compatibility

Version 12: For Angular 12+ usage.

Dependencies

Required Peer Dependencies

Ensure the following packages are installed in your consumer application (as defined in package.json):

Angular Core & Common: >=12.0.0
Angular Material & CDK (for UI components and drag-and-drop): >=12.0.0
Bootstrap (for baseline grid and component styling): >=5.0.0
Quill (for rich text subjective questions): >=2.0.0

Required Angular Imports

Import the following modules in your application:

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

Installation & Configuration

1. Import Modules

Import the CommonsAssessmentModule.forRoot() in your root app.module.ts once to register the singleton service providers. Other modules can then import the specific feature modules as needed:

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

@NgModule({
  imports: [
    CommonsAssessmentModule.forRoot(), // Import once in root app.module
    AssessmentMakerModule,
    AssessmentTakerModule
  ]
})

2. Configure HTTP Interceptor (Decoupled base URL)

Since the library uses relative paths, you must configure an HTTP Interceptor in your application to detect library API requests (which carry the X-Library-Source: commons-assessment header), prepend your backend API base URL, and strip the header before forwarding the request.

import { Injectable } from '@angular/core';
import { HttpHandler, HttpInterceptor, HttpRequest } from '@angular/common/http';

@Injectable()
export class ApiInterceptor implements HttpInterceptor {
  intercept(req: HttpRequest<any>, next: HttpHandler) {
    let headers = req.headers;
    let url = req.url;

    if (headers.has('X-Library-Source')) {
      headers = headers.delete('X-Library-Source');
      url = 'https://your-api-domain.org' + url; // Prepend your backend base URL
    }

    req = req.clone({ url, headers });
    return next.handle(req);
  }
}

3. 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 to the assets array.

"assets": [
  {
    "glob": "**/*",
    "input": "node_modules/commons-assessment/src/lib/assets",
    "output": "assets/commons-assessment"
  }
]

Styles: Include the library's global styles in the styles array.

"styles": [
  "src/styles.scss"
]

4. 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 "commons-assessment/src/lib/assets/theme/styles.global";
// 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

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. | | [showCorrectAnswers] | @Input | boolean | (Optional) Shows correct and incorrect answers for objective and multiselect type questions. 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. |

Detailed Documentation

For a more comprehensive guide on features, detailed input/output variables, interfaces, custom events, and styling variables, please refer to the following documentation files:

Assessment Maker Component: assessment-maker.md
Assessment Taker Component: assessment-taker.md
Theming & Styles Guide: theme.md

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.