# new ListComponent()
This component provides a flexible way to display lists of data with support for infinite scrolling, pagination, searching, and custom item rendering. It can fetch data from various sources including models, functions, or direct data input.
The component supports two main display types:
- Infinite scrolling - Loads more data as the user scrolls
- Pagination - Displays data in pages with navigation controls
Additional features include:
- Pull-to-refresh functionality
- Search filtering
- Empty state customization
- Custom item rendering
- Event emission for interactions
A versatile list component that supports various data display modes.
- Implements:
- OnInit
Example
<ngx-decaf-list
[source]="dataSource"
[limit]="10"
[type]="'infinite'"
[showSearchbar]="true"
(clickEvent)="handleItemClick($event)"
(refreshEvent)="handleRefresh($event)">
</ngx-decaf-list>Extends
Classes
- ListComponent
This component provides a flexible way to display lists of data with support for infinite scrolling, pagination, searching, and custom item rendering. It can fetch data from various sources including models, functions, or direct data input.
The component supports two main display types:
- Infinite scrolling - Loads more data as the user scrolls
- Pagination - Displays data in pages with navigation controls
Additional features include:
- Pull-to-refresh functionality
- Search filtering
- Empty state customization
- Custom item rendering
- Event emission for interactions
- ListComponent
Creates a new ListComponent and sets up the base component with the appropriate component name. This constructor is called when Angular instantiates the component and before any input properties are set. It passes the component name to the parent class constructor to enable proper localization and component identification.
The constructor is intentionally minimal, with most initialization logic deferred to the ngOnInit lifecycle hook. This follows Angular best practices by keeping the constructor focused on dependency injection and basic setup, while complex initialization that depends on input properties is handled in ngOnInit.
- 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.
- Overrides:
- Default Value:
- ""
EventEmitter.<KeyValue>
# clickEvent
Emits an event when a list item is clicked. The event includes the data of the clicked item, allowing parent components to respond to the interaction.
Event emitter for item click interactions.
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"Array.<KeyValue>
|
undefined
# data
Provides a way to directly pass data to the list component instead of fetching it from a source. When both data and source are provided, the component will use the source to fetch data only if the data array is empty.
Direct data input for the list component.
- Default Value:
- undefined
View Source lib/components/list/list.component.ts, line 1413
StringOrBoolean
# disableSort
When set to true, disables the sort controls and prevents users from changing the sort order or field. The list will maintain its default or programmatically set sort configuration without user interaction.
Controls whether sorting functionality is disabled.
- Default Value:
- false
View Source lib/components/list/list.component.ts, line 1583
Partial.<IListEmptyResult>
# empty
Customizes how the empty state is displayed when no data is available. This includes the title, subtitle, button text, icon, and navigation link.
Configuration for the empty state display.
- Default Value:
- { title: 'empty.title', subtitle: 'empty.subtitle', showButton: false, icon: 'alert-circle-outline', buttonText: 'locale.empty.button', link: '' }
View Source lib/components/list/list.component.ts, line 1612
string
|
undefined
# emptyIcon
Specifies the icon shown in the empty state when no data is available. This can be any icon name supported by the application's icon system.
Icon to display when the list is empty.
- Default Value:
- 'ti-database-exclamation'
View Source lib/components/list/list.component.ts, line 1594
StringOrBoolean
# enableFilter
When set to true, enables the filter component that allows users to create complex search criteria with multiple field filters, conditions, and values. When false, disables the filter interface entirely.
Controls whether the filtering functionality is enabled.
- Default Value:
- true
View Source lib/components/list/list.component.ts, line 1551
Array.<string>
# indexes
Provides a list of index names that can be used to optimize data querying and filtering operations, especially in scenarios with large datasets.
Indexes can significantly improve the performance of data retrieval by allowing the database to quickly locate and retrieve relevant data based on indexed fields.
List of available indexes for data querying and filtering.
- Default Value:
- []
View Source lib/components/list/list.component.ts, line 1775
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
- Overrides:
- Default Value:
- false
StringOrBoolean
# inset
When set to true, the list will have inset styling with rounded corners and margin around the edges. This creates a card-like appearance for the list.
Controls whether the list has inset styling.
- Default Value:
- false
View Source lib/components/list/list.component.ts, line 1484
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
- Overrides:
- Default Value:
- {tag: ""}
Array.<KeyValue>
# items
Stores the current set of items being displayed in the list after processing from the raw data source. This may be a subset of the full data when using pagination or infinite scrolling.
The processed list items ready for display.
number
# lastPage
Keeps track of the previously displayed page number, which is useful for handling navigation and search operations in paginated mode.
The last page number that was displayed.
- Default Value:
- 1
View Source lib/components/list/list.component.ts, line 1703
number
# limit
Determines how many items are loaded at once during pagination or infinite scrolling. This affects the size of data chunks requested from the source.
The number of items to fetch per page or load operation.
- Default Value:
- 10
View Source lib/components/list/list.component.ts, line 1448
"inset"
|
"full"
|
"none"
# lines
Determines how dividing lines appear between list items. Options include:
- "inset": Lines are inset from the edges
- "full": Lines extend the full width
- "none": No dividing lines
The style of dividing lines between list items.
- Default Value:
- "full"
View Source lib/components/list/list.component.ts, line 1473
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.
StringOrBoolean
# loadMoreData
When set to true, the component will allow loading additional data through infinite scrolling or pagination. When false, the component will not attempt to load more data beyond what is initially displayed.
Controls whether more data can be loaded.
- Default Value:
- true
View Source lib/components/list/list.component.ts, line 1460
SpinnerTypes
# loadingSpinner
Specifies the visual style of the loading spinner shown during data fetching operations. Uses Ionic's predefined spinner types.
The type of spinner to display during loading operations.
- Default Value:
- "circular"
View Source lib/components/list/list.component.ts, line 1539
string
|
undefined
# loadingText
Specifies the text shown in the loading indicator when the component is fetching data. If not provided, a default loading message will be used.
Custom text to display during loading operations.
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.
- Overrides:
- 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.
- Overrides:
- Default Value:
- [OperationKeys.READ]
number
# page
Tracks which page is currently being displayed when the component is in paginated mode. This is used for pagination controls and data fetching.
The current page number in paginated mode.
- Default Value:
- 1
View Source lib/components/list/list.component.ts, line 1623
number
# pages
Stores the calculated total number of pages based on the data size and limit. This is used for pagination controls and boundary checking.
The total number of pages available.
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.
- Overrides:
- 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.
- Overrides:
- Default Value:
- {}
EventEmitter.<BaseCustomEvent>
# refreshEvent
Emits an event when the list data is refreshed, either through pull-to-refresh or programmatic refresh. The event includes the refreshed data and component information.
Event emitter for refresh operations.
boolean
# refreshing
When true, the component is currently fetching new data. This is used to control loading indicators and prevent duplicate refresh operations from being triggered simultaneously.
Indicates whether a refresh operation is in progress.
- Default Value:
- false
View Source lib/components/list/list.component.ts, line 1645
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
- Overrides:
- 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
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.
"bottom"
|
"top"
# scrollPosition
Determines whether new items are added to the top or bottom of the list when loading more data through infinite scrolling.
The position where new items are added during infinite scrolling.
- Default Value:
- "bottom"
View Source lib/components/list/list.component.ts, line 1507
string
# scrollThreshold
Specifies how close to the bottom of the list the user must scroll before the component triggers loading of additional data. This is expressed as a percentage of the list height.
The threshold for triggering infinite scroll loading.
- Default Value:
- "15%"
View Source lib/components/list/list.component.ts, line 1496
string
|
undefined
# searchValue
Stores the text entered in the search bar. This is used to filter the list data or to send as a search parameter when fetching new data.
The current search query value.
StringOrBoolean
# showRefresher
When set to true, enables the pull-to-refresh functionality that allows users to refresh the list data by pulling down from the top of the list.
Controls the visibility of the pull-to-refresh feature.
- Default Value:
- true
View Source lib/components/list/list.component.ts, line 1528
StringOrBoolean
# showSearchbar
When set to true, displays a search bar at the top of the list that allows users to filter the list items. The search functionality works by filtering the existing data or by triggering a new data fetch with search parameters.
Controls the visibility of the search bar.
- Default Value:
- true
View Source lib/components/list/list.component.ts, line 1401
Array.<string>
# skeletonData
Contains placeholder items that are displayed during data loading. The length of this array determines how many skeleton items are shown.
Array used for rendering skeleton loading placeholders.
- Default Value:
- new Array(2)
View Source lib/components/list/list.component.ts, line 1656
string
|
KeyValue
|
undefined
# sortBy
Specifies how the fetched data should be sorted. This can be provided as a string (field name with optional direction) or a direct object.
Sorting parameters for data fetching.
string
|
KeyValue
|
undefined
# sortDirection
Specifies how the fetched data should be sorted. This can be provided as a string (field name with optional direction) or a direct object.
Sorting parameters for data fetching.
string
|
FunctionLike
# source
Specifies where the list should fetch its data from. This can be either:
- A string URL or endpoint identifier
- A function that returns data when called The component will call this source when it needs to load or refresh data.
The data source for the list component.
number
# start
Specifies the index from which to start fetching data. This is used for pagination and infinite scrolling to determine which subset of data to load.
The starting index for data fetching.
- Default Value:
- 0
View Source lib/components/list/list.component.ts, line 1437
StringOrBoolean
# translatable
When set to true, the component will attempt to use translation services for any text content. This allows for internationalization of the list component.
Controls whether the component uses translation services.
- Overrides:
- Default Value:
- true
View Source lib/components/list/list.component.ts, line 1389
ListComponentsTypes
# type
Determines how the list data is loaded and displayed. Options include:
- INFINITE: Loads more data as the user scrolls (infinite scrolling)
- PAGINATED: Displays data in pages with navigation controls
The display mode for the list component.
- Default Value:
- ListComponentsTypes.INFINITE
View Source lib/components/list/list.component.ts, line 1378
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.
EventEmitter.<KeyValue>
# static clickEvent
Emits an event when a list item is clicked. The event includes the data of the clicked item, allowing parent components to respond to the interaction.
Event emitter for item click interactions.
Array.<KeyValue>
|
undefined
# static data
Provides a way to directly pass data to the list component instead of fetching it from a source. When both data and source are provided, the component will use the source to fetch data only if the data array is empty.
Direct data input for the list component.
- Default Value:
- undefined
StringOrBoolean
# static disableSort
When set to true, disables the sort controls and prevents users from changing the sort order or field. The list will maintain its default or programmatically set sort configuration without user interaction.
Controls whether sorting functionality is disabled.
- Default Value:
- false
Partial.<IListEmptyResult>
# static empty
Customizes how the empty state is displayed when no data is available. This includes the title, subtitle, button text, icon, and navigation link.
Configuration for the empty state display.
- Default Value:
- { title: 'empty.title', subtitle: 'empty.subtitle', showButton: false, icon: 'alert-circle-outline', buttonText: 'locale.empty.button', link: '' }
string
|
undefined
# static emptyIcon
Specifies the icon shown in the empty state when no data is available. This can be any icon name supported by the application's icon system.
Icon to display when the list is empty.
- Default Value:
- 'ti-database-exclamation'
StringOrBoolean
# static enableFilter
When set to true, enables the filter component that allows users to create complex search criteria with multiple field filters, conditions, and values. When false, disables the filter interface entirely.
Controls whether the filtering functionality is enabled.
- Default Value:
- true
Array.<string>
# static indexes
Provides a list of index names that can be used to optimize data querying and filtering operations, especially in scenarios with large datasets.
Indexes can significantly improve the performance of data retrieval by allowing the database to quickly locate and retrieve relevant data based on indexed fields.
List of available indexes for data querying and filtering.
- Default Value:
- []
StringOrBoolean
# static inset
When set to true, the list will have inset styling with rounded corners and margin around the edges. This creates a card-like appearance for the list.
Controls whether the list has inset styling.
- Default Value:
- false
Array.<KeyValue>
# static items
Stores the current set of items being displayed in the list after processing from the raw data source. This may be a subset of the full data when using pagination or infinite scrolling.
The processed list items ready for display.
number
# static lastPage
Keeps track of the previously displayed page number, which is useful for handling navigation and search operations in paginated mode.
The last page number that was displayed.
- Default Value:
- 1
number
# static limit
Determines how many items are loaded at once during pagination or infinite scrolling. This affects the size of data chunks requested from the source.
The number of items to fetch per page or load operation.
- Default Value:
- 10
"inset"
|
"full"
|
"none"
# static lines
Determines how dividing lines appear between list items. Options include:
- "inset": Lines are inset from the edges
- "full": Lines extend the full width
- "none": No dividing lines
The style of dividing lines between list items.
- Default Value:
- "full"
StringOrBoolean
# static loadMoreData
When set to true, the component will allow loading additional data through infinite scrolling or pagination. When false, the component will not attempt to load more data beyond what is initially displayed.
Controls whether more data can be loaded.
- Default Value:
- true
SpinnerTypes
# static loadingSpinner
Specifies the visual style of the loading spinner shown during data fetching operations. Uses Ionic's predefined spinner types.
The type of spinner to display during loading operations.
- Default Value:
- "circular"
string
|
undefined
# static loadingText
Specifies the text shown in the loading indicator when the component is fetching data. If not provided, a default loading message will be used.
Custom text to display during loading operations.
number
# static page
Tracks which page is currently being displayed when the component is in paginated mode. This is used for pagination controls and data fetching.
The current page number in paginated mode.
- Default Value:
- 1
number
# static pages
Stores the calculated total number of pages based on the data size and limit. This is used for pagination controls and boundary checking.
The total number of pages available.
EventEmitter.<BaseCustomEvent>
# static refreshEvent
Emits an event when the list data is refreshed, either through pull-to-refresh or programmatic refresh. The event includes the refreshed data and component information.
Event emitter for refresh operations.
boolean
# static refreshing
When true, the component is currently fetching new data. This is used to control loading indicators and prevent duplicate refresh operations from being triggered simultaneously.
Indicates whether a refresh operation is in progress.
- Default Value:
- false
"bottom"
|
"top"
# static scrollPosition
Determines whether new items are added to the top or bottom of the list when loading more data through infinite scrolling.
The position where new items are added during infinite scrolling.
- Default Value:
- "bottom"
string
# static scrollThreshold
Specifies how close to the bottom of the list the user must scroll before the component triggers loading of additional data. This is expressed as a percentage of the list height.
The threshold for triggering infinite scroll loading.
- Default Value:
- "15%"
string
|
undefined
# static searchValue
Stores the text entered in the search bar. This is used to filter the list data or to send as a search parameter when fetching new data.
The current search query value.
StringOrBoolean
# static showRefresher
When set to true, enables the pull-to-refresh functionality that allows users to refresh the list data by pulling down from the top of the list.
Controls the visibility of the pull-to-refresh feature.
- Default Value:
- true
StringOrBoolean
# static showSearchbar
When set to true, displays a search bar at the top of the list that allows users to filter the list items. The search functionality works by filtering the existing data or by triggering a new data fetch with search parameters.
Controls the visibility of the search bar.
- Default Value:
- true
Array.<string>
# static skeletonData
Contains placeholder items that are displayed during data loading. The length of this array determines how many skeleton items are shown.
Array used for rendering skeleton loading placeholders.
- Default Value:
- new Array(2)
string
|
KeyValue
|
undefined
# static sortBy
Specifies how the fetched data should be sorted. This can be provided as a string (field name with optional direction) or a direct object.
Sorting parameters for data fetching.
string
|
KeyValue
|
undefined
# static sortDirection
Specifies how the fetched data should be sorted. This can be provided as a string (field name with optional direction) or a direct object.
Sorting parameters for data fetching.
string
|
FunctionLike
# static source
Specifies where the list should fetch its data from. This can be either:
- A string URL or endpoint identifier
- A function that returns data when called The component will call this source when it needs to load or refresh data.
The data source for the list component.
number
# static start
Specifies the index from which to start fetching data. This is used for pagination and infinite scrolling to determine which subset of data to load.
The starting index for data fetching.
- Default Value:
- 0
StringOrBoolean
# static translatable
When set to true, the component will attempt to use translation services for any text content. This allows for internationalization of the list component.
Controls whether the component uses translation services.
- Default Value:
- true
ListComponentsTypes
# static type
Determines how the list data is loaded and displayed. Options include:
- INFINITE: Loads more data as the user scrolls (infinite scrolling)
- PAGINATED: Displays data in pages with navigation controls
The display mode for the list component.
- Default Value:
- ListComponentsTypes.INFINITE
Methods
# async clearSearch() → {Promise.<void>}
Convenience method that clears the search by calling handleSearch with undefined. This resets the list to show all data without filtering.
Clears the current search and resets the list.
Promise.<void>
# async getFromModel(force, start, limit) → {Promise.<Array.<KeyValue>>}
Retrieves data from the configured model using its pagination or find methods, processes it, and updates the component's data state. This method handles both initial data loading and subsequent refresh operations when using a model as the data source.
Fetches data from a model source.
Parameters:
| Name | Type | Description |
|---|---|---|
force |
boolean
|
Whether to force a refresh even if data already exists |
start |
number
|
The starting index for pagination |
limit |
number
|
The maximum number of items to retrieve |
A promise that resolves to the fetched data
Promise.<Array.<KeyValue>>
# async getFromRequest(force, start, limit) → {Promise.<Array.<KeyValue>>}
Retrieves data from the configured source function or URL, processes it, and updates the component's data state. This method handles both initial data loading and subsequent refresh operations when using an external data source rather than a model.
Fetches data from a request source.
Parameters:
| Name | Type | Description |
|---|---|---|
force |
boolean
|
Whether to force a refresh even if data already exists |
start |
number
|
The starting index for pagination |
limit |
number
|
The maximum number of items to retrieve |
A promise that resolves to the fetched data
Promise.<Array.<KeyValue>>
# 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
# getMoreData(length) → {void}
Calculates whether more data is available and how many pages exist based on the total number of items and the configured limit per page. This information is used to control pagination UI and infinite scrolling behavior.
Updates pagination state based on data length.
Parameters:
| Name | Type | Description |
|---|---|---|
length |
number
|
The total number of items available |
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
# handleClick(event) → {void}
Listens for global ListItemClickEvent events and passes them to the debounced click subject. This allows the component to respond to clicks on list items regardless of where they originate from.
Handles click events from list items.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
ListItemCustomEvent
|
RendererCustomEvent
|
The click event |
void
# async handleCreate(uid) → {Promise.<void>}
Handles the create event from the repository.
Handles the create event from the repository.
Parameters:
| Name | Type | Description |
|---|---|---|
uid |
string
|
number
|
The ID of the item to create. |
A promise that resolves when the item is created and added to the list.
Promise.<void>
# handleDelete(uid, pk) → {Promise.<void>}
Filters out an item with the specified ID from the data array and refreshes the list display. This is typically used after a delete operation.
Removes an item from the list by ID.
Parameters:
| Name | Type | Description |
|---|---|---|
uid |
string
|
The ID of the item to delete |
pk |
string
|
The primary key field name |
Promise.<void>
# 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
# async handleFilter(value) → {Promise.<void>}
Processes filter queries from the filter component and applies them to the list data. This method acts as a bridge between the filter component and the search functionality, converting filter queries into search operations.
Handles filter events from the filter component.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
IFilterQuery
|
undefined
|
The filter query object or undefined to clear filters |
Promise.<void>
# async handleObserveEvent(table, event, uid) → {Promise.<void>}
Processes repository change events (CREATE, UPDATE, DELETE) and performs the appropriate list operations. This includes adding new items, updating existing ones, or removing deleted items from the list display.
Handles specific repository events and updates the list accordingly.
Parameters:
| Name | Type | Description |
|---|---|---|
table |
string
|
The table/model name that changed |
event |
OperationKeys
|
The type of operation (CREATE, UPDATE, DELETE) |
uid |
string
|
number
|
The unique identifier of the affected item |
Promise.<void>
# handlePaginate(event) → {void}
Processes pagination events by updating the current page number and refreshing the list data to display the selected page. This method is called when a user interacts with the pagination controls to navigate between pages.
Handles pagination events from the pagination component.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
PaginationCustomEvent
|
The pagination event containing page information |
void
# async handleRefresh(eventopt) → {Promise.<void>}
Processes refresh events triggered by the user pulling down on the list or by programmatic refresh requests. This method refreshes the list data and completes the refresher animation when the data is loaded.
Handles pull-to-refresh events from the refresher component.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
event |
InfiniteScrollCustomEvent
|
CustomEvent
|
<optional> |
The refresh event |
A promise that resolves when the refresh operation is complete
Promise.<void>
# async handleSearch(value) → {Promise.<void>}
Processes search queries from the search bar component, updating the displayed data based on the search term. The behavior differs between infinite and paginated modes to provide the best user experience for each mode.
Handles search events from the search bar.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string
|
undefined
|
The search term or undefined to clear search |
Promise.<void>
# initialize()
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
# protected itemMapper(item, mapper, propsopt) → {KeyValue}
Transforms a data item according to the mapping configuration, extracting nested properties and formatting values as needed. This allows the component to display data in a format different from how it's stored.
Maps a single item using the configured mapper.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
item |
KeyValue
|
The item to map |
|
mapper |
KeyValue
|
The mapping configuration |
|
props |
KeyValue
|
<optional> |
Additional properties to include |
The mapped item
KeyValue
# mapResults(data) → {Array.<KeyValue>}
Applies the itemMapper to each item in the result set, adding common properties like operations and route information. This transforms the raw data into the format expected by the list item components.
Maps all result items using the configured mapper.
Parameters:
| Name | Type | Description |
|---|---|---|
data |
Array.<KeyValue>
|
The array of items to map |
The array of mapped items
Array.<KeyValue>
# 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
# ngOnDestroy() → {void}
Performs cleanup operations when the component is being removed from the DOM. This includes clearing references to models and data to prevent memory leaks.
Cleans up resources when the component is destroyed.
void
# async ngOnInit() → {Promise.<void>}
Sets up the component by initializing event subscriptions, processing boolean inputs, and loading the initial data. This method prepares the component for user interaction by ensuring all properties are properly initialized and data is loaded.
Initializes the component after Angular sets the input properties.
Promise.<void>
# async observeRepository(…args) → {Promise.<void>}
Processes repository change notifications and routes them appropriately. For CREATE events with a UID, handles them immediately. For other events, passes them to the debounced observer subject to prevent excessive updates.
Handles repository observation events with debouncing.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
args |
Array.<unknown>
|
<repeatable> |
The repository event arguments including table, event type, and UID |
Promise.<void>
# parseConditions(value) → {Condition.<Model>}
Transforms search input or complex filter queries into Condition objects that can be used for database querying. Handles both simple string/number searches across indexed fields and complex filter queries with multiple criteria.
For simple searches (string/number):
- Creates conditions that search across all indexed fields
- Uses equality for numeric values and regex for string values
- Combines conditions with OR logic to search multiple fields
For complex filter queries:
- Processes each filter item with its specific condition type
- Supports Equal, Not Equal, Contains, Not Contains, Greater Than, Less Than
- Updates sort configuration based on the filter query
- Combines multiple filter conditions with OR logic
Converts search values or filter queries into database conditions.
Parameters:
| Name | Type | Description |
|---|---|---|
value |
string
|
number
|
IFilterQuery
|
The search value or filter query object |
A Condition object for database querying
Condition.<Model>
# 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
# async protected parseResult(result) → {Array.<KeyValue>}
Handles different result formats from various data sources, extracting pagination information when available and applying any configured data mapping. This ensures consistent data structure regardless of the source.
Processes query results into a standardized format.
Parameters:
| Name | Type | Description |
|---|---|---|
result |
Array.<KeyValue>
|
Paginator
|
The raw query result |
The processed array of items
Array.<KeyValue>
# parseSearchResults(results, search) → {Array.<KeyValue>}
Processes the current data array to find items that match the provided search string. This uses the arrayQueryByString utility to perform the filtering across all properties of the items.
Filters data based on a search string.
Parameters:
| Name | Type | Description |
|---|---|---|
results |
Array.<KeyValue>
|
The array of items to search through |
search |
string
|
The search string to filter by |
A promise that resolves to the filtered array of items
Array.<KeyValue>
# async refresh(event) → {Promise.<void>}
This method handles both initial data loading and subsequent refresh operations, including pull-to-refresh and infinite scrolling. It manages the data fetching process, updates the component's state, and handles pagination or infinite scrolling logic based on the component's configuration.
The method performs the following steps:
- Sets the refreshing flag to indicate a data fetch is in progress
- Calculates the appropriate start and limit values based on pagination settings
- Fetches data from the appropriate source (model or request)
- Updates the component's data and emits a refresh event
- Handles pagination or infinite scrolling state updates
- Completes any provided event (like InfiniteScrollCustomEvent)
Refreshes the list data from the configured source.
Parameters:
| Name | Type | Description |
|---|---|---|
event |
InfiniteScrollCustomEvent
|
RefresherCustomEvent
|
boolean
|
The event that triggered the refresh, or a boolean flag indicating if this is a forced refresh |
A promise that resolves when the refresh operation is complete
Promise.<void>
# refreshEventEmit(dataopt) → {void}
Creates and emits a refresh event containing the current list data. This notifies parent components that the list data has been refreshed.
Emits a refresh event with the current data.
Parameters:
| Name | Type | Attributes | Description |
|---|---|---|---|
data |
Array.<KeyValue>
|
<optional> |
Optional data to include in the event |
void
# 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 |
- Overrides:
void
# trackItemFn(index, item) → {string|number}
Provides a tracking function for the *ngFor directive in the component template.
This function is used to identify and control the rendering of items in the list,
preventing duplicate or unnecessary rendering.
The trackItemFn function takes two parameters: index (the index of the item in the list)
and item (the actual item from the list). It returns the tracking key, which in this case
is the union of the uid of the item with the model name.
Function for tracking items in the list.
Parameters:
| Name | Type | Description |
|---|---|---|
index |
number
|
The index of the item in the list. |
item |
KeyValue
|
string
|
number
|
The actual item from the list. |
The tracking key for the item.
string
|
number