@smarterservices/smarter-elements v1.0.2

SmarterElements

Embeddable UI components for SmarterServices that can be integrated into any web application.

Installation

NPM

npm install @smarterservices/smarter-elements

Yarn

yarn add @smarterservices/smarter-elements

Usage

Examples

Examples of how to use SmarterElements can be found in the UI application at:

http://localhost:3000/elements-examples/elements-integration.html

When running the UI application locally, you can access these examples to see how different components work and how to integrate them into your application.

JavaScript Integration

Using the Latest Version

<script src="https://unpkg.com/@smarterservices/smarter-elements"></script>
<script>
  // Create a new instance
  const elements = SmarterElements({
    baseUrl: 'https://your-smarterproctoring-url.com',
  });

  // Create an exam card
  const examCard = elements.create('examCard', {
    exam: {
      id: 'exam123',
      title: 'Biology 101',
      course: 'BIO 101 - Introduction to Biology',
      date: '2025-06-15',
      startTime: '10:00 AM',
      duration: 90,
    },
  });
</script>

Using a Specific Version

<!-- Using a specific major version (1.x.x - latest in 1.x range) -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1"></script>

<!-- Using a specific minor version (1.2.x - latest patch in 1.2 range) -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1.2"></script>

<!-- Using an exact version (1.2.3) -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1.2.3"></script>

<!-- Using a specific version with full path to UMD build -->
<script src="https://unpkg.com/@smarterservices/smarter-elements@1.2.3/dist/smarter-elements.umd.js"></script>

<script>
  // Create a new instance
  const elements = SmarterElements({
    baseUrl: 'https://your-smarterproctoring-url.com',
  });

  // Create an exam card
  const examCard = elements.create('examCard', {
    exam: {
      id: 'exam123',
      title: 'Biology 101',
      course: 'BIO 101 - Introduction to Biology',
      date: '2025-06-15',
      startTime: '10:00 AM',
      duration: 90,
    },
  });

  // Mount the exam card to a container
  examCard.mount('#exam-card-container');

  // Add event listeners
  examCard.on('start-exam', data => {
    console.log('Start exam clicked:', data);
  });

  examCard.on('view-details', data => {
    console.log('View details clicked:', data);
  });
</script>

React Integration

Installing a Specific Version

# Install the latest version
npm install @smarterservices/smarter-elements

# Install a specific major version (latest in 1.x range)
npm install @smarterservices/smarter-elements@1

# Install a specific minor version (latest patch in 1.2 range)
npm install @smarterservices/smarter-elements@1.2

# Install an exact version
npm install @smarterservices/smarter-elements@1.2.3

Basic Integration

import React, { useEffect, useRef } from 'react';
import SmarterElements from '@smarterservices/smarter-elements';

function ExamCardComponent() {
  const containerRef = useRef(null);
  const examCardRef = useRef(null);

  useEffect(() => {
    // Create a new instance
    const elements = SmarterElements({
      baseUrl: 'https://your-smarterproctoring-url.com',
    });

    // Create an exam card
    const examCard = elements.create('examCard', {
      exam: {
        id: 'exam123',
        title: 'Biology 101',
        course: 'BIO 101 - Introduction to Biology',
        date: '2025-06-15',
        startTime: '10:00 AM',
        duration: 90,
      },
    });

    // Mount the exam card to the container
    examCard.mount(containerRef.current);

    // Add event listeners
    examCard.on('start-exam', data => {
      console.log('Start exam clicked:', data);
    });

    examCard.on('view-details', data => {
      console.log('View details clicked:', data);
    });

    // Save the reference for cleanup
    examCardRef.current = examCard;

    // Cleanup
    return () => {
      if (examCardRef.current) {
        examCardRef.current.unmount();
      }
    };
  }, []);

  return <div ref={containerRef} className="exam-card-container"></div>;
}

export default ExamCardComponent;

Available Elements

• examCard: Displays exam information with actions
• proctorSchedule: Shows proctor schedule with calendar view
• examVerification: Handles exam verification process
• identityCheck: Manages identity verification
• elementsLayout: Provides a layout container for elements

Events

Each element emits events that you can listen to:

ExamCard Events

• start-exam: Triggered when the start exam button is clicked
• view-details: Triggered when the view details button is clicked
• resize: Triggered when the element's size changes

ProctorSchedule Events

• date-changed: Triggered when the selected date changes
• session-selected: Triggered when a session is selected

Modal Support

SmarterElements provides modal support for displaying elements in a modal:

// Open an exam card in a modal
const modalController = elements.openModal('examCard', {
  exam: {
    id: 'exam456',
    title: 'Physics 202',
    course: 'PHYS 202 - Quantum Mechanics',
    date: '2025-10-15',
    startTime: '2:00 PM',
    duration: 120,
  },
});

// Close the modal programmatically
modalController.close();

Versioning

This package follows Semantic Versioning:

• MAJOR version changes indicate incompatible API changes
• MINOR version changes add functionality in a backward-compatible manner
• PATCH version changes include backward-compatible bug fixes

Version Compatibility

To ensure your integration remains stable, we recommend the following versioning strategies:

For Production Applications

• Lock to an exact version in your package.json: "@smarterservices/smarter-elements": "1.2.3"
• Update versions manually after testing with your application

For Development/Staging

• Lock to a minor version using the caret syntax: "@smarterservices/smarter-elements": "^1.2.0"
• This allows automatic updates for patch releases (bug fixes) but prevents potentially breaking changes

Version Compatibility Matrix

Choosing the Right Version

When selecting a version for your application:

1. For new projects: Use the latest version available
2. For existing projects:
   • Check the CHANGELOG.md for breaking changes before upgrading major versions
   • Test thoroughly in a staging environment before deploying to production
3. For critical applications: Pin to an exact version and only upgrade after thorough testing

Browser Support

SmarterElements supports all modern browsers:

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

License

MIT