Actions
Actions are one of the main building blocks in NgRx architecture. Actions represent unique events that happen throughout our application.
Actions are used in many ways in NgRx. Actions are the inputs and outputs of systems in NgRx. Actions help you to understand how events are handled in our application.
Â
The Action interface
An Action in NgRx is formed by a simple interface:
interface Action {
type: string;
}
The interface has only one property, and it is the type that is represented as a string. The type property is for performing the action that will be dispatched in our application. Here the value of the type comes in the form of [Source] Event. value is used to provide a context of what category of action it is, and where the action was dispatched from. We add properties to an action to provide additional context or metadata for an action.
Below are examples of actions:
{
type: '[Auth API] Login Success'
}
After interacting with a backend API, this action describes an event triggered by a successful authentication.
{
type: '[Login Page] Login',
username: string;
password: string;
}
This action performs an event that is triggered by a user clicking on the login button from the login page in an attempt to authenticate a user. Additional metadata provided from the login page is defined as username and password.
Â
Writing actions
There are some rules to writing effective actions within your application.
- Upfront - it is used to write actions before developing new features to understand and gain a shared knowledge of that feature in advance.
- Divide - Based on the event source it will categorize actions.
- Many - As the more actions you write, the better you express flows in your application.
- Event-Driven - capture events using that separating the description of an event and the handling of that event.
- Descriptive - it provides an environment that is targeted to a unique event with more detailed information.
Let's see an example of an action that is initiating a login request.
import { createAction, props } from '@ngrx/store';
export const login = createAction(
'[Login Page] Login',
props<{ username: string; password: string }>()
);
Above the createAction function returns a function. When called returns an object in the shape of the Action interface. To define any additional metadata needed for the handling of the action, the props method is used. Action creators provide a type-safe and consistent way to construct an action that is being dispatched.
To return the Action when dispatching, use the action creator.
onSubmit(username: string, password: string) {
store.dispatch(login({ username: username, password: password }));
}
The login action creator receives username and password as an object and returns a plain JavaScript object with a type property of [Login Page] Login, and username and password as additional properties.
The returned action has context about where the action came from and what event happened.
- The category of the action is held within the square brackets [].
- The category is used to make group actions for a particular area like a component page, backend API, or browser API.
- The Login text after the category is a description of what event occurred from this action. In this case, to attempt to authenticate with a username and password the user clicked a login button from the login page.