Skip to content

Docs: Datasource

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

Documentation for Angular Datasource Library

Table of Contents

  1. Introduction
  2. Installation
  3. Overview
  4. Key Concepts
    • Datasource Plugins
    • Datasource Components
    • Dynamic Datasource Resolvers
  5. Core Module
    • DatasourceModule
  6. Key Components
    • DatasourceFormComponent
    • DatasourceOptionsComponent
    • DatasourceSourceComponent
    • DataDatasourceComponent
  7. Key Services
    • DatasourcePluginManager
    • DatasourceApiService
    • DatasourceEvaluator
  8. Models
  9. Mocks
  10. Usage
    • Configure Datasources
    • Register Datasource Plugins
    • Fetch and Post Data
  11. API Reference
  12. Examples
  13. Testing

1. Introduction

The Datasource Angular Library provides tools for managing, rendering, and resolving datasources dynamically within Angular applications. It allows you to interact with data sources via plugins, form-based configurations, and resolvers, offering extensibility through its plugin architecture and reusable components.

2. Installation

Install the library and its dependencies:

npm install @rollthecloudinc/material @rollthecloudinc/plugin @rollthecloudinc/attributes @rollthecloudinc/content

These dependencies enable plugin-based extensibility, attribute serialization, and seamless data handling.

3. Overview

The Datasource Library integrates datasources such as APIs, attributes, and data objects directly into Angular applications. The library supports:

  • Datasource Plugins: Enables dynamic datasource management using custom plugins.
  • Component-Based Forms: Provides reusable components for rendering datasource configurations and interacting with data.
  • Dynamic Rendering: Load plugin-specific editors dynamically with directives like DatasourceRendererHostDirective.
  • Data Mapping and Serialization: Transform data sources using serialization services.
  • Nested Datasource Evaluation: Recursive evaluation of datasources for complex data structures.

4. Key Concepts

4.1 Datasource Plugins

A DatasourcePlugin represents a reusable unit for fetching or managing data. It is typically set up with:

  • ID: A unique identifier for the plugin.
  • Editor Component: UI rendering logic for configuring the plugin.
  • Fetch Method: Resolves and retrieves data from a datasource.

Example:

export const dataDatasourcePluginFactory = (attributeSerializer: AttributeSerializerService) => {
  return new DatasourcePlugin<string>({
    id: 'data',
    title: 'Data',
    editor: DataDatasourceComponent,
    fetch: ({ settings }) =>
      of(new Dataset()).pipe(
        map(() => attributeSerializer.deserializeAsObject(settings)),
        map((s) => new Dataset({ results: JSON.parse(s.data) }))
      ),
  });
};

4.2 Datasource Components

The library provides specialized components to interact with datasources:

  • DatasourceFormComponent: Core form for managing datasource plugins.
  • DatasourceOptionsComponent: Form for configuring datasource options like query or mapping fields.
  • DataDatasourceComponent: Specialized editor for data datasource plugins.

4.3 Dynamic Datasource Resolvers

Resolvers facilitate runtime evaluation of datasources and their nested bindings. This enables dynamic resolution of complex datasource relationships.

5. Core Module

DatasourceModule

The DatasourceModule consolidates components, directives, and services required for datasource management. Import it into your application:

import { DatasourceModule } from 'datasource';

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

The module includes:

  • Components: DatasourceFormComponent, DatasourceOptionsComponent, etc.
  • Directive: DatasourceRendererHostDirective.
  • Services: DatasourcePluginManager, DatasourceEvaluator.

Here’s the module declaration:

@NgModule({
  declarations: [
    DatasourceOptionsComponent,
    DatasourceFormComponent,
    DatasourceRendererHostDirective,
    DataDatasourceComponent,
    DataSourceFormComponent,
    DatasourceSourceComponent,
    DatasourceSourceFormComponent,
  ],
  imports: [
    CommonModule,
    ReactiveFormsModule,
    MaterialModule,
    DurlModule,
  ],
  exports: [
    DatasourceOptionsComponent,
    DatasourceFormComponent,
    DatasourceRendererHostDirective,
    DataDatasourceComponent,
    DataSourceFormComponent,
    DatasourceSourceComponent,
    DatasourceSourceFormComponent,
  ],
})
export class DatasourceModule {}

6. Key Components

6.1 Datasource Form Component (DatasourceFormComponent)

