{ this.renderTitle() }
{ this.renderStep() }
{ this.renderSummary() }
This is where all the individual UI components live. For example, there's the Header and Footer components, which are used on all pages, as well as the CheckoutPayment component, which is only used in the checkout payment step.
Each component has its own UI logic and styling.
| | `route` | All the different pages of Scandi are defined here. The cart page, the category page, the home page and many others β each has their own folder inside `route`. Their job is to bring the different components together to create entire pages. | | `style` | All the "global" styles that apply to the page as a whole (and are not specific to a single component) go here. | ## π¨ Customizing Your App The app works, but looks just like any other Scandi app. You probably want to customize some of its features. As a first step, let's customize the copyright footer. Before we can modify its code, we need to know which component is responsible for rendering the Footer. We can use the browser's developer tools to find out. First, inspect the HTML element associated with the footer:  The developer tools should open, giving you information about the element. The element you selected will appear highlighted:  Note the class of the element you found. This might be slightly different depending on where you clicked β in our case, it is `Footer-Copyright`. What does this tell us about the component? Because Scandi follows strict [Block-Element-Modifier (BEM)](/structure/building-blocks-summary/components/styling-components#the-bem-methodology) conventions, this gives us the name of the component β `Footer` (the first part of the class, called the Block, is always the same as the component name). Now that we have found out the name of the component, there is only one place we need to look β the `component` directory in `node_modules/@scandipwa/scandipwa/src/`. Indeed, we can find a component named Footer there: {% code title="Original File in scandipwa/src/component/Footer/Footer.component.js" %} ```javascript // [...] export class Footer extends PureComponent { // [...] renderCopyrightContent() { const { copyright } = this.props; return (| Timeline | Plans | Status |
|---|---|---|
| Q4 2021 |
| Complete |
| Q1 + Q2 2022 |
| Complete |
| Q3 + Q4 2022 |
| In Progress |
* Overrides are contained in their own package and contain project-specific changes. They make it easy to **customize the presentation layer without modifying the source code**. To learn more about how to create application plugins, please follow the link below: {% content-ref url="/pages/-MVFUrrqeCkdXcB5fosC" %} [Extensions](/developing-with-scandi/extensions) {% endcontent-ref %} # CMA, CSA, and ScandiPWA Ecosystem overview The Scandi technology stack was built to support two modes: * **Storefront mode** β the statically compiled web application which uses a remote Magento 2 instance as the data source. Usually served by a non-Magento server, thus reducing the costs of maintenance and time-to-first-byte (TTFB).
* **Magento theme mode** β the statically compiled Magento 2 theme, served by Magento and getting data from the same Magento 2 instance it's hosted on. The main advantages of this approach are better SEO and higher customizability from the admin interface. To make the development in both modes easier, we introduced multiple toolchains to streamline the setup process: * **Create Magento App (CMA)** βΒ a toolchain that allows you to setup Magento 2 applications on your computer or server in a single command.
* **Create ScandiPWA App (CSA)** β a toolchain that implements the Override Mechanism, application plugins, and both building modes. It allows creating ScandiPWA applications in a single command. It is common to install both ScandiPWA and Magento on the local machine to develop efficiently. THe following open-source technologies are made by the ScandiPWA team: * [Create ScandiPWA App](/#create-scandipwa-app) * [ScandiPWA theme](/#scandipwa-theme) * [Create Magento App](/#create-magento-app) ## Create ScandiPWA App Create ScandiPWA App is an officially supported way to create ScandiPWA applications. It offers a modern build setup with no configuration. ### How does it work? The core of the CSA is a well-known Create React App - an officially supported way to create single-page React applications.  With a [CRACO](https://github.com/gsoft-inc/craco) (**C**reate **R**eact **A**pp **C**onfiguration **O**verride) plugin on top, we can use all Create React App features and still be able to customize ESLint, Babel, and other configurations.  [Create ScandiPWA App](https://docs.create-scandipwa-app.com) implements [Override](https://docs.create-scandipwa-app.com/themes/parent-themes) and [Plugin](https://docs.create-scandipwa-app.com/extensions/extensions) mechanisms on top of CRACO. It can be used to develop React applications while enjoying an enhanced development experience.  ## ScandiPWA Theme Alongside a new way of building your React applications, we created an open-source PWA theme for Magento 2. [ScandiPWA](https://scandipwa.com/) theme is enabling you to build a faster, smoother, and offline-enabled experience for your customers, boosting conversion rates. It is built on Progressive Web App (PWA) technology, which is increasingly favored by companies such as Amazon, [Alibaba](https://developers.google.com/web/showcase/2016/alibaba#results) and Uber due to its UX improvements.  The ScandiPWA theme is fully customizable. It introduces a new PWA front-end for Magento 2 alongside the back-end Magento modules with GraphQL endpoints needed to cover all Magento 2 features. ## Create Magento App When it comes to the back-end development, we introduce you the [Create Magento App](https://docs.create-magento-app.com/) - the fastest way of setting up Magento locally. This deployment technology combines two powerful approaches of containerization and Infrastructure as code to provision you a Magento 2 instance in minutes. With just one command line, you can [link](https://docs.create-magento-app.com/usage-guide/themes) your Create Magento App together with your Create ScandiPWA App, and build your Magento 2 PWA store locally.  # Challenges The challenges of creating a PWA for Magento and how we overcome them ## SEO Search Engine Optimization (SEO) is important to us, as it drives organic search discoverability and sales. It involves making sure that search engines can crawl the application to index its content. Traditionally, crawlers are not built to handle Client-Side Rendered (CSR) applications. CSR happens entirely in JavaScript, and most crawlers don't run JavaScript at all - therefore, they will be unable to see the application's content unless we take this into consideration. While some crawlers may now be able to run JavaScript, we still need to ensure that all search engines can index our app. This can be achieved with several different approaches, all of which involve rendering part of the app on the server, and responding with that result. [Dynamic rendering](https://developers.google.com/search/docs/guides/dynamic-rendering): the web server needs to detect crawlers. For crawlers, it serves a pre-rendered version of the app, but for other clients, it serves the regular JavaScript app. {% hint style="info" %} Pre-rendering: the frontend App is run on the server, in a headless browser. The resulting HTML is served instead of the app. {% endhint %} ## API Complexity The traditional style of building APIs is [REST](https://restfulapi.net/). It involves creating multiple endpoints that the client can use to fetch and manipulate resources. However, for a large application such as Magento, the REST approach starts encountering problems: * Increasing numbers of endpoints are hard to keep track of and remember * Additional data returned by each endpoint (sometimes unnecessarily) grows the size of the response To address these problems, Magento also supports a [GraphQL](https://graphql.org/) API. ScandiPWA builds on the GraphQL API and uses it in the frontend app, due to its advantages: * GraphQL only offers 1 endpoint with well-documented queries * The client can now request only the data it needs, saving bandwidth * Endpoints and their datatypes are documented when defining the schema, which is checked by GraphQL ### GraphQL Caching Using GraphQL creates an additional challenge - we need to find a way to cache API requests, which could easily be done with REST. By default, Magento sends the full query as a stringified JSON parameter, to take advantage of `GET` request caching. Despite this method's simplicity, it creates a limitation in query size, as the maximum URL length cannot be exceeded. In addition, this strategy requires the full query to be sent every time, increasing bandwidth usage. ScandiPWA uses an alternative approach - the persisted query method. Initially introduced by [Apollo](https://www.apollographql.com/), this approach involves transforming each query into a short identifier, which solves the caching problem and saves bandwidth, at the cost of some additional requests made. # Setting up Scandi Learn about different installation modes ScandiPWA recommends developing applications locally. We have created two tools in order to make this process of installation smooth. They are as follows: | Use... | ...if you need: | | ----------------------------------------------------------------------------------------------- | ------------------------- | | [`create-scandipwa-app`](https://docs.create-scandipwa-app.com/getting-started/getting-started) | A **ScandiPWA front-end** | | [`create-magento-app`](https://docs.create-magento-app.com/getting-started/getting-started) | A **Magento back-end** | It is possible to combine these setups to deploy ScandiPWA in multiple modes: * [Storefront mode (CSA)](/getting-started-1#storefront-mode-csa) * [Magento theme mode (CSA + CMA)](/getting-started-1#magento-theme-mode-csa-cma) {% hint style="danger" %} If you are **deploying ScandiPWA on a production server** or you would like to **develop on a remote server** (via SSH, for example), please follow the link below. {% endhint %} {% content-ref url="/pages/-MP3PlnAtlis8uSWi5pe" %} [Existing Magento 2 setup](/getting-started-1/magento-integration) {% endcontent-ref %} ## **Storefront mode (CSA)** In Standalone storefront mode - the **front-end is running on a small separate server** and uses a remote Magento 2 instance as the source for the data. {% hint style="info" %} In this mode, **you are not required to run Magento 2 locally** to develop. {% endhint %} When using this mode it is enough to have a ScandiPWA theme powered by **CSA (Create ScandiPWA App)** to compile it. As a data source, you can use any existing [properly configured](/getting-started-1/storefront-mode#configuring-the-magento-server) Magento 2 instance or create a ready Magento 2 instance using [RMG (ReadyMage)](https://readymage.com). {% content-ref url="/pages/-MUxW5d\_bCOq1\_Inrj1D" %} [Storefront Mode Setup](/getting-started-1/storefront-mode) {% endcontent-ref %} ## Magento theme mode (CSA + CMA) In Magento 2 theme mode - the front-end is statically compiled and **served by Magento 2 server**. In this case, data comes directly from the same server the application is hosted on. {% hint style="info" %} In this mode, **you are required to run Magento 2 locally** to develop. {% endhint %} When developing a Magento 2 theme, the local installation of Magento 2 is required. In order to simplify the local Magento 2 installation, we created **CMA (Create Magento App)** toolchain, with a goal to start a Magento 2 instance with a single command. The **CSA (Create ScandiPWA App)** toolchain will still be used to compile a theme. {% content-ref url="/pages/-MUxW7Lyak4clRkIK5\_U" %} [Magento Mode Setup](/getting-started-1/magento-theme-mode) {% endcontent-ref %} # Storefront Mode Setup Run Scandi as an separate app ## Summary * [ ] Ensure you have Node v12 or newer on your development machine * [ ] `npx create-scandipwa-app my-app` to create a new app * [ ] `cd my-app` to enter your app's directory * [ ] `npm start` to run the app These commands will create a new Scandi app, start it up, and open it in your browser. ## Creating a ScandiPWA App Youβll need to have Node >= 12 on your local development machine (but itβs not required on the server). You can use [n](https://www.npmjs.com/package/n) (macOS, Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to switch Node versions between different projects. To create a new app, you may choose one of the following methods: {% tabs %} {% tab title="NPX" %} ```bash npx create-scandipwa-app my-app ``` {% endtab %} {% tab title="NPM" %} ``` npm init scandipwa-app my-app ``` {% endtab %} {% tab title="Yarn" %} ``` yarn create scandipwa-app my-app ``` {% endtab %} {% endtabs %} ## Output Running any of these commands will create a directory called `my-app` inside the current folder. Inside that directory, it will generate the initial project structure and install the transitive dependencies. More details: {% content-ref url="/pages/-MUxZ3slqBE7329uexmH" %} [Directory Structure](/structure/folder-structure) {% endcontent-ref %} ## Available Commands Inside the newly created project, you can run some [built-in commands](/developing-with-scandi/developer-tools/available-commands): ### `npm start` or `yarn start` Runs the app in development mode. Will open the [http://localhost:3000](http://localhost:3000/) to preview changes in your default browser.\ \ The page will automatically reload if you make changes to the code. You will see the build errors and lint warnings in the console. ### `npm run build` or `yarn build` Builds the app for production to the `build` folder. It correctly bundles React in production mode and optimizes the build for the best performance. The build is minified and the filenames include the hashes.Your app is ready to be deployed. ## Connecting to a Magento server By default, your new application will be fetching data from a remote store. If you want to use your own Magento instance, you can either create a new **CMA** ([by following this guide](https://docs.create-magento-app.com/getting-started/getting-started)) or set up a Magento instance manually. After that, you must configure it to include ScandiPWA-specific modules ([as described here](/getting-started-1/storefront-mode#configuring-the-magento-server)). ## Configuring the Magento server To use Magento 2 as a data source for ScandiPWA, you are required to make sure that it is using the correct Composer dependencies. The list of your application Composer dependencies can be found in your ScandiPWA application's `composer.json` file. You can copy the dependencies defined in `require` field of your application's `composer.json` to your Magento server's root `composer.json` and execute the `composer update` command. # Proxying requests to server To tell the development server to proxy requests to your Magento 2 server, modify a `proxy` field to your `package.json`, for example: ```javascript "proxy": "http://localhost:4000", ``` {% hint style="warning" %} ### Heads up! This feature is only supported in `development` (when using [`start` command](/developing-with-scandi/developer-tools/available-commands#npm-start-or-yarn-start)). {% endhint %} ## Configuring proxy manually If the `proxy` option is **not** flexible enough for you, you can get direct access to the Express app instance and hook up your own proxy middleware. You can use this feature in conjunction with the `proxy` property in `package.json`, but it is recommended you consolidate all of your logic into `src/setupProxy.js`. First, install `http-proxy-middleware` using npm or Yarn: ```bash npm install http-proxy-middleware --save # for NPM yarn add http-proxy-middleware # for Yarn ``` Next, create `src/setupProxy.js` and place the following contents in it: ```javascript const { createProxyMiddleware } = require('http-proxy-middleware'); module.exports = function(app) { // ... }; ``` You can now register proxies as you wish! Here's an example using the above `http-proxy-middleware`: ```javascript const { createProxyMiddleware } = require('http-proxy-middleware'); module.exports = function(app) { app.use( '/graphql', createProxyMiddleware({ target: 'http://localhost:5000', changeOrigin: true, }) ); }; ``` {% hint style="warning" %} ### Heads up! You do not need to import this file anywhere. It is automatically registered when you start the development server. {% endhint %} ## Configuring Magento 2 server To use Magento 2 as a data source for ScandiPWA, you are required to make sure that it is using the correct Composer dependencies. The list of your application Composer dependencies can be found in your ScandiPWA application's `composer.json` file. You can copy the dependencies defined in `require` field of your application's `composer.json` to your Magento server's root `composer.json` and execute the `composer update` command. # Magento Mode Setup Build Scandi as a Magento theme This guide requires 5 steps to be completed in sequence: 1. [Create a new Create Magento App](/getting-started-1/magento-theme-mode#create-a-new-create-magento-app) 2. [Create a new Create Scandipwa App](/getting-started-1/magento-theme-mode#create-a-new-create-scandipwa-app) 3. [Link Magento App with ScandiPWA App](/getting-started-1/magento-theme-mode#link-magento-app-with-scandipwa-app) 4. [Run ScandiPWA App in Magento mode](/getting-started-1/magento-theme-mode#4-run-scandipwa-app-in-magento-mode) 5. [Change Magento theme to ScandiPWA](/getting-started-1/magento-theme-mode#5-change-magento-theme-to-scandipwa) ## 1. Create a new Create Magento App ### Install dependencies Before setting up, make sure you have installed the **libraries required to build the PHP**. The list of these libraries can be found here: for [Linux](https://docs.create-magento-app.com/getting-started/prerequisites/installation-on-linux) and [macOS](https://docs.create-magento-app.com/getting-started/prerequisites/installation-on-macos). Also, make sure to install **Docker** and **PHPBrew** in your system. ### Quick Start ```bash # make sure dependencies are installed !!! npx create-magento-app my-app cd my-app npm start ``` This command will start Docker services, start PHP and open your favorite browser with Magento 2 store. Create Magento App choose an available port for Magento 2 so it can vary. By default, it will use port 80 so the URL for the store will be [http://localhost:80/](http://localhost/). ### Creating a Magento App {% hint style="warning" %} ### **Make sure your Node version is up to date!** **Youβll need to have Node >= 12 on your local development machine** (but itβs not required on the server). You can use [n](https://www.npmjs.com/package/n) (macOS, Linux) or [nvm-windows](https://github.com/coreybutler/nvm-windows#node-version-manager-nvm-for-windows) to switch Node versions between different projects. {% endhint %} To create a new app, you may choose one of the following methods: {% tabs %} {% tab title="NPX" %} ```bash npx create-magento-app my-app ``` {% endtab %} {% tab title="NPM" %} ``` npm init magento-app my-app ``` {% endtab %} {% tab title="Yarn" %} ``` yarn create magento-app my-app ``` {% endtab %} {% endtabs %} ### Output Running any of these commands will create a directory called `my-app` inside the current folder. Inside that directory, it will generate the initial project structure and install the transitive dependencies. Learn more in [the folder structure guide](https://docs.create-magento-app.com/getting-started/folder-structure). {% hint style="info" %} **In case of issues** - please refer to [Create Magento App FAQ.](https://docs.create-magento-app.com/troubleshooting/common-issues) {% endhint %} ## 2. Create a new Create Scandipwa App The ScandiPWA App creation very similar to Storefront mode, however, **the Magento 2 server configuration is not required** as we will install our ScandiPWA as composer dependency for our newly created Magento 2 server, later in this guide. {% content-ref url="/pages/-MUxW5d\_bCOq1\_Inrj1D" %} [Storefront Mode Setup](/getting-started-1/storefront-mode) {% endcontent-ref %} ## 3. Link Magento App with ScandiPWA App The Create Magento App (CMA) comes with a built-in mechanism for ScandiPWA theme linking. In order to link a ScandiPWA theme with CMA project, execute the following command from CMA project root: {% tabs %} {% tab title="NPM" %} ```bash npm run link -- ./path/to/your/scandipwa-app ``` {% endtab %} {% tab title="Yarn" %} ``` yarn run link ./path/to/your/scandipwa-app ``` {% endtab %} {% endtabs %} {% hint style="info" %} This command will link your ScandiPWA theme from your selected path as a symbolic link and will [disable the "Full Page" cache](https://docs.magento.com/user-guide/system/cache-full-page.html). {% endhint %} ## 4. Run ScandiPWA App in Magento mode Run the command below from your ScandiPWA App directory: {% tabs %} {% tab title="Mac, Linux" %} ```bash BUILD_MODE=magento npm run start ``` {% endtab %} {% tab title="Windows" %} ```bash set BUILD_MODE=magento && npm run start & set BUILD_MODE= ``` {% endtab %} {% endtabs %} This command will now watch the files and put their compiled versions into the `magento/Magento_Theme` folder. ## 5. Change Magento theme to ScandiPWA Go to your Magento Admin panel (by default it can be accessed on `/admin`), **Content > Configuration**, choose a website that you want to apply theme on, click **Edit** and select your theme, click **Save**! Open your store URL and the ScandiPWA theme should be online. ## What's next? Learn what features and why we added on-top-of React + Redux stack: {% content-ref url="/pages/-MVVgnQHeo0DBRZnPZN8" %} [Introduction to the Stack](/introduction) {% endcontent-ref %} # Existing Magento 2 setup The ScandiPWA theme integrates seamlessly with Magento You might want to install ScandiPWA as a Magento theme (without using [Create Magento App](http://docs.create-magento-app.com/)) β and this is supported out of the box! You can install the theme as a local composer module, continuously build it, and Magento will be able to recognize it as a valid Magento theme. Then, you will be able to select your ScandiPWA-based theme in the Magento configuration. {% hint style="info" %} If you are using[ Create Magento App ](https://scandipwa.gitbook.io/create-magento-app/)you're lucky! It has a built-in ScandiPWA linking function built-in. Read how to [setup ScandPWA with CMA](/getting-started-1/magento-theme-mode) in minutes! {% endhint %} ## Prerequisites Make sure that you have a [supported Magento version](https://manual.scandipwa.com/pwa/magento-version-mapping)! Also, make sure your server is configured to point into `
Persisted query Redis password
(empty password is not allowed)
etc
registration.php
theme.xml
\
Now moved outside src, the new path is public.
The file index.production.phtml is renamed to index.php, and index.development.html is renamed to index.html.
Removed. The webpack configuration now lives in the
@scandipwa/scandipwa-scripts package. To modify this configuration, use build configuration plugins.
We have overridden the ProductCard component!
); } } export default ProductCard; ``` {% endcode %} Now, any import using the alias `Component/ProductCard/Component/ProductCard.component` will resolve to your newly-created file. Indeed, if you check the product list page, you will see the updated component:  ## Detailed overriding examples Despite the general rule being simple, it is important to learn more details. See the detailed guide on overriding class-based and non-class-based files below. {% content-ref url="/pages/-MV1eywHRTP7i-3joJLh" %} [Overriding classes](/developing-with-scandi/override-mechanism/extending-javascript/overriding-classes) {% endcontent-ref %} {% content-ref url="/pages/-MV1f2OzsGu5HXo42hWZ" %} [Overriding non-classes](/developing-with-scandi/override-mechanism/extending-javascript/overriding-non-classes) {% endcontent-ref %} ## Overriding Tutorial Specific examples of how to use the Override Mechanism for common tasks can be found in our [tutorial](/tutorials/customizing-your-theme/customizing-javascript)! {% content-ref url="/pages/-MNcSxs181lV3ZBK6-HK" %} [Broken mention](broken://pages/-MNcSxs181lV3ZBK6-HK) {% endcontent-ref %} # Overriding classes Virtually always, you will want to keep part of the default functionality and only modify some aspect of the existing class. This is how the theme is usually extended. For example, when overriding `ProductCard`, suppose we want to keep the default ScandiPWA implementation of the component, but with one change - we don't want the product images to be visible in the product cards. In order to do this, we will make sure our class extends the base `ProductCard` class. Then, it will inherit the default functionality from its parent class, and we will be able to override any part of it. All we need to do is import the original `ProductCard` class, extend it, and re-export the modified version. But there is one challenge: as mentioned before, if we try to import from `Component/ProductCard/ProductCard.component`, the import mechanism will resolve this to our overridden implementation, not the desired original class. Hence, it is impossible to import the original class from the parent theme using the `Component` alias if we intend to override this class. The solution is to use another alias, `SourceComponent` to extend classes from the parent theme. {% hint style="info" %} The ScandiPWA import mechanism provides the `Source` aliases to enable you to directly import from the parent theme, regardless of whether there is an overridden version available**.** Similarly, you can use the `SourceRoute` alias to import directly from a route defined in the parent theme, or the `SourceUtil` alias to import an utility file from the parent theme. {% endhint %} {% code title="override: component/ProductCard/ProductCard.component.js" %} ```jsx import { PureComponent } from 'react'; // we use the SourceComponent alias to explicitly import from the parent theme // (if we would use Component/ProductCard/... instead, we would be trying to import // the current file, which would result in an error) import { ProductCard as SourceProductCard } from 'SourceComponent/ProductCard/ProductCard.component'; // we imported the original ProductCard class defined in the parent theme. // we aliased the import to `SourceProductCard` to indicate that SourceProductCard // is the parent theme version of the class // you should always copy over the namespace declaration when overriding an existing class // to avoid breaking plugins /** @namespace Component/ProductCard/Component */ export class ProductCard extends SourceProductCard { // we can now extend SourceProductCard, // and override any methods we want to change // this method overrides the default implementation provided in the original ProductCard class renderPicture() { // returning null in a React component means rendering nothing return null; } } // we now export the extended and modified version of the class export default ProductCard; ``` {% endcode %} {% hint style="success" %} You should never have to copy any code from the parent theme to reuse it. **It is a good practice to always import functions, classes, and values from the parent theme when you want to extend them**, as shown above. Following this pattern will result in cleaner code - it will be immediately clear which functions your code changes by overriding them. In addition, there will be less code to maintain, resulting in faster development. {% endhint %} Indeed, we can check that now, the `ProductCard` component is the same as in the default theme, with one change: it no longer has a picture.  {% hint style="warning" %} When overriding a JavaScript file, **you should make the same exports as the file you are overriding**. If the original theme file exports a certain constant, it is possible that other classes (or third party plug-ins) will expect that they can import this value. If you forget to re-export it when overriding the file, these imports will break. You are of course allowed to add new exports and modify existing ones, but please be careful to never leave out an export. {% endhint %} ### Overriding Constructors ScandiPWA uses magic `__construct` functions instead of constructors. This is done to enable overriding of these functions, which you can override like any other function. # Overriding non-classes Virtually always, you will want to keep part of the default functionality and only modify some aspect of the existing file. This is how the theme is usually extended. This is easy-to-achieve with class, where you can extend the original file providing some custom functionality. But what to do if an override of the constant or function is intended? Following are the rules, which will help you to stay "compatible" (thus ensuring easier upgrades): ## 1. Do not copy files Instead of copy-pasting a file, prefer manually exporting original functions and constants, and then re-exporting ones you changed! {% hint style="info" %} The ScandiPWA import mechanism provides the `Source` aliases to enable you to directly import from the parent theme, regardless of whether there is an overridden version available**.** Similarly, you can use the `SourceRoute` alias to import directly from a route defined in the parent theme, or the `SourceUtil` alias to import a utility file from the parent theme. {% endhint %} Let's now consider an example. Here, we would like to override a `MIN_PASSWORD_LENGTH` defined in the `component/Form/Form.config.js` file. Here is how we can do it (**without copying the file**): {% code title="override: component/Form/Form.config.js" %} ```javascript // exporting all functions and constants from original file export * from 'SourceComponent/Form/Form.config.js'; // specifically exporting default (as it is not included in "*") export { default } from 'SourceComponent/Form/Form.config.js'; // re-exporting the overriden variable export const MIN_PASSWORD_LENGTH = 6; ``` {% endcode %} ## 2. Call original functions if possible Instead of copying the original function from the source file, consider importing and calling it, then processing the original output value. Let's now consider an example. Here, we would like to override a `mapDispatchToProps` defined in the `component/AddToCart/AddToCart.container.js` file. Here is how we can do it (**without copying the original function**): {% hint style="warning" %} ### Heads up! When overriding a function that is used later in the component (for example in default export), you must also override the place the function is being used (therefore, as per example, default export). {% endhint %} {% code title="overriding: component/AddToCart/AddToCart.container.js" %} ```javascript // imporing original function to call import { AddToCartContainer, mapStateToProps, mapDispatchToProps as sourceMapDispatchToProps } from 'SourceComponent/AddToCart/AddToCart.container.js'; // importing to replicate original default export import { connect } from 'react-redux'; // exporting all functions and constants from original file export * from 'SourceComponent/AddToCart/AddToCart.container.js'; // re-exporting the overriden variable export const mapDispatchToProps = (dispatch) => { // calling the original function to modify the result const handler = sourceMapDispatchToProps(dispatch); // add custom functionality handler.logProduct = () => { console.log('product added to cart'); }; // returning modified result return handler; } // exporting default // (becuase function mapDispatchToProps was used in it) export default connect(mapStateToProps, mapDispatchToProps)(AddToCartContainer); ``` {% endcode %} # Overriding Styles You can adjust the styling of your theme in 3 different ways: * [**Overriding the Base Styles**](/developing-with-scandi/override-mechanism/extending-styles#overriding-the-base-styles): The ScandiPWA theme includes a set of stylesheets in `app/style` that define the main look of the application. These define global settings, such as SCSS variables (`style/abstract/_variables.scss`), media query definitions (`style/abstract/_media.scss`), base styling for some HTML elements (`style/base`), CMS content styling (`style/cms`), and more. If you want to make global styling changes to these files, you can override them. * [**Replacing a Component's Styles**](/developing-with-scandi/override-mechanism/extending-styles#replacing-a-components-styles): Every component (and route) includes an associated stylesheet, named `# Working with "granular cache" ScandiPWA controls cache in a different way than [default Magento 2](https://devdocs.magento.com/guides/v2.3/graphql/develop/create-graphqls-file.html#query-caching) does. We are still using the caching identities, but, instead of specifying them on GraphQL queries, we use events. ## General rule To make some of your model work as cache identity manager: 1. Make sure it implements the `Magento\Framework\DataObject\IdentityInterface` ```php use Magento\Framework\DataObject\IdentityInterface; use Magento\Framework\Model\AbstractModel; class Slide extends AbstractModel implements IdentityInterface { public function getIdentities() { // TODO: implement } } ``` 2\. Specify the caching tag constant, it should be short and unique: ```php class Slide extends AbstractModel implements IdentityInterface { const CACHE_TAG = 'sw_sld'; protected $_cacheTag = self::CACHE_TAG; } ``` 3\. Implement the `getIdentities` method, specify all involved cache identities. In our example, on slide save, the slider model should also be invalidate: ```php class Slide extends AbstractModel implements IdentityInterface { const CACHE_TAG = 'sw_sld'; public function getIdentities() { return [ self::CACHE_TAG . '_' . $this->getId(), Slider::CACHE_TAG . '_' . $this->getSliderId() ]; } } ``` 4\. Add the names for events, prefer unique, descriptive names: ```php class Slide extends AbstractModel implements IdentityInterface { protected $_eventPrefix = 'scandiweb_slider_slide'; } ``` 5\. In case you have a resource model, i.e. the `Collection`, add the event after collection save: ```php use Magento\Framework\Model\ResourceModel\Db\Collection\AbstractCollection; class Collection extends AbstractCollection { protected function _afterLoadData() { parent::_afterLoadData(); $collection = clone $this; if (count($collection)) { $this->_eventManager->dispatch( 'scandiweb_slider_slider_collection_load_after', ['collection' => $collection] ); } return $this; } } ``` 6\. It is finally time to connect the events, to granular cache management classes. Create, or modify the `etc/events.xml` with the following content: ```php
{ this.renderCurrentPrice() } { this.renderOldPrice() } { this.renderSchema() }
); } } export default ProductPrice; ``` {% hint style="success" %} Note that this component is broken down by defining one function for each part. This is better than writing one long `render` method for several reasons: * Code is easier to understand, and sometimes more concise thanks to reusable functions * The class is easy to maintain - re-ordering these parts only affects 2 lines * The component is easier to extend via overrides or plugins (important if your theme will be used as a parent theme) {% endhint %} {% hint style="warning" %} The `.component` file shouldn't be responsible for any business logic, such as fetching or manipulating data. For better separation of concerns, move all business logic to the `.container` file. (However, it is allowed maintain basic UI state e.g. to keep track of wether an accordion is open) {% endhint %} ### A Common `.component` Pattern: Render Maps Ocasionally, a component needs to render different things depending on its state. Additionally, this state might affect an aspect of the component that is common between some states. To understand, consider an example: The `Checkout` component has several steps to guide the user through checkout: shipping, billing, and the success step. Some of these have features in common - during both shipping and billing steps, the customer needs to see the cart items and totals, but we hide this at the success step. All 3 steps render a page title, but the title is different for each step. All 3 steps are associated with an URI, but it is different for each step. Of course, we could handle these changes with several `if` and `switch` statements, but ScandiPWA offers a better approach: treating the possible steps as data, stored in a field named `stepMap`: (Oversimplified and annotated code, taken from [Checkout.component.js](https://github.com/scandipwa/scandipwa/blob/master/packages/scandipwa/src/route/Checkout/Checkout.component.js)) ```jsx // [...] copyright, imports /** @namespace Route/Checkout/Component */ export class Checkout extends PureComponent { // (1) first, each step is configured with the desired functionality stepMap = { [SHIPPING_STEP]: { title: __('Shipping step'), render: this.renderShippingStep.bind(this), areTotalsVisible: true }, [BILLING_STEP]: { title: __('Billing step'), render: this.renderBillingStep.bind(this), areTotalsVisible: true }, [DETAILS_STEP]: { title: __('Thank you for your purchase!'), render: this.renderDetailsStep.bind(this), areTotalsVisible: false } }; // render ui specific to shipping, billing, and success details renderShippingStep() {...} renderBillingStep() {...} renderDetailsStep() {...} // (2) then, everything below this line uses the current step + stepMap // to determine what to do // React calls this after every render but the first // update the title and URL based on the current step data componentDidUpdate(prevProps) { const { checkoutStep } = this.props; const { checkoutStep: prevCheckoutStep } = prevProps; if (checkoutStep !== prevCheckoutStep) { this.updateHeader(); } } // updates the page title based on the current step updateHeader() { const { setHeaderState, // function to update the state of the header checkoutStep, // one of SHIPPING_STEP, BILLING_STEP, DETAILS_STEP } = this.props; const { title = '' } = this.stepMap[checkoutStep]; setHeaderState({ title }); } renderTitle() { const { checkoutStep } = this.props; const { title = '' } = this.stepMap[checkoutStep]; // same rendering logic for all steps return ({ title }
); } renderStep() { const { checkoutStep } = this.props; const { render } = this.stepMap[checkoutStep]; // call appropriate render function based on current step return render(); } // this only renders something if areTotalsVisible is // true for the current step renderSummary() {...} render() { return (
{ this.renderReviews() }
{ this.renderProductPrice() }
{ this.renderVisualConfigurableOptions() }
{ this.renderTierPrice() }
{ this.renderMainDetails() }
{ this.renderAdditionalProductDetails() }
)) }
{ children }
{ this.renderImage() }
);
}
```
{% endcode %}
{% endhint %}
# Routes
Routes are pages in your single-page application
ScandiPWA uses [`react-router`](https://reactrouter.com/web/guides/quick-start) and `react-router-dom` to handle routing. The Router itself is a ScandiPWA component, defined in `component/Router/Router.component.js`.
The components for the routes themselves are defined in the `route` directory. The structure of each route is the same as any other [component](/structure/building-blocks-summary/components), but instead of being used throughout the application, they are used only in the router.
## Special Cases
ScandiPWA allows you to create custom URL rewrites that don't match the standard routes. This is implemented in `route/UrlRewrites`.
If neither the standard routes nor the URL rewrites resolve to anything, the user is shown an error message stating that no page has been found. This is implemented in `route/NoMatchHandler`.
## Example - Standard Route
The `CartPage` is defined in `route/CartPage`. It is added to the router:
```javascript
// component/Router/Router.component.js
// imported lazily for better performance
export const CartPage = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "cart" */ 'Route/CartPage'));
// [...]
/** @namespace Component/Router/Component */
export class Router extends PureComponent {
// all standard routes are defined here, including the cart page
[SWITCH_ITEMS_TYPE] = [
{
component: addField(
field: Field | string
) -> this
addFieldList(
fields:(Field | string)\[]
) -> this
addArgument(
name: string,
type: string,
value: string
) -> this
setAlias(
alias: string
) -> this
fetchQuery(
query: Field | Field\[]
) -> Promise\
fetchMutation(
query: Field | Field\[]
) -> Promise\
` element. If you want to rewrite the component to use a `
` instead, you would have to update the styles.
* Unnecessary [specificity](https://developer.mozilla.org/en-US/docs/Web/CSS/Specificity): Having an additional selector element will increase the specificity and make the styles harder to [override in `.override.style.scss` files](/developing-with-scandi/override-mechanism/extending-styles#partially-overriding-a-components-styles).
{% endhint %}
{% hint style="success" %}
Instead, it is recommended to assign a new BEM class to the element you want to style. Then, you can select it properly:
```css
.CheckoutOrderSummary {
&-CartItemDescription {
margin-top: 5px;
}
&-CartItemDescriptionContent {
font-size: 1.1rem;
line-height: 1.5;
}
}
```
{% endhint %}
## Minimize Nesting
In some cases, you might need to style one Block differently depending on whether it is a child of another block.
{% hint style="danger" %}
Avoid nesting selectors - don't select a block nested inside another block:
```css
.Button {
margin: 5px;
}
// this is discouraged
.ContactForm .Button {
margin: 10px;
}
```
This is discouraged for several reasons:
* `Button` styles now contain selectors from another component. This causes coupling, which will result in issues if the `.ContactForm` block is renamed
* The selector has higher specificity, making it harder to override.
{% endhint %}
{% hint style="success" %}
Instead, consider using a variable to customize your styling:
{% code title="Button.style.scss" %}
```css
:root {
--button-margin: 5px;
}
.Button {
// by default, a value of 5px will be inherited from :root
margin: var(--button-margin);
}
```
{% endcode %}
{% code title="ContactForm.style.scss" %}
```css
.ContactForm {
// we can set the variable lower in the hierarchy to override it
--button-margin: 10px;
}
```
{% endcode %}
Now, each component is responsible for its own styles only, and the specificity is still low.
{% endhint %}
{% hint style="info" %}
In this case, another possible solution would be to use a Modifier:
```css
.Button {
margin: 5px;
&_margin_large {
margin: 10px;
}
}
```
Now, the button could take a prop to specify the margin size and add it as a modifier to the Button Block. Then, the ContactForm would have to pass a value to this prop indicating that the button should have a larger margin.
{% endhint %}
## Prefer Mobile-First Styling
Mobile-first styling means that you are encouraged to start with mobile styles. When mobile styles are complete, you can use the `@include desktop` directive and other [breakpoints](/structure/building-blocks-summary/global-styles#breakpoints) to adjust the styling for larger viewports.
## Avoid Magic Numbers
You should avoid hard-coding numbers when their reasoning is not obvious. Make values re-usable and understandable by using CSS variables.
{% hint style="danger" %}
Avoid hard-coded values:
```css
.NotificationList {
position: fixed;
top: 110px;
}
```
Issues:
* Unclear where the value 110 is coming from
* The layout can break if some values are changed
{% endhint %}
{% hint style="success" %}
Instead, use variables, and combine them with `calc` if necessary:
```css
.NotificationList {
position: fixed;
top: calc(var(--header-height) + var(--breadcrumbs-height) + 20px);
}
```
Advantages:
* Intentions are more clear
* Variable values can be safely changed to adjust the layout
* Each value is re-usable.
{% endhint %}
## Use Round Numbers
Unless you need to produce a pixel-perfect design, we recommend using values rounded to the nearest 5px, avoid unnecessary decimal digits, and consider how much precision browsers can actually display.
# Customizing Your Theme
A walk-through of how you can create your own Scandi-based theme
In this tutorial, we will customize a Scandi theme in various ways, showing you specific examples of how common changes can be made. You can easily follow along with your own Scandi theme.
## Before You Start
You will need a Scandi app to customize, which you can easily get in a few minutes using `create-scandipwa-app` (CSA). Get started [here](https://docs.create-scandipwa-app.com/getting-started/getting-started)!
You can keep the `npm start` process running throughout this tutorial, so the changes you make will be automatically reflected in the browser.
There is no need for a Magento app, because CSA is clever and can forward all requests to a remote Magento instance.
# Styling
Give your theme a fresh coat of paint!
# Customizing the Global Styles
Define the overall look of your application
In Scandi, the `style` directory defines the overall look of your application - the theme colors, fonts, and some HTML element styling, along with CMS content styles. Often, when customizing a theme, these styles are the first thing to be changed.
Let's change the theme colors of the application. To override a style file, you will need to copy it from the base theme (which you can find in `node_modules/@scandipwa/scandipwa`) to your `src` directory, under the same path. In this case, the file we want to override is `node_modules/@scandipwa/scandipwa/src/style/abstract/_variables.scss`, because this is where the theme color variables are defined. Copy this file to `src/style/abstract/_variables.scss`. Now we are ready to customize the color variable declarations:
{% code title="src/style/abstract/\_variables.scss" %}
```css
$white: #FFF;
$black: #0D2E41;
$default-primary-base-color: #44AD9F;
$default-primary-dark-color: #00798A;
$default-primary-light-color: #87DEC7;
$default-secondary-base-color: #F8AF2C;
$default-secondary-dark-color: #FA6135;
$default-secondary-light-color: #FFE357;
```
{% endcode %}
However, you will notice that changes are not yet applied. This is because we also need to override the files in the import chain of the file. Inspecting the codebase, we see that `_variables.scss` is imported in `_abstract.scss`, which is in turn imported in `src/style/main.scss`. Therefore, we also need to copy over `_abstract.scss` and `main.scss` from the base theme.
Now, the global style changes should be applied. Indeed, if we check our app, we can see the new colors:
**Exercise: So far, we only changed the theme colors. Take a look around the `style` directory and see if there is anything else you'd like to change. Perhaps change the loader background style, or the spacing in lists?**
# Adding a New Font
Learn to add and use new assets in Scandi
You can add fonts in the `src` directory. When you reference them with `url` in your style sheets, they will be resolved and bundled with your application. Let's go through an example.
{% hint style="info" %}
You can find fonts in [Font squirrel](https://www.fontsquirrel.com/), [dafont.com](https://www.dafont.com/), [Everything Fonts](https://everythingfonts.com/) or [Google Fonts](https://fonts.google.com/).
In our case, it is best to [convert your fonts](https://www.fontsquirrel.com/tools/webfont-generator) into the woff format, which is optimized for the web. See [this article for more details](https://developer.mozilla.org/en-US/docs/Learn/CSS/Styling_text/Web_fonts).
{% endhint %}
Suppose you have decided to use the [Staatliches and Source Sans Pro fonts](https://fonts.google.com/share?selection.family=Source%20Sans%20Pro:wght@600%7CStaatliches). Convert them into the Woff and Woff2 formats. Then, put them in the `src/style/fonts` directory. Any directory under `src` would work, but it makes sense to store them in their own directory along with styles. Verify that your fonts are where you expect:
{% code title="$ ls src/style/fonts/" %}
```
sourcesanspro-regular-webfont.woff sourcesanspro-regular-webfont.woff2
staatliches-regular-webfont.woff staatliches-regular-webfont.woff2
```
{% endcode %}
However, they are still not imported in our styles. To actually include them into the page, create a new file, named`src/style/base/_font.scss`, for example. First, we will need to declare the font faces:
{% code title="src/style/base/\_font.scss" %}
```css
@font-face {
font-family: 'Staatliches';
src: url(/style/fonts/staatliches-regular-webfont.woff2) format('woff2'),
url(/style/fonts/staatliches-regular-webfont.woff) format('woff');
font-weight: normal;
font-style: normal;
}
@font-face {
font-family: 'SourceSansPro';
src: url(/style/fonts/sourcesanspro-regular-webfont.woff2) format('woff2'),
url(/style/fonts/sourcesanspro-regular-webfont.woff) format('woff');
font-weight: normal;
font-style: normal;
}
```
{% endcode %}
For convenience, let's also define SCSS variables to refer to these fonts:
{% code title="src/style/base/\_font.scss" %}
```css
$font-staatliches: 'Staatliches', sans-serif;
$font-source-sans-pro: 'SourceSansPro', sans-serif;
```
{% endcode %}
Now, we have told the browser that these fonts exist and where to find them. However, they aren't actually being used anywhere. Let's use the Staatliches font for headings, and the Source Sans font for everything else:
{% code title="src/style/base/\_font.scss" %}
```css
body {
font-family: $font-source-sans-pro;
}
h1, h2, h3, h4, h5, h6 {
font-family: $font-staatliches;
}
```
{% endcode %}
One final change is needed - to actually include the `_font.scss` file as part of the styles. We can do so by importing it in `src/style/main.scss` (override the file if you don't already have it in your code). In the last lines of `main.scss`, add:
{% code title="src/style/main.scss" %}
```css
@import './base/font';
```
{% endcode %}
{% hint style="warning" %}
Note: it is important that this import occurs after the import of `base/_reset.scss`, since, in the base theme, this is where the body font is set.
{% endhint %}
We can now refresh the page to see that the fonts have been updated:
**Exercise: Try adding a new font and assigning it to some text! Be careful though - the more fonts you add, the less consistent the user interface looks. Besides, each additional font needs to be loaded into the browser.**
# Overriding a Components Styles
Give a fresh new look to any component β replace the default styles with your own.
In the first few chapters, we looked at how global styles can be overridden in Scandi. However, for better code organization, individual components have their own styles, too. In this chapter, you will learn to override a component's styles.
Suppose you want to completely re-style an existing component in Scandi. All you need to do is override its `.style.scss` file by creating a new file of the same path, in your theme directory. For example:
```
to override:
node_modules/@scandipwa/scandipwa/
src/component/ProductAttributes/ProductAttributes.style.scss
create:
src/component/ProductAttributes/ProductAttributes.style.scss
```
You can also use the `scandipwa` CLI utility to override styles more easily. Just be sure to select `Override` when asked what to do with styles, and leave the other options un-selected.
```
scandipwa override component ProductAttributes
? Choose things to extend in ProductAttributes.component.js
? What would you like to do with styles? Override
? Choose things to extend in ProductAttributes.container.js
NOTE!
The following files have been created:
src/component/ProductAttributes/ProductAttributes.style.scss
```
Now, it's time to write some custom styling for the component:
{% code title="src/component/ProductAttributes/ProductAttributes.style.scss" %}
```css
:root {
--product-information-background: var(--secondary-base-color);
}
.ProductAttributes {
&-Wrapper {
padding: 0;
@include desktop {
padding: 2rem;
}
}
&-ExpandableContentButton {
@include after-mobile {
display: none;
}
}
&-ExpandableContentContent {
&_isContentExpanded {
@include mobile {
padding: 0 1.4rem;
}
}
}
&-Description,
&-Attributes {
width: 100%;
}
&-Attributes {
display: grid;
grid-template-columns: 1fr 1fr;
grid-gap: 1em;
}
&-ValueLabel,
&-AttributeLabel {
text-overflow: ellipsis;
font-family: var(--font-staatliches);
font-size: 20px;
line-height: 1;
}
&-ValueLabel {
font-weight: 700;
@include mobile {
padding-left: .7rem;
margin-bottom: 1.4rem;
}
}
&-AttributeLabel {
text-align: right;
color: var(--secondary-dark-color)
}
}
```
{% endcode %}
# Extending a Component's Styles
Tailor the details to your needs β make small adjustments while keeping the original styles
In the last chapter, we learned about overriding a component's styles. We did this by replacing the original styles with our own. However, in some cases, you may want to keep the original styles, and only make a few modifications. To avoid duplicating all of the original code, you can extend the styles by creating a file that will be used *in addition* to the base stylesheet.
For example, suppose you want to add a shadow to the menu overlay. To do this, we will only need to add a few lines of SCSS code β which means we want to keep most of the existing styling. This is easy to do β we simply need to extend the styles for the `Menu` component.
First, create a new stylesheet file:
{% code title="src/component/Menu/Menu.override.style.scss" %}
```css
.Menu {
&-SubCategoriesWrapper {
opacity: 0.95;
box-shadow: rgba(0, 24, 49, 0.8) 0 30px 80px;
}
&-Overlay {
display: none;
}
}
```
{% endcode %}
Now, to include this file in the application (in addition to the existing styles), override the `.component` and import the `.override.style`:
{% code title="src/component/Menu/Menu.component.js" %}
```jsx
import {
Menu as SourceMenu
} from 'SourceComponent/Menu/Menu.component';
import './Menu.override.style';
export default SourceMenu;
```
{% endcode %}
Note that the `.component` override doesn't make any changes β it simply re-exports the original component and imports an additional stylesheet.
{% hint style="info" %}
Note: you can use the `scandipwa` CLI utility to quickly override components. In this case, we can easily create the files we need with the following command:
```
scandipwa override component Menu
? Choose things to extend in Menu.component.js Menu
? What would you like to do with styles? Extend
? Choose things to extend in Menu.config.js
? Choose things to extend in Menu.container.js
NOTE!
The following files have been created:
src/component/Menu/Menu.override.style.scss
src/component/Menu/Menu.component.js
```
{% endhint %}
Now, we have added a shadow and a transparency effect to the menu overlay:
# Customizing JavaScript
Change the JavaScript logic in your theme!
Everyone's needs are different β and the Scandi theme can be customized to meet a wide range of requirements. Some changes are very commonly needed, and this section provides a set of recipes of how to make them. Feel free to consult these guides while developing your Scandi theme!
# Customizing the Footer Copyright
Learn to override the copyright text at the bottom of the page
In this tutorial, we will override the component responsible for rendering the copyright text, and change that text to a different value. This will give you an insight into how the override mechanism works with React components. After completing this tutorial, you will be able to override other components as well.
## Inspecting the Code
Before we can modify its code, we need to know which component is responsible for rendering the Footer. We can use the [React developer tools](/developing-with-scandi/developer-tools#browser) to find out. Open the `Components` tab, and identify the element you want to override. In this case, it appears to be a child of the `Footer` component.
Now that we have found out the name of the component, there is only one place we need to look β the `component` directory in `node_modules/@scandipwa/scandipwa/src/`. Indeed, we can find a component named Footer there:
{% code title="Original File in scandipwa/src/component/Footer/Footer.component.js" %}
```javascript
// [...]
export class Footer extends PureComponent {
// [...]
renderCopyrightContent() {
const { copyright } = this.props;
return (
{ copyright }
{ ' Powered by ' }
ScandiPWA
);
}
render() {
return (
);
}
}
export default Footer;
```
{% endcode %}
{% hint style="info" %}
That funny [HTML-in-JavaScript syntax is called JSX](https://reactjs.org/docs/introducing-jsx.html). Scandi uses the React library to render its user interface, and JSX is the easiest way to use React.
{% endhint %}
Now that we have found the component, we can update its code. But **don't** edit the file we found in `node_modules` β modifying dependency code is almost always a bad idea. (It would be hard to get updates, and difficult to track which of the many files you have edited). Instead, let's override it.
## Overriding the Footer
Scandi offers a great way to customize any component, and its called the Override Mechanism. With the override mechanism, you can override any file you want, while keeping the default implementations for the other files. This gives you great flexibility without having to duplicate any code.
To override a file, you need to create a new file with the same path in your `src` directory. For example...
```
To override:
component/Footer/Footer.component.js
(in node_modules/@scandipwa/scandipwa/src/)
...you need to create a new file:
component/Footer/Footer.component.js
(in src/)
```
{% hint style="info" %}
Instead of manually creating a new file, you can save yourself a lot of time by using the [Scandi CLI](/developing-with-scandi/developer-tools/scandipwa-cli). With a single command, you can override the Footer component:
```bash
scandipwa override component Footer
```
When you run that command, the Scandi tool will ask you which components you want to override. Select the `Footer` class in `Footer.component.js`; leave the other fields blank:
{% endhint %}
Now we have created the file, which overrides the original Footer component file. Now, we want to import the original class, so that we can keep most of the Footer functionality, and extend it to customize its behavior:
{% code title="File override in src/component/Footer/Footer.component.js" %}
```javascript
// We will need the ContentWrapper component later - let's import it
import ContentWrapper from 'Component/ContentWrapper';
// Import the original class (we want to keep most of the functionality)
// Note that we are using the "SourceComponent" alias in the import path β
// This tells Scandi that we want to get the original Footer component
import {
Footer as SourceFooter
} from 'SourceComponent/Footer/Footer.component';
// Extend the original class (SourceFooter)
// By subclassing it, we can change some of its behavior
/** @namespace myFirstApp/Component/Footer/Component/FooterComponent */
export class FooterComponent extends SourceFooter {
// This is the function responsible for rendering copyright
// We want to change it, so we re-define in this subclass
renderCopyrightContent() {
// Changed:
// Instead of the copyright text, let's write a friendly message
return (
Thank you for visiting my website. You are amazing!
);
}
// All the other functions will stay the same...
// Because we didn't override any other default functionality
}
// All components, including the original Footer component, have a
// default export. Other files use this export when they want to use
// this component.
// Now, instead of providing the original component, we export our
// overridden component. Any file importing this will get the new behavior!
export default FooterComponent;
```
{% endcode %}
## Results
Scandi implements hot reload β which means that you don't need to compile the app again. Just check your browser and the changes should have appeared.
Congratulations! Now you understand the basics of file overriding β and you can override any file in the app to change its behavior.
# Adding a New Page
Learn to create new pages (routes) in your Scandi app!
Suppose we wanted to create an "about us" page. Usually, we would do this by using the CMS system. However, for the sake of a simple example, suppose we want to hard-code this page in the codebase.
## Creating a New Route
First, we need a React component responsible for rendering the page. These are called routes, and in Scandi, they can be found within the `route` directory.
While you could create the necessary boilerplate yourself, the `scandipwa` [CLI](/developing-with-scandi/developer-tools/scandipwa-cli) utility can automate this for you. The `create route` command will create a new route. You can name yours anything you want, but we called it `AboutUs`:
```
scandipwa create route AboutUs
```
This should create a new subfolder under `route` and create all the necessary files inside. The command output will also tell us what happened:
```
NOTE!
The following files have been created:
src/route/AboutUs/AboutUs.component.js
src/route/AboutUs/AboutUs.style.scss
src/route/AboutUs/index.js
```
Let's create some basic placeholder content in the `.component.js` file:
```jsx
render() {
return (
);
}
```
Now, we have created our route. But it doesn't appear anywhere in our app yet... It's just another component lying around, unused, in our codebase. Let's do something about it!
## Registering the Route
In Scandi, the `Router` component is responsible for registering all routes. It uses `react-router` to specify which Routes should be visible in different URLs. Let's take a look at the original `Router` component. It contains a special field where it configures all of the routes available in the app:
```jsx
[SWITCH_ITEMS_TYPE] = [
{
component:
- ScandiPWA\\Router\\Validator\\AlwaysPass
- ScandiPWA\\Router\\Validator\\Wishlist
- ScandiPWA\\Router\\Validator\\AlwaysPass
```
The `validators` argument of the `ValidationManager` is an array mapping paths to corresponding validators. The validators' job is to determine if a path is valid (200 status code) or invalid (404 not found).
You can write your own custom validator if you need to β which you would have to do if you need to access the database to determine if the path is valid (for example, for products, you need to check if the product exists). However, in our case, all we need to do is add a simple `AlwaysPass` validator β because our `about-us-page` should always return a success status code, 200. First, create a new Magento module for this configuration. Then, it its `di.xml` file, add the following configuration:
```markup
- ScandiPWA\\Router\\Validator\\AlwaysPass
```
Make sure the new module is registered by running `magento setup:upgrade`. Now, when you refresh the page, you should see that your custom page returns a successful status code.
## What's Next?
Congrats! You have now added a brand-new page to your Scandi app. As an exercise, you could try to add some more pages, perhaps with more complicated paths with variables (hint: see the `react-router` [docs](https://reactrouter.com/web/guides/quick-start)!). Or perhaps you want to add a few links that will lead to your new page? Use the [Link](https://reactrouter.com/web/api/Link) component for this purpose. You can also play around with your new page, adding more styling and content if you want.
# Adding a Section in My Account
Learn to override with a common pattern in Scandi β render maps
In Scandi, several UI elements, including the My Account page, are organized in tabs:
In this tutorial, we will learn to customize the theme by adding a new tab to the My Account page. If you follow along with this tutorial, you should be able to add any component to any tab in Scandi.
## Creating a New Component
First, we need to create a component responsible for displaying the content of the tab. This means creating a new subdirectory in the `component` directory with the required files. Using the `scandipwa` CLI utility, this step can be automated with a single command.
We will name our example component `PositiveAffirmations`:
```bash
scandipwa create component PositiveAffirmations
```
This should create some new files and give the following output:
```
NOTE!
The following files have been created:
src/component/PositiveAffirmations/PositiveAffirmations.component.js
src/component/PositiveAffirmations/PositiveAffirmations.style.scss
src/component/PositiveAffirmations/index.js
```
Now, let's edit the `.component.js` file to render some example content. For simplicity, our example will contain positive self-affirmations copy-pasted from the internet:
{% code title="src/component/PositiveAffirmations/PositiveAffirmations.component.js" %}
```jsx
render() {
return (
);
}
```
{% endcode %}
This will help customers gain confidence and boost their mood while they adjusting the settings for their account.
{% hint style="info" %}
Wondering what the `{ __("") }` magic is for? They are necessary to enable translating the text. You could remove them, and the app would still work, but only in English. Let's break down what that syntax does:
1. The curly braces `{}` allow us to escape from JSX (that HTML-like syntax) and write normal JavaScript expressions.
2. `__` is a special function-like directive in Scandi. It allows us to translate the content.
3. The text needs to be put in quotes `""` so that it can be processed like any other JavaScript string.
{% endhint %}
Great! Now we have created the component, but it's not yet visible on the page, because we haven't used it anywhere β that's the next step.
## Inspecting the Codebase
To add a new tab, we need to find out which component is responsible for rendering all of the My Account tabs. Using [React Developer tools](/developing-with-scandi/developer-tools#browser), we can identify the `MyAccountTabList` component:
Inspecting the source code and searching for usages of `
);
}
}
```
{% endcode %}
## Result
If you check the product page in your app, you'll see that the tabs are now updated, and include our new tab:
# Creating a New Redux Store
Learn to add your Redux store to the Scandi app
In this guide, you will learn to add a new Redux store to your app. To learn more about [Redux stores in Scandi](/structure/building-blocks-summary/redux-stores), read the docs.
## Creating a New Store
First, we need to create a new Redux store. Using the [`scandipwa`](/developing-with-scandi/developer-tools/scandipwa-cli) CLI utility, you can easily create a new store with a single command. In our toy example, we will call our store `ImportantNumber`:
```bash
scandipwa create store ImportantNumber
```
You should see that new files have been created, as indicated by a success message:
```
NOTE!
The following files have been created:
src/store/ImportantNumber/ImportantNumber.action.js
src/store/ImportantNumber/ImportantNumber.reducer.js
```
Feel free to implement any logic you need in the Redux store.
## Redux in Scandi
At this point, you will notice that while we have defined the store in the codebase, it is not registered in the app yet. This is because it hasn't been registered yet.
In Scandi, stores are registered in the `store/index.js` file:
{% code title="node\_modules/@scandipwa/scandipwa/src/store/index.js" %}
```javascript
import BreadcrumbsReducer from 'Store/Breadcrumbs/Breadcrumbs.reducer';
import CartReducer from 'Store/Cart/Cart.reducer';
import CategoryReducer from 'Store/Category/Category.reducer';
// [...]
/** @namespace Store/Index/getReducers */
export const getStaticReducers = () => ({
BreadcrumbsReducer,
CartReducer,
CategoryReducer,
// [...]
});
export default function injectStaticReducers(store) {
Object.entries(getStaticReducers()).forEach(
([name, reducer]) => store.injectReducer(name, reducer)
);
return store;
}
```
{% endcode %}
As you can see, most reducers are registered in the `getStaticReducers` function. To add a new reducer, we must override this function, and add our own reducer. We must also override `injectStaticReducers` to use our new function.
{% hint style="info" %}
Confused by the object notation syntax? In JavaScript, spelling out the key name is optional if it's the same as the value variable. So writing...
```javascript
{
BreadcrumbsReducer,
CartReducer,
CategoryReducer
}
```
...is the same as writing:
```javascript
{
'BreadcrumbsReducer': BreadcrumbsReducer,
'CartReducer': CartReducer,
'CategoryReducer': CategoryReducer
}
```
It's just like any other JavaScript object `{}`.
{% endhint %}
## Registering the Store
So how can we override the `index.js` file? Unfortunately, at the moment, the CLI cannot automate this for us, so you need to create a new file for overriding manually:
{% code title="src/store/index.js" %}
```javascript
// import the original getStaticReducers function
// and rename it to baseGetStaticReducers
import { getStaticReducers as baseGetStaticReducers } from 'SourceStore/index';
// import our own reducer
import ImportantNumberReducer from 'Store/ImportantNumber/ImportantNumber.reducer';
// define getStaticReducers.
// this is a function that returns an object of all the reducers in the app.
// just like in the base theme...
/** @namespace TutorialCsaApp/Store/Index/getStaticReducers */
export const getStaticReducers = () => ({
...baseGetStaticReducers(),
// ...except we also add our own reducer to the mix
ImportantNumberReducer
});
// nothing new here, just copying the function from the base theme
// (this is necessary so that it uses our own `getStaticReducers` function
export default function injectStaticReducers(store) {
Object.entries(getStaticReducers()).forEach(
([name, reducer]) => store.injectReducer(name, reducer)
);
return store;
}
```
{% endcode %}
Aaand that's it! If you check the Redux developer tools, you will see that your reducer is now included in the state.
# Payment Method Integration
Integrate an existing payment method so you can use it in a Scandi store!
A crucial part in any Magento website β payment methods! In the Magento Marketplace you can find a large number of payment method providers β but adapting them to work with Scandi can require additional effort (unless the integration already exists on the Scandi Marketplace).
In this tutorial, you'll learn the basics of building an extension for integrating a new payment method in Scandi.
For our example, we'll use Mollie. Like many other providers, Mollie redirects the user to another page after checkout to complete the payment. After the customer has entered their details on the 3rd party site, they are redirected back to the website, where they see a message about the current payment status. We'll need to adapt this logic so it also works in a Scandi theme.
# Setting Up for Development
Before you can start working on the Scandi integration, you need to set up a local environment
## Creating a New App
First, make sure you have a working Magento app with Scandi installed. The easiest way to get this setup is by using `create-magento-app` with `create-scandipwa-app`!
Next, since we want to create a reusable extension that can be installed on multiple projects, we can initialize it with a single command. After checking that you have the `scandipwa` CLI utility installed, navigate to your theme's root directory and enter this command:
(don't forget to replace `your-payment-provider` with the actual payment provider name!)
```
scandipwa extension create your-payment-provider-scandi
```
This will automatically create a new extension, including some boilerplate configuration to get you started. It will also install the extension into your app.
## Setting up the Payment Extension
In most cases, you'll also want to install the Magento payment integration extension. While it might not provide out-of-the-box support for working with Scandi, it will already include most of the payment logic that you need for the integration.
Next, you'll need to configure the extension. The configuration will vary across providers, but you'll most likely have to log in to your account on the payment provider's website to copy some credentials into your Magento configuration β check the extension's documentation for more details!
In our example, Mollie needs us to enter a few authentication secrets to connect the extension to the Mollie account. We also need to enable the different payment methods supported by Mollie.
Be sure to also enable test mode in the extension. This will allow you to ensure your extension is working correctly without needing to make real payments.
It might be a good idea to get an idea of how the Magento extension works before starting work on your Scandi integration. You could simply switch the theme to Luma and complete a
## *Sigh...* Webhooks
Many payment workflows involve webhooks. Webhooks allow a third-party server (in this case the payment provider) to notify your Magento app when something of interest has happened β for example, when a payment has been completed or canceled.
Crucially, since the payment providers' servers need to be able to notify your app, the URL needs to be accessible to them. This means that you can't simply keep your app on `localhost`, because then your computer is the only one that can access the website. And of course, the payment provider isn't running on your computer, so they can't access your app.
Fortunately, there is a workaround! You can tunnel traffic from a publicly accessible address to your locally-running app. `ngrok` is a tool that allows you to do it for free.
### Using ngrok
First, [create a ngrok account](https://ngrok.com/), and install the ngrok tool. Configure ngrok as specified in the instructions on their website. Then, you should be able to create a tunnel from a public `.ngrok.io` URL to your localhost. The easiest way is to create a HTTP tunnel:
```
./ngrok http 80 --region eu
```
Note: the `--region` parameter is optional, but your requests might be faster if you specify a region that is close to where you are.
Now, your local app will be available to anyone that knows the `ngrok` URL β which will be displayed after running the above command. And "anyone" includes the payment service provider, so webhooks will work!
Don't forget to update the Magento `base_url` to the new ngrok URL. Otherwise, you'll keep getting redirected to your [localhost](http://localhost) address.
# Redirecting to the Payment Provider
Redirect to a 3rd party site after the order is placed
Very often, after the shipping details are entered and the payment method is chosen on your website, the user needs to be redirected to a third-party site to complete the payment. You can easily do this in Scandi by writing a few plugins.
Note: In this example, we're implementing a specific payment method provider, Mollie. If you are making an extension for a different payment service, the steps outlined below might be slightly different. However, the general workflow of integrating a payment method will be similar: inspect the checkout source code and customize it through plugins.
## Getting the Redirection URL
First, we need to get the URL that the user should be redirected to. For many payment extensions, this URL is included in the `placeOrder` GraphQL mutation response. Indeed, our example extension, Mollie, includes a `mollie_redirect_url` in the `order` field of the response.
However, as you may know, in GraphQL, only the fields that have been requested are found in the response. And of course, since `mollie_redirect_url` is an extension-specific field, it is not requested by default. Therefore, we need to write a plugin that will request this additional field as part of the `placeOrder` mutation.
After inspecting the Scandi source code, you'll find that the file responsible for creating the `placeOrder` mutation is `scandipwa/src/query/Checkout.query.js`.
All Scandi query creators live in the `query` folder. If you need to find the file responsible for a specific query, you can search for this query's name there.
First, let's take a look at the relevant parts of the original`Checkout.query` file, to get an idea of what we're plugging in to:
{% code title="scandipwa/src/query/Checkout.query.js" %}
```jsx
import { isSignedIn } from 'Util/Auth';
import { Field } from 'Util/Query';
/** @namespace Query/Checkout */
export class CheckoutQuery {
// ...
getPlaceOrderMutation(guestCartId) {
const mutation = new Field('s_placeOrder')
.setAlias('placeOrder')
.addField(this._getOrderField());
if (!isSignedIn()) {
mutation.addArgument('guestCartId', 'String', guestCartId);
}
return mutation;
}
// ...
_getOrderField() {
return new Field('order')
.addFieldList(['order_id']);
}
// ...
}
export default new CheckoutQuery();
```
{% endcode %}
As you see, the `_getOrderField` function is responsible for creating the `order` field, and populating it with the `order_id` subfield. We want to plug into this function to add an additional subfield β `mollie_redirect_url`.
So let's create a new plugin file! In the `plugin` directory of your extension, create a new Javascript file that ends in `.plugin.js`. It's a good idea to name it after the query it plugs into, so we'll name ours `Checkout.query.plugin.js`.
In Scandi, plugins are functions that wrap around the original function (read the documentation for more details of how they work). In this case, it's really simple:
{% code title="plugin/Checkout.query.plugin.js" %}
```jsx
const _getOrderField = (args, callback, instance) => {
// `callback` is the original function.
// By calling it, we get the original `order` field,
// which only contains 1 subfield, `order_id`, as seen above
return callback()
.addFieldList([
'mollie_redirect_url', // we add the redirect URL field
'mollie_payment_token' // and also this one (we'll need it later)
])
}
// This bit is the plugin configuration object.
export default {
// First, specify the namespace to plug in to.
"Query/Checkout": {
// There are different types of plugins, but since we're
// plugging into a member function (as opposed to static functions)
// we specify the "member-function" type
"member-function": {
// There's only 1 plugin we want to specify here
_getOrderField: _getOrderField
// (But we could plug into other functions too if we wanted!)
}
}
}
```
{% endcode %}
If all goes smoothly, you should see a `mollie_redirect_url` value returned in the GraphQL response when completing an order with a Mollie payment method.
You can check the "Network" tab in your browser's developer tools to see the GraphQL responses. This can be useful for debugging requests!
Now, we have the redirect URL in the response, but we're not doing anything with it yet. The next step is to implement the actual redirection functionality.
## Redirecting the User
First we need to find out which code is responsible for taking the user through the checkout steps. As the React Developer Tools extension will tell you, it's the `Checkout` route. We also know that the business logic (which is what we're interested in right now) most likely lives in the `.container`. So let's look at `scandipwa/src/route/Checkout/Checkout.container.js` , and the `savePaymentMethodAndPlaceOrder` function in particular:
{% code title="scandipwa/src/route/Checkout/Checkout.container.js" %}
```javascript
// [imports...]
// [mapStateToProps and mapDispatchToProps]
/** @namespace Route/Checkout/Container */
export class CheckoutContainer extends PureComponent {
// [...]
async savePaymentMethodAndPlaceOrder(paymentInformation) {
const { paymentMethod: { code, additional_data } } = paymentInformation;
const guest_cart_id = !isSignedIn() ? getGuestQuoteId() : '';
try {
await fetchMutation(CheckoutQuery.getSetPaymentMethodOnCartMutation({
guest_cart_id,
payment_method: {
code,
[code]: additional_data
}
}));
const orderData = await fetchMutation(CheckoutQuery.getPlaceOrderMutation(guest_cart_id));
const { placeOrder: { order: { order_id } } } = orderData;
this.setDetailsStep(order_id);
} catch (e) {
this._handleError(e);
}
}
render() {...}
}
export default connect(mapStateToProps, mapDispatchToProps)(CheckoutContainer);
```
{% endcode %}
The function sets the payment method for the order, and places the order. After the order is placed, it simply transitions to the order success step (also known as the "details step").
We want to change this functionality β instead of transitioning to the details step, we need to redirect the user to the final payment step, on the 3rd party website. We already made sure that `CheckoutQuery.getPlaceOrderMutation` will return the redirection URL in the response, so we just need to use that.
Let's write a plugin for `savePaymentMethodAndPlaceOrder` that will redirect the user if necessary. We can add it to our existing `Checkout.container.plugin.js` file:
{% code title="plugin/Checkout.container.plugin.js" %}
```jsx
import { redirectToUrl } from '../util/Redirect';
import { getPaymentToken, setPaymentToken } from '../util/PaymentTokenPersistence';
const savePaymentMethodAndPlaceOrder = async (args, callback, instance) => {
const [paymentInformation] = args;
const { paymentMethod: { code, additional_data } } = paymentInformation;
const guest_cart_id = !isSignedIn() ? getGuestQuoteId() : '';
// It's important to check if the user has selected a Mollie payment method.
// We don't want to affect other methods, so we just use the callback directly in that case.
if (!MOLLIE_METHODS.includes(code)) {
return await callback(...args);
}
// Since this is a Mollie method, now we need some custom logic
try {
// Just like the original function, we set the payment method
await fetchMutation(CheckoutQuery.getSetPaymentMethodOnCartMutation({
guest_cart_id,
payment_method: {
code,
[code]: additional_data,
},
}));
// However, when placing the order, there is some additional data we need to consider
const orderData = await fetchMutation(CheckoutQuery.getPlaceOrderMutation(guest_cart_id));
const { placeOrder: { order: { mollie_redirect_url, mollie_payment_token } } } = orderData;
if (Boolean(mollie_payment_token)) {
// We'll need this token later, so let's save it to the browser's storage
setPaymentToken(mollie_payment_token);
} else {
// It is a good idea to "fail early" if some data you expect to be present
// is not there. Also, provide good error messages.
// That way, your code will be easier to debug if something goes wrong.
throw Error("Expected mollie_payment_token in order data, none found", orderData)
}
// We take the redirect URL we requested in the previous step and redirect to it
if (Boolean(mollie_redirect_url)) {
redirectToUrl(mollie_redirect_url)
} else {
throw Error("Expected mollie_redirect_url in order data, none found", orderData)
}
} catch (e) {
instance._handleError(e);
}
};
// Afain, we need to export the plugin configuration:
export default {
"Route/Checkout/Container": {
"member-function": {
savePaymentMethodAndPlaceOrder,
},
},
}
```
{% endcode %}
As you might have noticed, we used a couple of custom utility functions, namely `redirectToUrl` and `setPaymentToken`. Of course we need to define them as well.
It's common for extensions to need new utility functions. They just need to implement them in the `util` directory, just like you would in a theme.
The `redirectToUrl` in `Redirect.js` is a really simple function that I found on StackOverflow (don't tell anyone). Still, it's nice to have it as a reusable function so the rest of the code is more readable.
{% code title="util/Redirect.js" %}
```javascript
export const redirectToUrl = (url) => {
window.location.replace(url);
};
```
{% endcode %}
The `setPaymentToken` and `getPaymentToken` functions (we haven't used the latter yet) are also very simple. They use the `BrowserDatabase` utility to save (and load) the payment token. This token will still be accessible after redirecting the user to the payment provider's page and back.
{% code title="util/PaymentTokenPersistence.js" %}
```jsx
// Let's use Scandi's BrowserDatabase utility for persistence
import BrowserDatabase from 'Util/BrowserDatabase';
import { ONE_MONTH_IN_SECONDS } from 'Util/Request/QueryDispatcher';
const TOKEN_KEY = 'mollie_payment_token';
export const setPaymentToken = (token) => {
// Again, some error checking can help catch mistakes early.
if (!Boolean(token)) {
throw Error("Must specify token to set")
}
BrowserDatabase.setItem(token, TOKEN_KEY, ONE_MONTH_IN_SECONDS);
};
export const getPaymentToken = () => {
const token = BrowserDatabase.getItem(TOKEN_KEY);
if (!Boolean(token)) {
throw Error("No payment token found in browser database")
}
return token
};
```
{% endcode %}
And with that, the redirection step is complete! If you wish, you can complete an order using Mollie's payment methods to verify that you are indeed redirected.
# Handling the Customer's Return
Handle the customer's return from a 3rd party site
After the customer has entered the payment details on the 3rd party page, they are returned to the e-commerce store. Often, there is additional logic required in this step. For example, you might have to fetch the transaction result to display it to the user.
In our case, we need to call the `mollieProcessTransaction` GraphQL mutation to make sure the transaction is processed, and to retrieve the order result (success/failure, etc.). Finally, we need to display this result to the user, in the form of a success or failure message.
## Setting the Return URL
First, we need to ensure that the correct return URL is used. Since all Scandi checkout steps start with `checkout`, we're going to use `checkout/mollie_result` for the final order processing and displaying the result.
Mollie allows us to do this really easily by configuring some database values:
```php
config = $config;
}
public function install(
ModuleDataSetupInterface $setup, ModuleContextInterface $context
) {
$setup->startSetup();
$this->config->saveConfig(Config::GENERAL_USE_CUSTOM_REDIRECT_URL, true);
$this->config->saveConfig(
Config::GENERAL_CUSTOM_REDIRECT_URL,
'{{secure_base_url}}checkout/mollie_result?order_id={{increment_id}}&mollie_payment_token={{payment_token}}&mollie_order_hash={{order_hash}}'
);
$setup->endSetup();
}
}
```
Now, we need to make sure that the correct business logic takes place after this redirect.
## Processing the Order
When the user is redirected back, we need to use the `mollieProcessTransaction` GraphQL mutation to process the order and get the transaction result.
First, let's take a look at some relevant methods in the `CheckoutContainer`, which renders all `checkout` routes, and thus will be involved in `checkout/mollie_result` as well:
{% code title="scandipwa/src/route/Checkout/Checkout.container.js" %}
```jsx
// [imports...]
// [mapStateToProps and mapDispatchToProps]
/** @namespace Route/Checkout/Container */
export class CheckoutContainer extends PureComponent {
// [...]
__construct(props) {plplu
super.__construct(props);
const {
toggleBreadcrumbs,
totals: {
is_virtual
}
} = props;
toggleBreadcrumbs(false);
this.state = {
isLoading: is_virtual,
isDeliveryOptionsLoading: false,
requestsSent: 0,
paymentMethods: [],
shippingMethods: [],
shippingAddress: {},
checkoutStep: is_virtual ? BILLING_STEP : SHIPPING_STEP,
orderID: '',
paymentTotals: BrowserDatabase.getItem(PAYMENT_TOTALS) || {},
email: '',
isGuestEmailSaved: false,
isCreateUser: false,
estimateAddress: {}
};
if (is_virtual) {
this._getPaymentMethods();
}
}
componentDidMount() {
const {
history,
showInfoNotification,
totals: {
items = []
}
} = this.props;
if (!items.length) {
showInfoNotification(__('Please add at least one product to cart!'));
history.push(appendWithStoreCode('/cart'));
}
}
// [...]
render() {...}
}
export default connect(mapStateToProps, mapDispatchToProps)(CheckoutContainer);
```
{% endcode %}
We'll need to change the behavior of `__construct`, because otherwise it would cause problems by setting an incorrect initial state β such as `BILLING_STEP` or `SHIPPING_STEP` β but we actually want a custom `MOLLIE_PROCESSING_STEP` to be set.
For this, we can write a plugin. The function is very similar to the original one, but sets the correct initial step if applicable:
{% code title="plugin/Checkout.component.plugin.js" %}
```jsx
// We'll define this later...
// MOLLIE_PROCESSING_STEP is a simple string that identifies the current checkout step
import { MOLLIE_PROCESSING_STEP } from './Checkout.component.plugin';
const __construct = (args, callback, instance) => {
const [props] = args;
const {
toggleBreadcrumbs,
} = props;
const { orderId, paymentToken, orderHash } = getParameters();
// This is how we determine that it's a Mollie return URL:
// The mollie_payment_token is specified
if (!paymentToken) {
// Not a return URL, just call the original function
return callback(...args)
}
// Otherwise, we make sure to *not* call the original function
// or else it would interfere with our logic
toggleBreadcrumbs(false);
instance.state = {
isLoading: false,
isDeliveryOptionsLoading: false,
requestsSent: 0,
paymentMethods: [],
shippingMethods: [],
shippingAddress: {},
checkoutStep: MOLLIE_PROCESSING_STEP, // Set a custom step
orderID: orderId,
paymentTotals: BrowserDatabase.getItem(PAYMENT_TOTALS) || {},
email: '',
isGuestEmailSaved: false,
isCreateUser: false,
estimateAddress: {},
mollieParameters: { orderId, paymentToken, orderHash },
mollie: { isLoading: true },
};
};
```
{% endcode %}
We'll also plug into `componentDidMount`, since that's a good place to put business logic that needs to run once when the component is initialized. The original function has some logic that we want to suppress for the Mollie processing step, so we'll check before calling it.
{% code title="plugin/Checkout.component.plugin.js" %}
```jsx
const componentDidMount = (args, callback, instance) => {
const { mollieParameters: { paymentToken: isMolliePayment } = {} } = instance.state;
// Check if it's a Mollie Payment return URL.
if (!isMolliePayment) {
// If not, just call the original function.
return callback(...args)
}
const paymentToken = getPaymentToken();
const processTransactionMutation = MollieQuery.getProcessTransactionMutation(paymentToken);
// Make the GraphQL mutation for processing the transaction
fetchMutation(processTransactionMutation).then(({ mollieProcessTransaction: { paymentStatus, cart } }) => {
instance.setState({
mollie: {
isLoading: false,
paymentStatus,
cart,
},
})
}).catch((e) => {
console.error(e);
instance.setState({
mollie: {
isLoading: false,
paymentStatus: ERROR,
cart: null,
},
})
})
};
```
{% endcode %}
The above plugin makes use of the `MollieQuery` class. That's a query creator utility for `mollieProcessTransaction` which we also have to define:
{% code title="query/Mollie.query.js" %}
```jsx
import { Field } from 'Util/Query';
/** @namespace Query/Mollie */
export class MollieQuery {
getProcessTransactionMutation(paymentToken) {
if (!paymentToken) {
throw Error("The payment_token is required")
}
return new Field('mollieProcessTransaction')
.addArgument('input', 'MollieProcessTransactionInput', { payment_token: paymentToken })
.addFieldList(['paymentStatus', this._getCartField()])
}
_getCartField() {
return new Field('cart').addField('id')
}
}
export default new MollieQuery()
```
{% endcode %}
Finally, don't forget to update the `.container` plugin configuration:
```javascript
export default {
"Route/Checkout/Container": {
"member-function": {
__construct,
componentDidMount,
savePaymentMethodAndPlaceOrder,
},
},
}
```
## Displaying the Result
After the order has been processed, we need to inform the user of the order status.
{% code title="util/PaymentStatus.js" %}
```javascript
// This list was found in Mollie's backend code.
// We define the possible statuses so we can reuse them.
export const CREATED = 'CREATED';
export const PAID = 'PAID';
export const AUTHORIZED = 'AUTHORIZED';
export const CANCELED = 'CANCELED';
export const ERROR = 'ERROR';
export const ALL_SUCCESS = [CREATED, PAID, AUTHORIZED]
// Provides a human-readable, translated string describing the order status.
export const getStatusMessage = (status) => {
switch (status) {
case CREATED:
return __('Your order has been created.');
case PAID:
return __('Your order has been paid.');
case AUTHORIZED:
return __('Your order has been authorized.');
case CANCELED:
return __('Your order has been canceled.');
case ERROR:
return __('There was an error processing your order.')
}
};
```
{% endcode %}
Now, we can add plugins for the Checkout `.component`, which is responsible for the presentation logic of the checkout flow.
```jsx
import { ALL_SUCCESS, getStatusMessage } from '../util/PaymentStatus';
import CheckoutSuccess from 'Component/CheckoutSuccess';
import Loader from 'Component/Loader';
// A string representing the Mollie Processing Step
export const MOLLIE_PROCESSING_STEP = 'MOLLIE_PROCESSING_STEP';
function renderMollieStep() {
const { mollie: { isLoading, paymentStatus } = {}, orderID } = this.props;
// Display a loader while the order is processing
if (isLoading) {
return ![]()
` elements, it converts them into `` components, making them consistent with the rest of the app.
Importantly, all `` elements are turned into the `` component. This is what enables Scandi to process the CMS widgets.
### The `WidgetFactory` Component
In the `WidgetFactory`, different widget types are mapped to corresponding components. The `renderContent` function then renders the appropriate component for the widget, passing on all the attributes as props:
```jsx
import PropTypes from 'prop-types';
import { lazy, PureComponent, Suspense } from 'react';
import RenderWhenVisible from 'Component/RenderWhenVisible';
import {
CATALOG_PRODUCT_LIST,
NEW_PRODUCTS,
RECENTLY_VIEWED,
SLIDER
} from './WidgetFactory.config';
import './WidgetFactory.style';
export const ProductListWidget = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "category" */ 'Component/ProductListWidget'));
export const NewProducts = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "category" */ 'Component/NewProducts'));
export const HomeSlider = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "cms" */ 'Component/SliderWidget'));
export const RecentlyViewedWidget = lazy(() => import(/* webpackMode: "lazy", webpackChunkName: "category" */ 'Component/RecentlyViewedWidget'));
/** @namespace Component/WidgetFactory/Component */
export class WidgetFactory extends PureComponent {
static propTypes = {
type: PropTypes.string.isRequired
};
renderMap = {
[SLIDER]: {
component: HomeSlider,
},
[NEW_PRODUCTS]: {
component: NewProducts
},
[CATALOG_PRODUCT_LIST]: {
component: ProductListWidget
},
[RECENTLY_VIEWED]: {
component: RecentlyViewedWidget
}
};
renderContent() {
const { type } = this.props;
const {
component: Widget
} = this.renderMap[type] || {};
if (Widget !== undefined) {
return (
);
}
return null;
}
render() {
return (
{ this.renderContent() }
);
}
}
export default WidgetFactory;
```
Finally, the individual widget components (`ProductListWidget`, `NewProducts`, etc.) are regular React components responsible for rendering their widget.
# Creating a Magento Widget
Since widgets are created in the admin panel, we first need to write some Magento logic for the backend part of the widget.
The Magento Developer Docs have a [great guide](https://devdocs.magento.com/guides/v2.4/ext-best-practices/tutorials/custom-widget.html) for creating a widget. Lets walk through what you need to do to create a new widget to later make it work with Scandi.
## Create the Widget Block
Create a Block class for the widget. It needs to extend `Template` and implement the `BlockInterface`. Other than that, the only thing we need to do is specify the `_template` the widget uses.
{% code title="app/code/ScandiTutorials/CustomWidget/Block/Widget/NewsletterWidget.php" %}
```php
escapeHtml($block->getData('title'))` and assign it to the `data-title` attribute:
{% code title="app/code/ScandiTutorials/CustomWidget/view/frontend/templates/widget/newsletter\_widget.phtml" %}
```php
` element can appear in the CMS content, we need to implement parsing it and rendering a custom React element in its place. Luckily, as outlined in the intro section, Scandi already parses all CMS content β all we need to do is define a new widget type!
## Create a Component
We need to create a Component for the widget. This will just be a regular Scandi React component that takes the widget attributes (only `data-title` in this case) as props.
To create a new widget, you can just use the ScandiPWA CLI utility:
```
scandipwa create component NewsletterWidget
```
Our widget needs to let the user subscribe to the newsletter. Thankfully, this functionality is already implemented in the `NewsletterSubscription` component, so we can re-use that. All we need to do is add the widget title. Hence, the implementation is pretty simple:
{% code title="src/component/NewsletterWidget/NewsletterWidget.component.js" %}
```jsx
/** @namespace TutorialCsaApp/Component/NewsletterWidget/Component/NewsletterWidgetComponent */
export class NewsletterWidgetComponent extends PureComponent {
static propTypes = {
'data-title': propTypes.string.isRequired
};
render() {
const { 'data-title': title } = this.props;
return (
" %}
Let's talk theory
{% endembed %}
ScandiPWA v3 has arrived at your doorstep and with it comes a new tech stack. Letβs talk about it!
Topics covered in this tutorial:
* β[Whatβs Wrong With jQuery?](/tutorials/video-tutorials/lets-talk-theory#whats-wrong-with-jquery)β
* β[History API](/tutorials/video-tutorials/lets-talk-theory#history-api)β
* β[React and JSX](/tutorials/video-tutorials/lets-talk-theory#react-and-jsx)β
* β[Setting Up The Environment](/tutorials/video-tutorials/lets-talk-theory#setting-up-the-environment)β
* β[VSCode Extensions](/tutorials/video-tutorials/lets-talk-theory#vscode-extensions)β
* β[Node](/tutorials/video-tutorials/lets-talk-theory#node)β
* β[Yarn](/tutorials/video-tutorials/lets-talk-theory#yarn)β
* β[Installing The ScandiPWA App](/tutorials/video-tutorials/lets-talk-theory#installing-the-scandipwa-app)β
## Whatβs Wrong With jQuery?
ScandiPWA v2 used [jQuery](https://jquery.com/) - an API for working with document object models or DOMs. Allegedly, jQuery lets you do more while writing less. So, why use something else?
Each page of an application has a header, a footer and some content. We need to customize all of this periodically. The jQuery library theoretically allows us to have easy access to any specific element, but it would be very messy to implement as a jQuery template due to the fact that it consists of pure strings that are hard to edit.
## History API
With the coming-of-age of [history API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) ScandiPWA has switched to React.
Previously each page you visited made a request to a server, which then provided a renderable output. Now, we can skip the server step and start to render the page on the clientβs side by re-using the URL thatβs currently being visited, if it had been visited at some point in history.
The history API lets us track the changes made in the state of the application and control the routing.
## React and JSX
Moreover, [React](https://reactjs.org/) in itself allows us to write simple, editable templates and components. These so-called components are encapsulated code chunks that later will be shipped or not shipped based on necessity.
β[JSX](https://reactjs.org/docs/introducing-jsx.html) is a syntax extension to JavaScript which means that we can use the JS variables, expressions etc. inside of it to write a template.
For example, here we define a constant that gets assigned a JSX tag:
```
const element =
```
After youβve successfully created the ScandiPWA theme, go to your themeβs folder and run the following command that will compile the project:
```
yarn start
```
Letβs look at the file structure:
```
π β£ πi18n # internationalization folder β£ πmagento β£ πnode_modules # contains the app's dependencies β£ πpublic # assets should be put here β£ πsrc # empty source folder β£ πcomposer.json β£ πpackage.json β πyarn.lock
```
The `src` or source folder will be empty in a fresh install. Since ScandiPWA is meant to be extended, not modified, a fresh install will run the default ScandiPWA theme until new files that will override the theme are added to the `src` folder.
You can check out the what the default theme consists of in `node_modules/@scandipwa/scandipwa/src` - the original source folder.
The `public` folder should contain any assets you want to have like fonts, icons etc.
`i18n` or internationalization folder contains files for locale handling and translations of any phrases you have on the app.
The `package.json` file contains two dependencies:
```
"dependencies": { "@scandipwa/scandipwa": "0.0.1", "@scandipwa/scandipwa-scripts": "0.0.5"}
```
`scandipwa` dependency currently is in v2.17.0. `scandipwa-scripts` dependency contains the `webpack` configuration.
There are two scripts available out of the box as well:
```
"scripts": { "start": "scandipwa-scripts start", "build": "scandipwa-scripts build"}
```
The `start` command begins the local file watching process and starts the local dev server that will let you see the changes in the browser right as youβve made them.
Note that `yarn start` was the first command that we ran, thus the development process can begin. You can check out your theme by going to `localhost:3000` in your browser.
The `build` command is for starting the production build process. You can build in Magento mode as a Magento theme and you can also build as a store front.
If you want to build ScandiPWA as a Magento theme, youβll notice that the `composer.json` file contains the theme registration and the `magento` folder contains all of the assets needed for defining a theme.
# #2 Templating in React
{% embed url="" %}
Going hand on
{% endembed %}
In this tutorial we will discuss the following React concepts:
* [Component state](/tutorials/video-tutorials/templating-in-react#component-state)
* [Components update tracking logic](/tutorials/video-tutorials/templating-in-react#components-update-tracking-logic)
* [ShouldUpdate method](/tutorials/video-tutorials/templating-in-react#shouldupdate-method)
* [PureComponents VS traditional Components](/tutorials/video-tutorials/templating-in-react#purecomponents-vs-traditional-components)
* [Handling side-effects in getDerivedStateFromProps](/tutorials/video-tutorials/templating-in-react#handling-side-effects-in-getderivedstatefromprops)
You should be able to discuss the following topics after watching this video:
* onClick as an arrow function, bind, non-bind
* setState as a function and via state destruct
* Checking for prev value in componentDidUpdate
* Defining state examples, in constructor, as a property
* Updating state in component did-update consequences
* Keeping previous property in state
This tutorial builds on the [previous](/tutorials/video-tutorials/lets-talk-theory) one. If youβve been wanting to work with ScandiPWA youβll know that itβs meant to be extended. This is done by creating new files in your project that will override the defaults.
Run `yarn start` to start the development set-up and letβs start by overriding the `index.js` file. Create a new `index.js` file in your `src` folder. The application should compile automatically after youβve saved any changes.
This is what our `src/index.js` should contain:
```javascript
import { Component } from 'react';
import ReactDOM from 'react-dom';
class Button extends Component {
render () {
return (
);
}
}
ReactDOM.render(
// this is the component's template
,
document.getElementById('root')
);
```
The component should be passed as a render template and after this we should tell React where we expect this element to render.
If you go to `localhost:3000` in your browser youβll see that the element has rendered.
Letβs make it a clickable button:
```javascript
import { Component } from 'react';
import ReactDOM from 'react-dom';
class Button extends Component {
onButtonClick() {
// writes logs in console
console.log('you clicked me!');
}
render () {
return (
// adds event listener
);
}
}
ReactDOM.render(
,
document.getElementById('root')
);
```
In React you need to provide a listener for the element when itβs initially rendered, with the listener in this case being `
Don't Panic
Welcome to my website.
{ __('Today, I am brimming with energy and overflowing with joy.') }
{ __('I live in the moment while learning from the past and preparing for the future.') }
{ __('Life is beautiful.') }
{ name }
{ __('Our Promise to You') }
{ __('Everything we make is guaranteed to work for at least two years. It cannot break. If it' + ' breaks it\\'s probably your fault.') }
{ __("Loading, please wait") }
); } const message = getStatusMessage(paymentStatus); return ({ message }
); }; // Plugin configuration as always. export default { 'Route/Checkout/Component': { 'member-property': { stepMap, }, 'member-function': { renderTitle, }, }, } ``` ## Conclusion At this point, we've covered the main steps in integrating a payment method extension in Scandi. Usually, you need to do some debugging to make sure everything is working properly β payment integration can be tricky! You should be able to test your extension using the test mode of the payment provider. When you're done with the extension, consider publishing it on the ScandiPWA Marketplace so others can benefit from your creation! # Creating a Custom Widget Create a widget you can use anywhere in the Magento CMS! > A [widget](https://docs.magento.com/m2/ce/user_guide/cms/widgets.html) is a prepared snippet of code that can be used to place blocks, links, and dynamic content at specific locations on store pages. You can use widgets to create landing pages for marketing campaigns, display promotional content at specific locations throughout the store. Widgets can also be used to add interactive elements and action blocks for external review systems, video chats, voting, and subscription forms, or to provide navigation elements for tag clouds and image sliders. > > *β* [*Magento Glossary*](https://glossary.magento.com/widget/) Since most of the Scandi presentation logic happens on the frontend, the CMS system is a little different in Scandi than default Magento. For this reason, you need to take a slightly different approach when developing a widget for Scandi. In this example, we will create a newsletter widget. The CMS author will be able to add the widget anywhere and specify its title. Then, the customer will see the title and newsletter block on the frontend. # Scandi CMS System Overview An overview of how the Scandi CMS system works with widgets. First, let's get familiar with how the widget system works in Magento+Scandi. This will give you a high-level understanding on what bits of code need to be added to create a new widget. {% hint style="info" %} Reading this section is optional, and only needed if you want to get a high-level understanding for the context of the code we'll be writing. {% endhint %} ## The Widget System First, let's get familiar with how the widget system works in Magento+Scandi. As an example, suppose the Admin creates a home page CMS page with a `RecentlyViewed` widget. The CMS source code would contain a `{{widget}}` template: ```markupSome CMS text...
{{widget type="Magento\\Catalog\\Block\\Widget\\RecentlyViewed" uiComponent="widget_recently_viewed" page_size="5" show_attributes="name,image,price,learn_more" show_buttons="add_to_cart" template="product/widget/viewed/grid.phtml"}}
``` When rendering the page, the Magento CMS system will parse the `widget` template, and convert it into a widget element: ```markupSome CMS text...