Loaders in the frontend frameworks
This is an article for advanced users of Frontastic.
Loaders in the Frontastic frontend framework are used to make modifications to backend data, for example, adding a product to the cart or logging in a user. In this article, we'll show you how to use them and display the feedback from them to the user.
The general idea
The loaders can be retrieved from the application to handle all operations regarding, for example, the user account, cart, and wishlist.
An example of what a full component using loaders, data resulting from loader actions, and informs the customer about potential errors could look like:
import React, { Component } from 'react'
import PropTypes from 'prop-types'
import AtomsInput from '...'
import AtomsButton from '...'
import app from '@frontastic/catwalk/src/js/app/app'
import Notifications from '@frontastic/catwalk/src/js/component/notifications'
class Login extends Component {
constructor (props) {
super(props)
this.state = {
login_email: '',
login_password: '',
}
}
render () {
if (this.props.context.session.loggedIn) {
return false
}
return (<form className='c-form'>
<Notifications />
<AtomsInput label='Email' type='email'
value={this.state.login_email}
onChange={(event) => {
this.setState({ login_email: event.target.value })
}}
/>
<AtomsPassword label='Password' type='password'
value={this.state.login_password}
onChange={(event) => {
this.setState({ login_password: event.target.value })
}}
/>
<AtomsButton type='primary' full
onClick={(event) => {
app.getLoader('context').login(
this.state.login_email,
this.state.login_password
)
}}>
Login
</AtomsButton>
</form>)
}
}
Login.propTypes = {
context: PropTypes.object.isRequired,
}
export default tastify({
connect: {
context: true,
}
})(Login)
We'll look into 3 important topics in more detail:
- Retrieving the current state using
tastify
(line 56) - Changing the state on the server using
app.getLoader(...).<action>(...)
(line 41) - Displaying notifications using the
<Notifications />
helper component (line 26)
1. Using Tastify
While you can connect directly to the Redux state tastify
is the optimized way to access the relevant information and we'll ensure this API stays backwards compatible. Especially the 3 most important concerns regarding loaders can be retrieved using Tastify: context
, cart
and wishlist
. You'll find more info about tastify
in this article.
2. Using the loaders
Loaders in Frontastic allow you to modify information in the connected backend systems. All loaders can be retrieved using the app.getLoader(...)
function from @frontastic/catwalk/src/js/app/app
as you can see in the full example above. The result from the loader will be handled by Frontastic and you can expect your component to be updated accordingly.
Cart
The cart
loader is used to modify the cart, add items, and additional information to it. The available methods are:
Cart::get(parameters = {})
– Explicitly get the cart again but usually isn't necessaryCart::getOrder(parameters = {})
– Retrieve a certain order from the backend but usually isn't necessaryCart::setProductOption(productId, option)
– Set additional options on a variant line item in the cart identified by its product ID (this is only used for special cart items)Cart::add(product = null, variant, count, option = null)
– Add a variant line item to the cartCart::addMultiple(lineItems)
– Add multiple line items to the cart at onceCart::addPayment(cartInformation)
– Add payment information to the cartCart::updateLineItem(update)
– Update a line item in the cart (most likely its count)Cart::removeLineItem(update)
– Remove line item from cartCart::updateCart(cartInformation)
– Update cart information, like shipping or billing addresses or any other of the available fieldsCart::redeemDiscount(code)
– Add a discount code to the cartCart::removeDiscount(discountId)
– Remove a discount code from the cartCart::checkout(cartInformation)
– Try to convert the cart into a placed order (this will only work on "completed" carts (all information available and paid))
Account (Context)
The context
loader is used for all account-related actions, from register and login to managing the user's addresses. The available methods are:
Context::refresh(parameters)
– Update the user context (login state) (called automatically on log in and register)Context::register(user, redirect = true)
– Register a new userContext::login(email, password, previous = null)
– Log in a user with the provided credentialsContext::logout()
– Log out a userContext::addAddress(address)
– Add an address to the user's address listContext::updateAddress(address)
– Update an existing addressContext::removeAddress(address)
– Remove an address from the listContext::setDefaultBillingAddress(address)
– Set an address as the default billing addressContext::setDefaultShippingAddress(address)
– Set an address as the default shipping addressContext::updateUser(user)
– Update user informationContext::requestPasswordReset(email)
– Request a password reset for a userContext::resetPassword(token, newPassword)
– Reset the password to a new password with the password request token the user retrieved by mailContext::updatePassword(oldPassword, newPassword)
– Update the users password (with the old and new password)Context::notifyUser(message, type = 'info', timeout = 5000)
– Notify a user about something (most actions, and even cart actions, do this automatically. This can include user-focused errors.)
Wishlist
The wishlist
loader is used to manage the products on the user's wish list and the list of available wish lists if there are multiple. The available methods are:
Wishlist::get(parameters = {})
– Explicitly get the wish list again but usually isn't necessaryWishlist::create(name)
– Create another wishlist with the given nameWishlist::add(product, variant, count, wishlist = null)
– Add a product (line item) to a wishlistWishlist::addMultiple(lineItems)
– Add multiple products (line items) to a wishlist at onceWishlist::updateLineItem(wishlist, update)
– Update a line item inside the wishlistWishlist::removeLineItem(wishlist, update)
– Remove a line item from a wishlist
3. Using the notifications helper
The <Notifications />
helper component from @frontastic/catwalk/src/js/component/notifications
displays all user notifications. It can be embedded anywhere on the page and will always display all pending notifications. Some notifications (success) will automatically hide again after 5 seconds, while some notifications will stay until the user removes them (errors).
You can overwrite the default AtomsNotification
by using the component injector. For this, you could add something similar to the below to your src/js/injection.js
:
import MyNotification from 'my/notification'
ComponentInjector.set('AtomsNotification', MyNotification)
A good way to use this component could be either to embed this in every form or just embed this into a commonly used header component.
See the injecting custom components and reducers article for more info on the component injector.
Updated over 2 years ago