The Widget (and its configurator if any) has to be declared in an Angular module:

An Angular application may load different modules, sometime lazy loaded, depending on the project size, organization or complexity.

Each module that registers Custom widgets needs to register the widget and its (optional) configurator widget through the GeneCustomWidgetFactoryService.

The Custom Widget sample below shows how to do it.

@NgModule({
    declarations : [SampleWidgetComponent, SampleWidgetConfiguratorComponent],
    entryComponents : [SampleWidgetComponent, SampleWidgetConfiguratorComponent],
    providers: [SampleWidgetService],
    imports : [
        CommonModule,
        FormsModule,
        ReactiveFormsModule,
        ClrInputModule,

        // DOC Modules dependencies
        GeneCommonUiModule,
        GeneLoadingOverlayModul

    ]
})
export class SampleWidgetModule {

    constructor(customWidgetFactory: GeneCustomWidgetFactoryService) {

        // Register my component Manifest into the custom Widget factory, so
        // it is accessible through the wizard
        customWidgetFactory.registerWidget(SampleWidgetComponent.MANIFEST, SampleWidgetComponent, SampleWidgetConfiguratorComponent);
    }
}

/**
 * Copyright (c) DecisionBrain SAS. All Rights Reserved.
 *
 * This is the base interface of dynamic widget parameters.
 */
 export interface GeneWidgetConfiguration {}

For example, we will make the "title" of the Sample Widget configurable.

/**
 * Sample Widget configuration class
 */
export interface SampleWidgetConfiguration extends GeneWidgetConfiguration {
    // Current widget instance title
    title?:string;
}

The configurator component will integrate with DOC by dispatching GeneWidgetConfigurationEvent events each time the user modify the configuration. The configurator is responsible for providing validation status of the edited configuration through those events. DOC will not let the user save a Widget configuration that is invalid. See sample-widget-configurator.component.ts in the sample widget source code.

/**
 * Copyright (c) DecisionBrain SAS. All Rights Reserved.
 *
 * This interface describes a component that can be instantiated dynamically (e.g. custom dashboard) and
 * initialized through a context object.
 *
 * By implementing this interface you make sure that a component is Custom Dashboard "ready"
 */
export interface GeneWidgetConfigurationAware<T extends GeneWidgetConfiguration> extends GeneWidgetContextAware {
    ...
}


/**
 * Copyright (c) DecisionBrain SAS. All Rights Reserved.
 *
 * Event class, describes the events triggered by a DynamicWidgetConfigurator each time
 * the context is modified by the user
 */
export class GeneWidgetConfigurationEvent<T extends GeneWidgetConfiguration> {

    /**
     * The current configured context
     */
    public configuration: T;

    /**
     * Event type
     */
    public type: GeneWidgetConfigurationEventType;

    /**
     * This object contains information about configuration validity and
     * potential error message if not valid.
     */
    public validationResult?: ValidationResult;
}

/**
 * Copyright (c) DecisionBrain SAS. All Rights Reserved.
 *
 * Type of events for GeneWidgetConfigurationEvent
 */
export enum GeneWidgetConfigurationEventType {
    CONFIGURATION_CHANGED
}

Enabling GeneWidgetStateAware allows you to save and restore some state properties of a widget. For more details, refer to Section Understanding Widget State.

GeneBaseDataWidgetComponent provides a base implementation of the Widget state management, and when using this class as the base class of a Widget the only methods that need to be overridden are:

restoreWidgetState(state: T);

getDefaultWidgetState(): T;

The provided Sample Map Widget illustrates how to use this API to save and restore the map position and zoom level.

/**
     * Method that is being called when the framework injects a widget state.
     *
     * This method restore the Map center from the saved stated.
     * @param widgetState
     */
    applyWidgetState(widgetState:SampleMapState) {
        if(widgetState) {
            this.center = {lat: widgetState.lat, lng: widgetState.lng};
            this.zoom = widgetState.zoom;
        }
    }

    /**
     * When the Map center or zoom change, this code saves the Widget state
     * through DOC API updateWidgetState(S) method.
     */
    onMapChanged() {
        const center = this.googleMap.getCenter();
        const zoom = this.googleMap.getZoom();
        this.updateWidgetState( { lat: center.lat(), lng: center.lng(), zoom: zoom});
    }

    getDefaultWidgetState(): SampleMapState {
        return {
            zoom: 5,
            lat: NYC_COORDINATES.lat,
            lng: NYC_COORDINATES.lng,
        }
    }

The base class GeneBaseDataWidget provides additional features like data loading mechanisms and event handlers.

Widgets inheriting this base class need to implement loadData() method that will be called automatically by DOC framework. Also if your component needs to use Angular OnInit life cycle hook, you will have to call super.ngOnInit(); in the ngOnInit() method so that GeneBaseDataWidget will be initialized properly.

Note that loadData() is automatically called by the framework and should never be called manually, if your widget needs to force data refresh, then you should call the requestLoadData() method.

