# new EmptyStateComponent()
This component provides a standardized way to display empty state messages when no data is available or when a user needs to take an action to populate content. It includes customizable title, subtitle, icon, and action button elements that can be styled and configured through input properties. The component supports localization and can trigger navigation or custom actions when the button is clicked.
Component for displaying empty state messages with optional actions.
- Implements:
- OnInit
View Source lib/components/empty-state/empty-state.component.ts, line 53
Extends
Classes
- EmptyStateComponent
This component provides a standardized way to display empty state messages when no data is available or when a user needs to take an action to populate content. It includes customizable title, subtitle, icon, and action button elements that can be styled and configured through input properties. The component supports localization and can trigger navigation or custom actions when the button is clicked.
- EmptyStateComponent
Initializes a new EmptyStateComponent by calling the parent class constructor with the component name for logging and identification purposes. This component provides a standardized way to display empty state messages with optional icons and action buttons.
- 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.
Color
# buttonColor
Specifies the color for the button using Ionic's color system. This allows the button to match the application's color scheme.
The color of the action button.
- Default Value:
- 'primary'
View Source lib/components/empty-state/empty-state.component.ts, line 546
'clear'
|
'solid'
|
'outline'
# buttonFill
Controls the visual style of the button using Ionic's button fill options. 'solid' creates a button with a solid background, 'outline' creates a button with just a border, and 'clear' creates a button with no background or border.
The fill style of the action button.
- Default Value:
- 'solid'
View Source lib/components/empty-state/empty-state.component.ts, line 535
string
|
FunctionLike
|
undefined
# buttonLink
Specifies where the button should navigate to when clicked or what function it should execute. This can be either a URL string or a function that handles navigation. When not provided, the button will not perform any action.
The navigation target or action for the button.
'large'
|
'small'
|
'default'
# buttonSize
Controls the size of the button shown in the empty state. Can be 'large', 'small', or 'default' to accommodate different layout needs.
The size of the action button.
- Default Value:
- 'default'
View Source lib/components/empty-state/empty-state.component.ts, line 557
string
|
undefined
# buttonText
Specifies the label for the action button in the empty state. If translatable is true, this will be processed through the localization system. If not provided, the button will not display any text.
The text displayed on the action button.
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:
- ""
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"string
# icon
Specifies which icon to show when showIcon is true. The component uses the icon system defined in the application, and this value should correspond to an available icon name.
The name of the icon to display.
- Default Value:
- "ti-info-square-rounded"
View Source lib/components/empty-state/empty-state.component.ts, line 479
PredefinedColors
|
undefined
# iconColor
Specifies the color for the icon using Ionic's predefined color system. This allows the icon to match the application's color scheme.
The color of the displayed icon.
- Default Value:
- 'medium'
View Source lib/components/empty-state/empty-state.component.ts, line 501
'large'
|
'small'
|
undefined
# iconSize
Controls the size of the icon shown in the empty state. Can be either 'large' or 'small' to accommodate different layout needs.
The size of the displayed icon.
- Default Value:
- 'large'
View Source lib/components/empty-state/empty-state.component.ts, line 490
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
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: ""}
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.
- 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]
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:
- {}
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.
string
# searchValue
When the empty state is shown due to a search with no results, this property can hold the search term that was used. This can be displayed in the empty state message to provide context to the user.
The search value that resulted in no results.
StringOrBoolean
# showIcon
Determines if the visual icon should be shown in the empty state. This can be provided as a boolean or a string that will be converted to a boolean. Icons help visually communicate the empty state context to users.
Controls whether the icon is displayed.
- Default Value:
- true
View Source lib/components/empty-state/empty-state.component.ts, line 467
string
|
undefined
# subtitle
Provides additional context or instructions below the main title. This text is typically used to guide the user on what actions they can take. If translatable is true, this will be processed through the localization system.
The secondary message displayed in the empty state.
string
# subtitleColor
Specifies the color for the subtitle text using the application's color system. The value should correspond to a color variable defined in the application's theme. The component will automatically prefix this with "color-" to create the CSS class.
The color of the subtitle text.
- Default Value:
- 'gray-4'
View Source lib/components/empty-state/empty-state.component.ts, line 455
string
# title
Specifies the primary message to show in the empty state component. This text is typically used to inform the user about why they're seeing an empty view. If translatable is true, this will be processed through the localization system.
The main title displayed in the empty state.
- Default Value:
- "title"
View Source lib/components/empty-state/empty-state.component.ts, line 421
string
# titleColor
Specifies the color for the title text using the application's color system. The value should correspond to a color variable defined in the application's theme. The component will automatically prefix this with "color-" to create the CSS class.
The color of the title text.
- Default Value:
- 'gray-6'
View Source lib/components/empty-state/empty-state.component.ts, line 432
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.
- Overrides:
- 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.
Color
# static buttonColor
Specifies the color for the button using Ionic's color system. This allows the button to match the application's color scheme.
The color of the action button.
- Default Value:
- 'primary'
View Source lib/components/empty-state/empty-state.component.ts, line 179
'clear'
|
'solid'
|
'outline'
# static buttonFill
Controls the visual style of the button using Ionic's button fill options. 'solid' creates a button with a solid background, 'outline' creates a button with just a border, and 'clear' creates a button with no background or border.
The fill style of the action button.
- Default Value:
- 'solid'
View Source lib/components/empty-state/empty-state.component.ts, line 169
string
|
FunctionLike
|
undefined
# static buttonLink
Specifies where the button should navigate to when clicked or what function it should execute. This can be either a URL string or a function that handles navigation. When not provided, the button will not perform any action.
The navigation target or action for the button.
'large'
|
'small'
|
'default'
# static buttonSize
Controls the size of the button shown in the empty state. Can be 'large', 'small', or 'default' to accommodate different layout needs.
The size of the action button.
- Default Value:
- 'default'
View Source lib/components/empty-state/empty-state.component.ts, line 189
string
|
undefined
# static buttonText
Specifies the label for the action button in the empty state. If translatable is true, this will be processed through the localization system. If not provided, the button will not display any text.
The text displayed on the action button.
string
# static icon
Specifies which icon to show when showIcon is true. The component uses the icon system defined in the application, and this value should correspond to an available icon name.
The name of the icon to display.
- Default Value:
- "ti-info-square-rounded"
View Source lib/components/empty-state/empty-state.component.ts, line 118
PredefinedColors
|
undefined
# static iconColor
Specifies the color for the icon using Ionic's predefined color system. This allows the icon to match the application's color scheme.
The color of the displayed icon.
- Default Value:
- 'medium'
View Source lib/components/empty-state/empty-state.component.ts, line 138
'large'
|
'small'
|
undefined
# static iconSize
Controls the size of the icon shown in the empty state. Can be either 'large' or 'small' to accommodate different layout needs.
The size of the displayed icon.
- Default Value:
- 'large'
View Source lib/components/empty-state/empty-state.component.ts, line 128
string
# static searchValue
When the empty state is shown due to a search with no results, this property can hold the search term that was used. This can be displayed in the empty state message to provide context to the user.
The search value that resulted in no results.
StringOrBoolean
# static showIcon
Determines if the visual icon should be shown in the empty state. This can be provided as a boolean or a string that will be converted to a boolean. Icons help visually communicate the empty state context to users.
Controls whether the icon is displayed.
- Default Value:
- true
View Source lib/components/empty-state/empty-state.component.ts, line 107
string
|
undefined
# static subtitle
Provides additional context or instructions below the main title. This text is typically used to guide the user on what actions they can take. If translatable is true, this will be processed through the localization system.
The secondary message displayed in the empty state.
string
# static subtitleColor
Specifies the color for the subtitle text using the application's color system. The value should correspond to a color variable defined in the application's theme. The component will automatically prefix this with "color-" to create the CSS class.
The color of the subtitle text.
- Default Value:
- 'gray-4'
View Source lib/components/empty-state/empty-state.component.ts, line 96
string
# static title
Specifies the primary message to show in the empty state component. This text is typically used to inform the user about why they're seeing an empty view. If translatable is true, this will be processed through the localization system.
The main title displayed in the empty state.
- Default Value:
- "title"
View Source lib/components/empty-state/empty-state.component.ts, line 64
string
# static titleColor
Specifies the color for the title text using the application's color system. The value should correspond to a color variable defined in the application's theme. The component will automatically prefix this with "color-" to create the CSS class.
The color of the title text.
- Default Value:
- 'gray-6'
View Source lib/components/empty-state/empty-state.component.ts, line 75
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
# async getSearchSubtitle(content) → {Promise.<SafeHtml>}
This method takes a content string, typically the subtitle, and processes it through the translation service. It replaces a placeholder ('value0') with the actual search value, then sanitizes the result to safely use as HTML. This is particularly useful for displaying dynamic, localized messages in the empty state when a search yields no results.
Generates a localized and sanitized subtitle for search results.
Parameters:
| Name | Type | Description |
|---|---|---|
content |
string
|
The content string to be translated and processed |
A promise that resolves to a sanitized HTML string
Promise.<SafeHtml>
# handleClick() → {boolean|void|Promise.<boolean>}
This method is triggered when the user clicks the action button in the empty state component. It supports three navigation patterns: 1) no action when buttonLink is not provided, 2) custom function execution when buttonLink is a function, and 3) navigation to a specific URL when buttonLink is a string. This flexibility allows the empty state to trigger various actions based on the context in which it's used.
Handles click events on the action button.
- false if no action is taken
- The result of the buttonLink function if it's a function
- A Promise resolving to the navigation result if buttonLink is a URL
boolean
|
void
|
Promise.<boolean>
# 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()
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
# 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
# async ngOnInit() → {Promise.<void>}
Sets up the component by processing boolean inputs, applying localization to text elements if translation is enabled, and formatting CSS classes for title and subtitle colors. This method prepares the component for user interaction by ensuring all properties are properly initialized and localized.
Initializes the component after Angular first displays the data-bound properties.
Promise.<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
# 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 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