Skip to content

Docs: Refinery

Jump to bottom
ng-druid edited this page Aug 8, 2025 · 1 revision

Documentation for Angular Refinery Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Key Concepts
    • Plugins and Ductdata Workflow
    • Persistence Model
    • Plugin Management
  5. Core Components and Directives
    • RefineryModule
    • PersistenceDialogComponent
    • PersistenceFormComponent
    • DataductRenderHostDirective
  6. Key Services
    • PersistService
    • DataductPluginManager
  7. Usage
    • Managing Plugins
    • Using Persistence Dialog
    • Creating Persistence Forms
  8. API Reference
  9. Examples
  10. Testing

1. Introduction

The Angular Refinery Library is designed to streamline workflows and persistence operations in Angular applications using plugins and dynamic forms. It provides an extensible platform for rendering, managing, and persisting data with a flexible plugin architecture.

2. Installation

Install the library and its dependencies:

npm install @rollthecloudinc/material @rollthecloudinc/plugin @rollthecloudinc/attributes @rollthecloudinc/context @rollthecloudinc/utils uuid rxjs zone.js

3. Overview

The library facilitates building dynamic applications by supporting plugins for data persistence, rendering, and complex forms. At its core, it focuses on:

  • Plugins: Dynamically handle data with configuration.
  • Persistence Layer: Define and manage persistence workflows via forms.
  • Directive-based Rendering: Manage object renderers via directives.
  • Plugin Manager: Maintain and resolve plugin definitions.

Features:

  • Persistence of data via plugins and forms.
  • Dynamic plugin configuration and rendering.
  • Extensible models for input and output workflows.
  • Integration with Angular Material for dialogs and forms.

4. Key Concepts

4.1 Plugins and Ductdata Workflow

Plugins are central to the library. They define workflows to handle settings, components, and persistence logic. The DataductPlugin model allows you to set editors, input handling (DuctdataInput), and output rendering (DuctdataOutput).

  • DataductPlugin:
    • Define a plugin with an editor component and send method.
    • Operates on DuctdataInput for data persistence.

4.2 Persistence Model

Persistence is handled via forms and dialogs in conjunction with PersistenceFormPayload. It represents data encapsulated in plugins and settings.

  • PersistenceFormPayload:
    • Specifies which plugin is used and its associated settings.
    • Groups PersistenceFormDataduct objects for plugin management.

4.3 Plugin Management

The DataductPluginManager allows dynamic management of plugins. It retrieves plugin definitions and manages lifecycle operations for renderers.

5. Core Components and Directives

RefineryModule

The RefineryModule is the entry point to the library and includes all components, services, and directives for persistence workflows.

import { RefineryModule } from 'refinery';

@NgModule({
  imports: [
    RefineryModule
  ]
})
export class AppModule { }

PersistenceDialogComponent

The PersistenceDialogComponent is a reusable Angular Material dialog for setting and saving persistence workflows.

Features:

  • Accepts PersistenceFormPayload and inline contexts as input.
  • Uses Angular Reactive Forms to manage settings.
  • Serializes settings for persistence.

PersistenceFormComponent

The PersistenceFormComponent provides a dynamic form to configure a plugin and its associated settings. It can:

  • Dynamically render plugin editors.
  • Manage the input and value lifecycle of settings.
  • Validate dynamically generated forms.

DataductRenderHostDirective

The DataductRenderHostDirective facilitates dynamic rendering of components belonging to a plugin, attaching them to host elements.

6. Key Services

PersistService

The PersistService handles the central persistence logic. It evaluates persistence workflows using plugins and passes data structures for saving.

Key Responsibilities:

  • Fetch plugin by name.
  • Send data along with settings to the plugin.
  • Generate DuctdataInput objects dynamically.

DataductPluginManager

The DataductPluginManager dynamically manages plugin definitions for use in forms and dialogs.

Key Responsibilities:

  • Register and retrieve plugins dynamically.
  • Resolve plugin definitions and editor components.
  • Enable creation of custom workflows.