This class also provides base methods you can override to integrate with the Framework Events. You can see Angular documentation for full details about how to integrate with DOC different events and life cycle.

    /**
     * Method called when the DynamicWidgetConfiguration is set.
     * You should configure your widget from widgetParameters by overriding this method
     * @param widgetParameters : widgetParameters that should be used to configure the state of the widget
     */
    protected applyWidgetConfiguration(widgetParameters: T) {
    }

    /**
     * This method is called when a GeneTaskEvent occurs.
     * Override it to implement custom behaviors
     */
    protected onGeneTaskEvent(event: GeneTaskEvent) {
    }

    /**
     * This method is called when a GeneScenarioEvent occurs.
     * Override it to implement custom behaviors
     */
    protected onGeneScenarioEvent(event: GeneScenarioEvent) {
    }

    /**
     * This method is called when a GeneUIEvent occurs.
     * Override it to implement custom behaviors
     */
    protected onGeneUIEvent(event: GeneUIEvent) {
    }

    /**
     * This method is called when a GeneDataEvent occurs.
     * Override it to implement custom behaviors
     * @param event
     */
    protected onGeneDataEvent(event: GeneDataEvent) {
    }


    /**
     * Handler automatically called when a GeneContextEvent of type HIGHLIGHT_CHANGED is received.
     * Override this method to handle those events in your widget implementation.
     *
     * @param event GeneContextEvent of type HIGHLIGHT_CHANGED
     */
    protected onContextHighlightChanged(event: GeneContextEvent) {
    }

    /**
     * Handler automatically called when a GeneContextEvent of type SCENARIO_CHANGED is received.
     *
     * Its base implementation calls the requestLoadData() method.
     *
     * Override this method to handle those events in your widget implementation.
     *
     * @param event GeneContextEvent of type SCENARIO_CHANGED
     */
    protected onContextScenarioChanged(event: GeneContextEvent) {
    }

    /**
     * Handler automatically called when a GeneContextEvent of type SELECTION_CHANGED is received.
     * Override this method to handle those events in your widget implementation.
     *
     * @param event GeneContextEvent of type SELECTION_CHANGED
     */
    protected onContextSelectionChanged(event: GeneContextEvent) {
    }

    /**
     * Handler automatically called when a GeneContextEvent of type FILTER_CHANGED is received.
     * Override this method to handle those events in your widget implementation.
     *
     * @param event GeneContextEvent of type FILTER_CHANGED
     */
    protected onContextFilterChanged(event: GeneContextEvent) {
    }

    /**
     * Handler automatically called each time data have been loaded.
     * @param data the loaded data
     */
    protected onDataLoaded(data: D) {
    }

    /**
     * Handler automatically called each time requestLoadData() is called but cannot be
     * executed because canLoadData() returned false.
     * @param data the loaded data
     */
    protected onCanNotLoadData() {
    }

    /**
     * Handler automatically called each time loadData() failed to load data.
     * @param error the data loading error
     */
    protected onLoadDataError(error: any) {
    }


    /**
     * This method should return either an observable emitting a single value or a boolean.
     *
     * Returning a true value means the widget framework can safely call loadData(), all
     * the required initializations are completed.
     *
     * Returning false means the widget is not ready to load data yet, and this method
     * will be called again upon #requestLoadData() next call.
     *
     * The default implementation checks that widgetConfiguration and context are set
     * and, in comparison mode, that the involved scenarios have a VALID data status.
     *
     * Override this method if you implement additional checks.
     */
    protected canLoadData(): boolean | Observable<boolean> {
    }

The Sample Widget integrated with Configuration and Data Loading mechanism:

@Component({
    selector : 'app-sample-widget',
    templateUrl : './sample-widget.component.html',
    styleUrls : ['./sample-widget.component.scss']
})
export class SampleWidgetComponent extends GeneBaseDataWidgetComponent<SampleWidgetConfiguration, SampleWidgetModel> {

    // Widget Manifest used
    public static MANIFEST: GeneWidgetManifest = {
        widgetTypeName : 'SampleWidgetComponent',
        configuratorTypeName: 'SampleWidgetConfiguratorComponent',
        version : '1.0',
        description : 'Simple Demo Sample Widget',
        name : 'Sample Widget',
        customViewCompatible : true,
        dashboardCompatible : true,
        minItemRows : 5,
        minItemCols : 5,
        itemRows : 5,
        itemCols : 5
    };

    constructor(protected injector: Injector,
                private service: SampleWidgetService,
                private toastrService: ToastrService) {
        super(injector);
    }

    // Called by the framework when required
    loadData(context: GeneContext): Observable<SampleWidgetModel> {
        return this.service.loadWidgetModel(context);
    }

    // Event handler when a user clicks on validate or invalidate
    onUpdateStatus(status: SampleScenarioStatus) {
        this.service.updateScenarioStatus(this._context, status)
            .pipe(
                tap( () => this.requestLoadData() )
            )
            .subscribe(
            result => this.toastrService.info('Scenario Updated with Status ' + status),
            error => this.toastrService.error('Error While Updating Status ' + error)
        );
    }
}

}