Docs: Attributes - rollthecloudinc/quell GitHub Wiki

1. Introduction
2. Installation
3. Overview and Features
4. Key Components
   • AttributesModule
   • Components (AttributesBuilderComponent, AttributeWidgetComponent)
5. Core Concepts
   • Widgets
   • Attribute Management
   • Serialization/Deserialization
6. Services
   • WidgetPluginManager
   • AttributeMatcherService
7. Usage
   • Dynamic Form Generation
   • Creating Custom Widgets
8. API Reference
9. Examples
10. Testing

The Angular Attributes Library is designed to help developers manage dynamic form attributes in Angular applications. It provides serialization, widget plugins, and a modular system for defining and rendering custom forms and attributes. The library's flexibility allows developers to create forms dynamically, customize widgets, and define attributes without needing static components.

Install the library using npm:

npm install @your-org/attributes

You may also need other dependencies like @rollthecloudinc/material and @rollthecloudinc/plugin, which are used for widget rendering and plugin management.

The AttributesModule is the core module in this library that enables the following features:

• Dynamic Form Creation: Create forms dynamically based on attribute data.
• Custom Widgets: Render attribute values using widgets like text boxes, dropdowns, and sliders.
• Plugin-based Widget Management: Extend the library by registering widget plugins using a modular approach.
• Attribute Serialization and Deserialization: Serialize object data into attributes and deserialize attributes back into object data.
• Reactive Form Integration: Leverage Angular Forms for validation and state management.

The AttributesModule orchestrates all components and services in the library. It imports supporting modules like ReactiveFormsModule and MaterialModule to enable dynamic forms and material design.

@NgModule({
  imports: [
    CommonModule,
    ReactiveFormsModule,
    MaterialModule,
    HttpClientJsonpModule,
  ],
  declarations: [
    AttributesBuilderComponent,
    AttributeWidgetComponent,
    TextWidgetComponent,
    MinMaxWidgetComponent,
    AttributePipe,
  ],
  exports: [
    AttributesBuilderComponent,
    AttributeWidgetComponent,
    AttributePipe,
  ],
  providers: [
    {
      provide: ATTRIBUTE_WIDGET,
      useFactory: attrFactories.textFactory,
      multi: true,
    },
    {
      provide: ATTRIBUTE_WIDGET,
      useFactory: attrFactories.minmaxFactory,
      multi: true,
    },
  ],
})
export class AttributesModule {}

AttributesBuilderComponent
The AttributesBuilderComponent provides functionality for dynamically creating attribute-based forms. It integrates widgets as plugins and allows nesting of attributes.

AttributeWidgetComponent
The AttributeWidgetComponent dynamically renders widgets based on the provided attribute schema and widget plugin.

Widgets are reusable form components that dynamically render attributes based on schema definitions. The library comes with the following predefined widgets:

• TextWidgetComponent: A single-line text input.
• MinMaxWidgetComponent: A numeric range widget (min and max values).

You can also define custom widgets and register them as plugins for dynamic rendering.

Attributes are structured data models defined in attributes.models.ts. The key models include:

• Attribute: Represents the schema definition of an attribute.
• AttributeWidget: Represents a plugin-based widget along with its associated schema.
• AttributeValue: Represents the value of an attribute at runtime.

The WidgetPluginManager is a plugin-based service for managing custom widgets. It extends the base PluginManager class from @rollthecloudinc/plugin and provides methods to define and fetch widgets dynamically.

Example:

pluginManager.register(new AttributeWidget<string>({
  id: 'custom-widget',
  name: 'Custom Widget',
  title: 'My Custom Widget',
  component: CustomWidgetComponent,
  schema: customSchema,
}));

This service handles the logic for matching attribute values and computing derived values. Use it to process complex attribute relationships and nested attributes.

To create a dynamic form, pass an array of Attribute objects to the AttributesBuilderComponent.

<classifieds-ui-attributes-builder
  [attributes]="attributes"
  [appearance]="'material'"
>
</classifieds-ui-attributes-builder>

attributes: Attribute[] = [
  {
    name: 'Username',
    type: AttributeTypes.Text,
    label: 'Enter your username',
    required: true,
    widget: 'text',
    options: {},
    attributes: [],
  },
  {
    name: 'Age',
    type: AttributeTypes.Number,
    label: 'Enter your age',
    required: true,
    widget: 'minmax',
    options: { min: 18, max: 99 },
    attributes: [],
  },
];

You can create custom widgets by extending the AttributeWidget model and defining a new Angular component.

@Component({
  selector: 'app-custom-widget',
  templateUrl: './custom-widget.component.html',
})
export class CustomWidgetComponent {
  @Input() attribute: Attribute;
}

Register your widget as a plugin:

const customWidgetFactory = () => {
  const schema = new Attribute({
    name: 'custom',
    type: AttributeTypes.Complex,
    label: 'Custom Widget',
    required: true,
    widget: 'custom',
    options: {},
    attributes: [],
  });
  return new AttributeWidget<string>({
    id: 'custom-widget',
    name: 'custom-widget',
    title: 'Custom Widget',
    component: CustomWidgetComponent,
    schema,
  });
};

• AttributeWidget: Represents a widget plugin and schema.
• Attribute: Schema definition for an attribute.
• AttributeValue: Runtime representation of attribute values.

• WidgetPluginManager: Plugin-based widget manager.
• AttributeSerializerService: Serializes and deserializes attributes.
• AttributeMatcherService: Matches and computes derived values.

• AttributesBuilderComponent: Builds dynamic attribute forms.
• AttributeWidgetComponent: Dynamically renders a widget.

<classifieds-ui-attributes-builder
  [attributes]="attributes"
></classifieds-ui-attributes-builder>

<classifieds-ui-attribute-widget
  [widget]="customWidgetPlugin$"
  [attribute]="attribute"
></classifieds-ui-attribute-widget>

Unit tests are provided for all components and services. Run tests using the command:

npm run test

Example Spec Test (TextWidgetComponent):

describe('TextWidgetComponent', () => {
  let component: TextWidgetComponent;
  let fixture: ComponentFixture<TextWidgetComponent>;

  beforeEach(() => {
    TestBed.configureTestingModule({
      declarations: [TextWidgetComponent],
    }).compileComponents();

    fixture = TestBed.createComponent(TextWidgetComponent);
    component = fixture.componentInstance;
  });

  it('should create', () => {
    expect(component).toBeTruthy();
  });
});

The Angular Attributes Library provides powerful tools for dynamic form creation, attribute serialization, and custom widget management. Developers can extend the library to handle complex forms and modular data attributes, improving reusability and maintainability in Angular applications.

Let us know if you need further assistance!