Theme tips and tricks - XMPieLab/uStore-NG GitHub Wiki

Upon the first loading of the application, the population of the Redux state takes place a-synchronously. As a result, when accessing data from the state or the custom state, the data may not yet be available, thus component rendering may fail. Note that while developing the theme it can work properly; however, when publishing the theme it may fail on the production environment. Therefore, it is important to write safer code and make sure the data already exists in the state and is ready for use.

For example, if you wish to add a welcome message with the name of the current user, add the following code to the homepage:

…
return (
      <Layout {...this.props} className="home">
        <div className="welcome-text">
          {currentUser && currentUser.FirstName}, welcome to the online store
        </div>
        <div className="promotion-wrapper">
…

Notice that the existence of the currentUser in the state is verified before accessing it’s FirstName property.

When adding a link in the code that directs to an internal page in the theme (for example when clicking a button or a link), use the LinkAria component. It is imported from the $core-components alias:

import { LinkAria } from '$core-components'

It can then be used in the code as follows:

<LinkAria to={urlGenerator.get({ page: 'contact-us' })}>
   CONTACT US
</LinkAria>

LinkAria accepts the following properties:

• to – the target URL. Normally produced by the urlGenerator service.
• reloadDocument – when true, navigation is performed as a full document load instead of a client-side route change.
• disabled – renders the link in a disabled state.

Any other property is passed through to the underlying link element.

For a detailed example, see "Adding a link to the new page" in Adding a new page.

Use LinkAria together with the urlGenerator service, which supplies the route to direct to, as described in General services. Using LinkAria keeps navigation handled by the theme's router in all environments. If directing to an external site, a regular anchor tag with href can be used.

The urlGenerator service helps to construct the internal application URL for the requested page. This service accesses the Redux state in order to know the current culture of the application. Therefore, if you add a code that requires using the urlGenerator, always place this code inside the component code and not outside, so that the data in the state will be available for the urlGenerator when needed.

It is occasionally needed to extract information from the URL of the application, such as query params or the current path.

In a function component, use the React Router hooks directly:

import { useParams, useSearchParams } from 'react-router-dom'

const MyComponent = () => {
  const { id } = useParams()
  const [searchParams] = useSearchParams()
  const mode = searchParams.get('mode')
  …
}

See the src\components\Layout\Header\Search.js component for a working example.

Class components cannot use hooks. If you still have one that needs routing information, convert it to a function component — the theme's own components were migrated the same way.

Notice that components which also need the uStore state use the withState HOC explained in the accessing uStore data section.

When developing new sections in the application, new text is often added. The text may be longer than its designated space in the UI. In this case, it is possible to limit the text length so that it will appear cut and show 3 dots at the end denoting that the full text is not shown (ellipsis). To limit the text of a single line, simply add the className truncate to the element containing the text. Example for the use of this class can be seen in the src\components\Layout\Header\SignOut.js component:

…
return (
    <div className="signout">
      <div className="info">
        <div className="title">{t('Profile.My_Account')}</div>
        <div className="greeting truncate">{t('SignOut.Hello_Message', {FirstName})}</div>
      </div>
      …
    </div>
  )
…

If the user’s first name is too long, it will truncate:

Page titles and meta description tags are produced by the HeadSEO component, which the theme's Layout component renders on every page. It derives the values from the store's SEO configuration and from the current page, so in most cases no change is required in the theme.

To change how titles are composed, edit src\components\Layout\HeadSEO.js in your custom theme.