A dynamic form for managing datasources. It:

  • Loads plugin editor components dynamically using the DatasourceRendererHostDirective.
  • Handles renderer bindings and plugin-specific settings.
<classifieds-ui-datasource-form [datasource]="datasource"></classifieds-ui-datasource-form>

6.2 Datasource Options Component (DatasourceOptionsComponent)

Provides a form-based UI for configuring datasource options such as mappings, multiple selection, and limits.

<classifieds-ui-datasource-options></classifieds-ui-datasource-options>

6.3 Datasource Source Component (DatasourceSourceComponent)

Renders settings and forms for an embedded datasource.

<classifieds-ui-datasource-source [settings]="settings"></classifieds-ui-datasource-source>

6.4 Data Datasource Component (DataDatasourceComponent)

Manages settings specific to the data plugin.

<classifieds-ui-data-datasource [settings]="settings"></classifieds-ui-data-datasource>

7. Key Services

7.1 Datasource API Service (DatasourceApiService)

Provides methods to fetch and post data to remote endpoints, while caching results for optimized performance.

constructor(private apiService: DatasourceApiService) {}

this.apiService.getData('https://example.com/data').subscribe(data => {
  console.log(data);
});

7.2 Datasource Plugin Manager (DatasourcePluginManager)

Dynamically registers and retrieves datasource plugins.

constructor(private pluginManager: DatasourcePluginManager) {}

pluginManager.getPlugins().subscribe(plugins => {
  console.log(plugins);
});

7.3 Datasource Evaluator (DatasourceEvaluator)

Recursively evaluates datasources and their bindings, resolving nested datasource relationships.

constructor(private evaluator: DatasourceEvaluator) {}

this.evaluator.evalDatasource({ datasource, metadata }).subscribe(dataset => {
  console.log(dataset.results);
});

8. Models

Datasource Models

  • DatasourcePlugin: Represents a plugin's settings, editor component, and fetch method.
  • Dataset: Structured data received from plugins.
  • DatasourceOptions: Configuration options like query, mappings, and limits.
  • Datasource: Core datasource model including plugin, renderer settings, and parameters.

9. Mocks

The library includes predefined mocks for testing purposes:

Mock Datasource Options Example:

import { mockDatasourceOptions } from 'datasource';

const options = mockDatasourceOptions;

10. Usage

10.1 Configure Datasources

You can configure datasources using DatasourceFormComponent.

<classifieds-ui-datasource-form [datasource]="datasource"></classifieds-ui-datasource-form>
myDatasource: Datasource = {
  plugin: 'data',
  settings: [
    { name: 'query', value: 'SELECT * FROM my_table' },
    { name: 'limit', value: '100' },
  ],
};

10.2 Register Datasource Plugins

Register custom datasource plugins using DatasourcePluginManager.

pluginManager.register(
  new DatasourcePlugin({
    id: 'custom',
    title: 'Custom Plugin',
    editor: CustomEditorComponent,
    fetch: (params) => of(new Dataset({ results: [] })),
  })
);

11. API Reference

Components

  • DatasourceFormComponent
  • DatasourceOptionsComponent
  • DatasourceSourceComponent
  • DataDatasourceComponent

Services

  • DatasourceApiService
  • DatasourcePluginManager
  • DatasourceEvaluator

Models

  • DatasourcePlugin
  • Datasource
  • Dataset
  • DatasourceOptions

12. Examples

Define and Use Datasources

<classifieds-ui-datasource-form [datasource]="myDatasource"></classifieds-ui-datasource-form>
myDatasource: Datasource = {
  plugin: 'data',
  settings: [
    { name: 'query', value: 'SELECT * FROM my_table' },
    { name: 'limit', value: '100' },
  ],
};

13. Testing

Unit testing can be performed using Angular's testing utilities. Example test configuration:

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

  beforeEach(() => {
    TestBed.configureTestingModule({});
    service = TestBed.inject(DatasourceApiService);
  });

  it('should fetch data', () => {
    service.getData('https://test.com/data').subscribe((data) => {
      expect(data).toBeTruthy();
    });
  });
});

To execute tests:

npm run test

Conclusion

The Datasource Angular Library simplifies management, rendering, and evaluation of datasources in Angular applications. Its extensible plugin-based framework, reusable components, and powerful evaluators allow developers to build dynamic, scalable, and maintainable applications.

For contributions or feature requests, feel free to reach out!

Clone this wiki locally