A tool for embedding OneSchema into your application with Angular. This library contains an Angular module and service to help you use OneSchema with your application.

Getting Started

Installation

You can install this package with npm:

npm i --save @oneschema/angular @oneschema/importer

With pnpm, install eventemitter3 alongside them:

pnpm add @oneschema/angular @oneschema/importer eventemitter3@^4.0.7

The importer class this service wraps extends EventEmitter from eventemitter3, so that type is part of the published declarations. pnpm keeps each package's dependencies isolated instead of hoisting them, so your build cannot resolve eventemitter3 unless it is declared in your project too. npm and yarn hoist it for you.

Compatibility

@oneschema/angular keeps @oneschema/importer as a peer dependency so that your application resolves a single copy of the importer core, and its peer range always admits the core released alongside it: a given @oneschema/angular release requires the matching @oneschema/importer minor (currently ^0.7.0). Install both packages together, and upgrade them together.

The package is published in the Angular Package Format with partial-Ivy bundles, which the Angular linker in your application's build fully compiles ahead of time. It supports Angular 15 and newer (@angular/core and @angular/common >=15); the packaged bundles are verified by building scratch applications on Angular 15, 20 and 22, and the library itself is built and unit tested against Angular 16.

Sample usage

Add the OneSchemaModule to your app.module:

import { BrowserModule } from "@angular/platform-browser"
import { NgModule } from "@angular/core"
import { AppComponent } from "./app.component"

// Import the module from the OneSchema package
import { OneSchemaModule } from "@oneschema/angular"

@NgModule({
  declarations: [AppComponent],
  imports: [
    BrowserModule,

    // Import the module into the application, with configuration
    OneSchemaModule.forRoot({
      clientId: "CLIENT_ID",
      templateKey: "TEMPLATE_KEY",
      userJwt: "USER_JWT",
      styles: {
        position: "fixed",
        top: "0",
        left: "0",
        width: "100vw",
        height: "100vh",
      },
    }),
  ],

  bootstrap: [AppComponent],
})
export class AppModule {}

Create a button to open the OneSchema importer and listen to events:

import { Component } from '@angular/core'
import { OneSchemaService } from './oneschema.service'

@Component({
  selector: 'oneschema-button',
  template: `<button (click)="launch()">Open OneSchema</button>`,
  styles: [],
})
export class OneSchemaButtonComponent implements OnDestroy {
  constructor(public oneschema: OneSchemaService) {
    this.oneschema.on('success', this.onSuccess)
    this.oneschema.on('error', this.onError)
    this.oneschema.on('cancel', this.onCancel)
  }

  launch() {
    this.oneschema.launch()
  }

  onSuccess(data: any) {
    // handle success
  }

  onError(error: any) {
    // handle error
  }

  onCancel() {
    // handle cancel
  }

  ngOnDestroy() {
    this.oneschema.off('success', this.onSuccess)
    this.oneschema.off('error', this.onError)
    this.oneschema.off('cancel', this.onCancel)
  }
}

To style the iframe, either pass in styles prop to the module, add CSS to your global stylesheet, or to a component with ViewEncapsulation.None. The iframe's class will be what is passed to the module as the className prop or oneschema-iframe by default. Sample CSS for the iframe to take up the full viewport is:

.oneschema-iframe {
  position: fixed;
  right: 0;
  top: 0;
  width: 100vw;
  height: 100vh;
}

Advanced usage

Manage the iframe yourself by adding inline to your OneSchemaModule configuration and then making an iframe in a component:

import { AfterViewInit, Component, ElementRef, ViewChild } from '@angular/core'
import { OneSchemaService } from '@oneschema/angular'

@Component({
  selector: 'oneschema-iframe',
  template: ` <iframe #oneschema></iframe>`,
  styles: [
    `
      iframe {
        position: fixed;
        top: 0;
        left: 0;
        width: 100vw;
        height: 100vh;
      }
    `,
  ],
})
export class OneSchemaIframeComponent implements AfterViewInit {
  @ViewChild('oneschema') iframe?: ElementRef<HTMLIFrameElement>

  constructor(public oneschema: OneSchemaService) {}

  ngAfterViewInit() {
    this.oneschema.setIframe(this.iframe!.nativeElement)
  }
}

Documentation

Please see 📚 OneSchema's documentation for 📒 API reference and other helpful guides.