# new NgxBaseComponent(instance, locale, translatable, className, mode)
The NgxBaseComponent serves as the foundation for all Decaf UI components, providing shared functionality for localization, element references, and styling. This abstract class implements common properties and methods that are used across the component library, ensuring consistent behavior and reducing code duplication. Components that extend this class inherit its capabilities for handling translations, accessing DOM elements, and applying custom styling.
Base component class that provides common functionality for all Decaf components.
Parameters:
| Name | Type | Description |
|---|---|---|
instance |
string
|
The component instance token used for identification |
locale |
string
|
The locale to be used for translations |
translatable |
StringOrBoolean
|
Whether the component should be translated |
className |
string
|
Additional CSS classes to apply to the component |
mode |
"ios"
|
"md"
|
undefined
|
Component platform style |
Example
```typescriptClasses
- NgxBaseComponent
The NgxBaseComponent serves as the foundation for all Decaf UI components, providing shared functionality for localization, element references, and styling. This abstract class implements common properties and methods that are used across the component library, ensuring consistent behavior and reducing code duplication. Components that extend this class inherit its capabilities for handling translations, accessing DOM elements, and applying custom styling.
- NgxBaseComponent
Initializes a new instance of the base component with the provided instance token. This constructor sets up the fundamental properties required by all Decaf components, including the component name, locale settings, and logging capabilities. The instance token is used for component identification and locale derivation.
The constructor performs the following initialization steps:
- Sets the componentName from the provided instance token
- Derives the componentLocale from the class name using utility functions
- Initializes the logger instance for the component
Members
DecafRepository.<Model>
# protected _repository
Provides a connection to the data layer for retrieving and manipulating data.
This is an instance of the DecafRepository class from the @decaf-ts/core package,
which is initialized in the repository getter method.
The repository is used to perform CRUD (Create, Read, Update, Delete) operations on the data model, such as fetching data, creating new items, updating existing items, and deleting items. It also provides methods for querying and filtering data based on specific criteria.
The repository for interacting with the data model.
string
# className
Allows custom CSS classes to be added to the component's root element. These classes are appended to any automatically generated classes based on other component properties. Multiple classes can be provided as a space-separated string. This provides a way to customize the component's appearance beyond the built-in styling options.
Additional CSS class names to apply to the component.
- Default Value:
- ""
ElementRef
# component
Provides direct access to the native DOM element of the component through Angular's ViewChild decorator. This reference can be used to manipulate the DOM element directly, apply custom styles, or access native element properties and methods. The element is identified by the 'component' template reference variable.
Reference to the component's element.
string
# componentLocale
Stores the automatically derived locale based on the component's class name. This is determined during component initialization and serves as a fallback when no explicit locale is provided via the locale input property. The derivation is handled by the getLocaleFromClassName utility function, which extracts a locale identifier from the component's class name.
The locale derived from the component's class name.
string
# protected componentName
Stores the name of the component, which is typically derived from the class name. This property is used internally for various purposes such as logging, deriving the default locale, and potentially for component identification in debugging or error reporting.
The componentName is set during the component's initialization process and should not
be modified externally. It's marked as protected to allow access in derived classes while
preventing direct access from outside the component hierarchy.
The name of the component.
Example
// Inside a derived component class
console.log(this.componentName); // Outputs: "MyCustomComponent"boolean
# initialized
Tracks whether the component has completed its initialization process. This flag is used to prevent duplicate initialization and to determine if certain operations that require initialization can be performed.
Flag indicating if the component has been initialized
- Default Value:
- false
boolean
# initialized
Tracks whether the component has completed its initialization process. This flag is used to prevent duplicate initialization and to determine if certain operations that require initialization can be performed.
Flag indicating if the component has been initialized
- Default Value:
- false
Record.<string, unknown>
# item
Defines how list items should be rendered in the component. This property holds a configuration object that specifies the tag name and other properties needed to render list items correctly. The tag property identifies which component should be used to render each item in a list. Additional properties can be included to customize the rendering behavior.
Configuration for list item rendering
- Default Value:
- {tag: ""}
EventEmitter.<RendererCustomEvent>
# listenEvent
Emits custom events that occur within child components or the layout itself. This allows parent components to listen for and respond to user interactions or state changes within the grid layout. Events are passed up the component hierarchy to enable coordinated behavior across the application.
Event emitter for custom renderer events.
string
# locale
Specifies the locale identifier to use when translating component text. This can be set explicitly via input property to override the automatically derived locale from the component name. The locale is typically a language code (e.g., 'en', 'fr') or a language-region code (e.g., 'en-US', 'fr-CA') that determines which translation set to use for the component's text content.
The locale to be used for translations.
Record.<string, string>
# mapper
Defines how fields from the data model should be mapped to properties used by the component. This allows for flexible data binding between the model and the component's display logic.
Field mapping configuration.
"ios"
|
"md"
|
undefined
# mode
Controls the visual appearance of the component based on platform design guidelines. The 'ios' mode follows iOS design patterns, while 'md' (Material Design) follows Android/Google design patterns. This property affects various visual aspects such as animations, form elements, and icons. Setting this property allows components to maintain platform-specific styling for a more native look and feel.
Component platform style.
- Default Value:
- "md"
Model
|
undefined
# model
The data model repository that this component will use for CRUD operations. This provides a connection to the data layer for retrieving and manipulating data.
Repository model for data operations.
Array
# operations
Defines which CRUD operations (Create, Read, Update, Delete) are available for this component. This affects which operations can be performed on the data.
Available CRUD operations for this component.
- Default Value:
- [OperationKeys.READ]
string
# pk
Specifies which field in the model should be used as the primary key. This is typically used for identifying unique records in operations like update and delete.
Primary key field name for the model.
- Default Value:
- 'id'
Record.<string, unknown>
# props
Contains key-value pairs of dynamic properties that can be applied to the component at runtime. This flexible configuration object allows for dynamic property assignment without requiring explicit input bindings for every possible configuration option. Properties from this object are parsed and applied to the component instance through the parseProps method, enabling customizable component behavior based on external configuration.
Dynamic properties configuration object.
- Default Value:
- {}
string
|
StringOrBoolean
# renderChild
Determines if child components should be rendered by the component. This can be set to a boolean value or a string that can be converted to a boolean. When true, child components defined in the model will be rendered. When false, child components will be skipped. This provides control over the rendering depth.
Controls whether child components should be rendered
- Default Value:
- true
string
# rendererId
A unique identifier used to reference the component's renderer instance. This can be used for targeting specific renderer instances when multiple components are present on the same page.
Unique identifier for the renderer.
NgxRenderingEngine
# renderingEngine
Provides access to the NgxRenderingEngine singleton instance, which handles the rendering of components based on model definitions. This engine is used to extract decorator metadata and render child components.
Reference to the rendering engine instance
NgxRenderingEngine
# renderingEngine
Provides access to the NgxRenderingEngine singleton instance, which handles the rendering of components based on model definitions. This engine is used to extract decorator metadata and render child components.
Reference to the rendering engine instance
string
# route
Defines the base route path used for navigation actions related to this component. This is often used as a prefix for constructing navigation URLs.
Base route for navigation related to this component.
StringOrBoolean
# translatable
Controls whether the component's text content should be processed for translation. When true, the component will attempt to translate text using the specified locale. When false, text is displayed as-is without translation. This property accepts either a boolean value or a string that can be converted to a boolean (e.g., 'true', 'false', '1', '0').
Determines if the component should be translated.
- Default Value:
- false
string
|
number
# uid
A unique identifier for the current record being displayed or manipulated. This is typically used in conjunction with the primary key for operations on specific records.
Unique identifier for the current record.
string
# static className
Allows custom CSS classes to be added to the component's root element. These classes are appended to any automatically generated classes based on other component properties. Multiple classes can be provided as a space-separated string. This provides a way to customize the component's appearance beyond the built-in styling options.
Additional CSS class names to apply to the component.
- Default Value:
- ""
ElementRef
# static component
Provides direct access to the native DOM element of the component through Angular's ViewChild decorator. This reference can be used to manipulate the DOM element directly, apply custom styles, or access native element properties and methods. The element is identified by the 'component' template reference variable.
Reference to the component's element.
string
# static componentLocale
Stores the automatically derived locale based on the component's class name. This is determined during component initialization and serves as a fallback when no explicit locale is provided via the locale input property. The derivation is handled by the getLocaleFromClassName utility function, which extracts a locale identifier from the component's class name.
The locale derived from the component's class name.
string
# protected static componentName
Stores the name of the component, which is typically derived from the class name. This property is used internally for various purposes such as logging, deriving the default locale, and potentially for component identification in debugging or error reporting.
The componentName is set during the component's initialization process and should not
be modified externally. It's marked as protected to allow access in derived classes while
preventing direct access from outside the component hierarchy.
The name of the component.
Example
// Inside a derived component class
console.log(this.componentName); // Outputs: "MyCustomComponent"Record.<string, unknown>
# static item
Defines how list items should be rendered in the component. This property holds a configuration object that specifies the tag name and other properties needed to render list items correctly. The tag property identifies which component should be used to render each item in a list. Additional properties can be included to customize the rendering behavior.
Configuration for list item rendering
- Default Value:
- {tag: ""}
EventEmitter.<RendererCustomEvent>
# static listenEvent
Emits custom events that occur within child components or the layout itself. This allows parent components to listen for and respond to user interactions or state changes within the grid layout. Events are passed up the component hierarchy to enable coordinated behavior across the application.
Event emitter for custom renderer events.
string
# static locale
Specifies the locale identifier to use when translating component text. This can be set explicitly via input property to override the automatically derived locale from the component name. The locale is typically a language code (e.g., 'en', 'fr') or a language-region code (e.g., 'en-US', 'fr-CA') that determines which translation set to use for the component's text content.
The locale to be used for translations.
Record.<string, string>
# static mapper
Defines how fields from the data model should be mapped to properties used by the component. This allows for flexible data binding between the model and the component's display logic.
Field mapping configuration.
"ios"
|
"md"
|
undefined
# static mode
Controls the visual appearance of the component based on platform design guidelines. The 'ios' mode follows iOS design patterns, while 'md' (Material Design) follows Android/Google design patterns. This property affects various visual aspects such as animations, form elements, and icons. Setting this property allows components to maintain platform-specific styling for a more native look and feel.
Component platform style.
- Default Value:
- "md"
Model
|
undefined
# static model
The data model repository that this component will use for CRUD operations. This provides a connection to the data layer for retrieving and manipulating data.
Repository model for data operations.
# static operations
Defines which CRUD operations (Create, Read, Update, Delete) are available for this component. This affects which operations can be performed on the data.
Available CRUD operations for this component.
- Default Value:
- [OperationKeys.READ]
string
# static pk
Specifies which field in the model should be used as the primary key. This is typically used for identifying unique records in operations like update and delete.
Primary key field name for the model.
- Default Value:
- 'id'
Record.<string, unknown>
# static props
Contains key-value pairs of dynamic properties that can be applied to the component at runtime. This flexible configuration object allows for dynamic property assignment without requiring explicit input bindings for every possible configuration option. Properties from this object are parsed and applied to the component instance through the parseProps method, enabling customizable component behavior based on external configuration.
Dynamic properties configuration object.
- Default Value:
- {}
string
|
StringOrBoolean
# static renderChild
Determines if child components should be rendered by the component. This can be set to a boolean value or a string that can be converted to a boolean. When true, child components defined in the model will be rendered. When false, child components will be skipped. This provides control over the rendering depth.
Controls whether child components should be rendered
- Default Value:
- true
string
# static rendererId
A unique identifier used to reference the component's renderer instance. This can be used for targeting specific renderer instances when multiple components are present on the same page.
Unique identifier for the renderer.
string
# static route
Defines the base route path used for navigation actions related to this component. This is often used as a prefix for constructing navigation URLs.
Base route for navigation related to this component.
StringOrBoolean
# static translatable
Controls whether the component's text content should be processed for translation. When true, the component will attempt to translate text using the specified locale. When false, text is displayed as-is without translation. This property accepts either a boolean value or a string that can be converted to a boolean (e.g., 'true', 'false', '1', '0').
Determines if the component should be translated.
- Default Value:
- false
string
|
number
# static uid
A unique identifier for the current record being displayed or manipulated. This is typically used in conjunction with the primary key for operations on specific records.
Unique identifier for the current record.
Methods
# getLocale(translatable) → {string}
Determines which locale string to use for translation based on the translatable flag and available locale settings. This method first converts the translatable parameter to a boolean using the stringToBoolean utility function. If translatable is false, it returns an empty string, indicating no translation should be performed. If translatable is true, it checks for an explicitly provided locale via the locale property. If no explicit locale is available, it falls back to the componentLocale derived from the component's class name.
Gets the appropriate locale string based on the translatable flag and available locales.
Parameters:
| Name | Type | Description |
|---|---|---|
translatable |
StringOrBoolean
|
Whether the component should be translated |
The locale string to use for translation, or empty string if not translatable
string
# getModel(model) → {void}
Processes the provided model parameter, which can be either a Model instance or a string identifier. If a string is provided, it attempts to resolve the actual model from the injectables registry. After resolving the model, it calls setModelDefinitions to configure the component based on the model's metadata.
Resolves and sets the component's model
Parameters:
| Name | Type | Description |
|---|---|---|
model |
string
|
Model
|
The model instance or identifier string |
void
# getRoute() → {string}
Retrieves the route path for the component, generating one based on the model if no route is explicitly set. This method checks if a route is already defined, and if not, it creates a default route based on the model's constructor name. The generated route follows the pattern '/model/{ModelName}'. This is useful for automatic routing in CRUD operations.
Gets the route for the component
The route path for the component, or empty string if no route is available
string
# handleEvent(event) → {void}
Receives events from child renderer components and forwards them to parent components through the listenEvent output. This creates an event propagation chain that allows events to bubble up through the component hierarchy, enabling coordinated responses to user interactions across the layout structure.
Handles custom events from child components.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
RendererCustomEvent
|
The custom event from a child component |
void
# initialize() → {void}
Performs one-time initialization of the component. This method checks if the component has already been initialized to prevent duplicate initialization. When called for the first time, it sets the initialized flag to true and logs an initialization message with the component name. This method is typically called during the component's lifecycle setup.
Initializes the component
void
# ngOnChanges(changes) → {void}
This Angular lifecycle hook is called when input properties change. It responds to changes in the model, locale, or translatable properties by updating the component's internal state accordingly. When the model changes, it calls getModel to process the new model and getLocale to update the locale. When locale or translatable properties change, it calls getLocale to update the translation settings.
Handles changes to component inputs
Parameters:
| Name | Type | Description |
|---|---|---|
changes |
SimpleChanges
|
Object containing changed properties |
void
# protected parseProps(instance) → {void}
This method iterates through the properties of the provided instance object and applies any matching properties from the component's props configuration to the component instance. This allows for dynamic property assignment based on configuration stored in the props object, enabling flexible component customization without requiring explicit property binding for every possible configuration option.
The method performs a safe property assignment by checking if each key from the instance exists in the props object before applying it. This prevents accidental property overwriting and ensures only intended properties are modified.
Parses and applies properties from the props object to the component instance.
Parameters:
| Name | Type | Description |
|---|---|---|
instance |
KeyValue
|
The component instance object to process |
void
# protected repository() → {DecafRepository.<Model>}
Provides a connection to the data layer for retrieving and manipulating data.
This method initializes the _repository property if it is not already set, ensuring
that a single instance of the repository is used throughout the component.
The repository is used to perform CRUD operations on the data model, such as fetching data, creating new items, updating existing items, and deleting items. It also provides methods for querying and filtering data based on specific criteria.
Getter for the repository instance.
The initialized repository instance.
DecafRepository.<Model>
# setModelDefinitions(model) → {void}
Extracts and applies configuration from the model's decorators to set up the component. This method uses the rendering engine to retrieve decorator metadata from the model, then configures the component's mapper and item properties accordingly. It ensures the route is properly set and merges various properties from the model's metadata into the component's configuration.
Configures component properties based on model metadata
Parameters:
| Name | Type | Description |
|---|---|---|
model |
Model
|
The model to extract configuration from |
void
# trackItemFn(index, item) → {string|number}
Provides a tracking function for Angular's *ngFor directive to optimize rendering performance. This method generates unique identifiers for list items based on their index and content, allowing Angular to efficiently track changes and minimize DOM manipulations during list updates. The tracking function is essential for maintaining component state and preventing unnecessary re-rendering of unchanged items.
Tracks items in ngFor loops for optimal change detection.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number
|
The index of the item in the list |
item |
KeyValue
|
string
|
number
|
The item data to track |
A unique identifier for the item
string
|
number