Getting started - XMPieLab/uStore-NG GitHub Wiki

This section will teach you how to set up the theme development environment and some theme technology basics, so you can start developing a theme using the new technology. Note that this technology can be used in stores built in version 10.0 and above.

Prerequisites

Environment prerequisites

  • A local machine with the Node.js installed.

    • For uStore v10 through v12.0, Node.js version 10.x is mandatory.
    • For uStore v12.1 through v13.4, Node.js version 12.x is mandatory.
    • For uStore v13.4 with patch 1961 and higher or v14 or later, Node.js version 16.3 is mandatory.
    • For uStore v17.0, Node.js version 18.18 is mandatory.
    • For uStore v17.2 and higher, Node.js version 20.18 and Python Version 3.9 are mandatory.

  • An Integrated Development Environment (IDE) for theme editing, such as Visual Studio Code, or Notepad++ with Command Prompt.

uStore prerequisites

  • A uStore server version 10 and above which you can access over HTTP from your local machine.
  • An online NG store (i.e. test store) available on uStore Back Office. The store should have at least one product category with at least one online product.
  • A uStore user who has permissions to access the test store.
  • (Optional) Credentials of a uStore user who has permissions to access uStore Back Office. This will enable you to download the initial theme package and upload the developed theme back to the server.

Setting up the environment

  1. Open uStore Back Office and go to Presets > Theme Management.

  2. Download XMPie’s AquaBlue theme to your local machine and extract the folder.

  3. Open the theme folder in an IDE, open the terminal and change the folder to src as follows:

    cd src

    The terminal path will now direct to the src folder.

  4. Install the node packages. In the terminal type:

    npm install

    All node packages will be installed without errors. You can ignore any warnings.

    NOTE: If you have uStore version 13.4 with patch 1961 and higher or version 14.x, please use the command: npm install --legacy-peer-deps This is not required for uStore version 17.0 and later.

  5. Start the application on the local node server, giving the uStore server URL as the parameter where the test store is located, and the API calls are directed to. In the terminal type:

    npm start -- server=<uStoreServerUrl>

    The theme will compile and you can browse to the local development server. If there are compilation errors, they will be listed in the terminal.

    NOTE: <uStoreServerUrl> is the full URL to the server containing the protocol and the external domain or server IP, e.g. http://uStoreServer/ or http://216.58.216.164/. During the development process for uStore versions before 17.2, the protocol must be set as "http". Therefore, the store should be defined as "Not Secured" (it's recommend to have a staging server or a testing store). If you are developing themes for v17.2 or later, you can use https, but hybrid pages (where .net components are loaded into an iframe) will not be available.

  6. Open a browser and in the address line type the following URL:

    http://localhost:3000/ustore?storeid=<storeID>&devmode=true&devthemename=<themeName>

    where the parameters are:

    storeID – The ID of your test store. The store ID can be found in the store list in uStore Back Office.

    devmode – Denotes that the environment is set to development.

    devthemename – The name of the theme that was originally downloaded (the value is case-sensitive so look for the value in the config.json file under "name" key).

    NOTES:

    • The port number has changed from 5000 to 3000 due to intersection with Mac used ports.
    • These parameters should always be present in the URL before logging into the store, in order to have a working development environment. Add them again if you are redirected to the login page during theme development as they will be removed from the URL.

  7. Log in to the store and check that the homepage is up and running.

  8. Develop the theme on the local environment as you would any other React project.

  9. When development is completed, create a theme package and upload it to the uStore Back Office, as described in Publishing the Theme.

Theme technology basics

The theme application is constructed of several areas, each built using a different technology.

  • The new areas of the application are the homepage, category page, header and footer, which are written in ReactJS technology. They have a modern UI and a responsive layout.

  • The remaining areas are legacy pages, written in ASPX and .NET technology. Their style is controlled by the legacy skin, adapted to work with the theme technology. The skin has a mobile version and is also supported in mobile devices in most areas of the application.

The legacy pages are hosted inside an iframe in the new React pages, so in fact routing is carried out using the React/Next.js routing mechanism to enable a natural flow of navigation in the store. The new React code includes a page with an iframe for each of the legacy pages, referred to as “hybrid” pages.

The React areas in the application and their style are entirely controlled by the theme development process. This is not the case for legacy pages. The code of legacy pages cannot be modified and the page style can be controlled only via the existing variables of the theme.

Notice that while developing the new areas of the theme, changes that you make to variables cannot be seen in legacy pages in the development environment. They will be visible only when you publish the theme and assign it to a store.

Training video

For a detailed example, watch the Setting up the development environment video in XMPie Campus.

⚠️ **GitHub.com Fallback** ⚠️