7. Usage

7.1 Managing Plugins

Use the DataductPluginManager to register and retrieve plugin definitions dynamically.

Example:

import { DataductPluginManager } from './services/dataduct-plugin-manager.service';

constructor(private pluginManager: DataductPluginManager) {}

ngOnInit() {
  this.pluginManager.pluginDef().subscribe(plugin => {
    console.log('Available Plugin:', plugin);
  });
}

7.2 Using Persistence Dialog

The PersistenceDialogComponent integrates with Angular Material for saving persistence settings.

Example:

import { MatDialog } from '@angular/material/legacy-dialog';
import { PersistenceDialogComponent } from './components/persistence-dialog/persistence-dialog.component';

constructor(private dialog: MatDialog) {}

openDialog() {
  const dialogRef = this.dialog.open(PersistenceDialogComponent, {
    data: { persistence: new PersistenceFormPayload(), contexts: [] }
  });

  dialogRef.afterClosed().subscribe(result => {
    console.log('Dialog closed with:', result);
  });
}

7.3 Creating Persistence Forms

Use the PersistenceFormComponent to make input-driven, reactive forms for dynamic data persistence.

Example:

<classifieds-ui-persistence-form [contexts]="contexts" [(ngModel)]="persistencePayload"></classifieds-ui-persistence-form>

8. API Reference

Classes

  • DataductPlugin: Defines a plugin with editor and send logic.
  • DuctdataInput: Represents input data for plugins.
  • DuctdataOutput: Represents output data from plugins.
  • PersistenceFormPayload: Encapsulates persistence settings for plugins.

Directive

  • DataductRenderHostDirective: Hosts dynamic components rendered by plugins.

Components

  • PersistenceDialogComponent: Dialog managing persistence workflows.
  • PersistenceFormComponent: Creates forms dynamically based on plugins and settings.

Services

  • PersistService: Centralized service for persistence logic.
  • DataductPluginManager: Manages plugin definitions dynamically.

9. Examples

Example 1: Configure Persistence Workflow

import { PersistService } from './services/persist.service';
import { PersistenceFormPayload } from './models/refinery.models';

constructor(private persistService: PersistService) {}

saveWorkflow() {
  const payload = new PersistenceFormPayload({
    dataduct: {
      plugin: 'dataductPlugin',
      settings: [{ name: 'key', value: 'value' }]
    }
  });

  this.persistService.persist({ data: {}, persistence: payload }).subscribe(() => {
    console.log('Persistence workflow saved!');
  });
}

Example 2: Render Plugin Editor in Form

import { DataductPluginManager } from './services/dataduct-plugin-manager.service';

constructor(private pluginManager: DataductPluginManager) {}

renderEditor(pluginName: string) {
  this.pluginManager.getPlugin(pluginName).subscribe(plugin => {
    const viewContainerRef = this.datasourceHost.viewContainerRef;
    viewContainerRef.clear();
    const componentRef = viewContainerRef.createComponent(plugin.editor);
    console.log('Editor rendered:', componentRef.instance);
  });
}

10. Testing

Example: Test Persistence Workflow

import { PersistService } from './services/persist.service';
import { PersistenceFormPayload } from './models/refinery.models';

describe('PersistService', () => {
  let service: PersistService;

  beforeEach(() => {
    service = new PersistService(/* dependencies */);
  });

  it('should save persistence workflows', () => {
    const payload = new PersistenceFormPayload({
      dataduct: {
        plugin: 'testPlugin',
        settings: []
      }
    });

    service.persist({ data: {}, persistence: payload }).subscribe(result => {
      expect(result).toBeUndefined();
    });
  });
});

Conclusion

The Angular Refinery Library provides a powerful, extensible system for managing plugins, persistence dialogs, and forms within your Angular projects. It supports dynamic data workflows, custom plugin management, and flexible rendering logic for modern applications.

For contributions, feature requests, or bug reports, please reach out!

Clone this wiki locally