README

这是我们为基于 Magento 2 的商店提供的父主题。

要求

• Magento 2
• NodeJS
• Gulp

文档

• 第一步
  • 构建 Creativeshop
  • 设置新主题
  • 开发
• 添加新组件
  • 组件结构
  • 入口文件
• 样式定制
  • 定制过程
  • 定制 <your-theme>/src/config
  • 定制现有组件
  • 混合和钩子
• 分割入口
• 常见问题解答

第一步

Creativeshop 是一个利用 MageSuite 所有功能的 Magento 2 主题包。它依赖于基于组件的开发方法，因此可以通过添加新组件或覆盖现有组件来轻松地根据您的需求进行定制和扩展。本指南将向您展示如何设置 Creativeshop 项目，解释推荐的工作流程，并展示如何使用其最佳功能，定制它们，并添加新的功能以适应您的需求。

在安装MageSuite 后，您需要构建 Creativeshop 并然后创建您自己的子主题。MageSuite 不依赖于 Magento 来构建资产，而是使用基于 Webpack 和 Gulp 的自己的解决方案。多亏了它，您只能用您的代码维护主题存储库；其余的将在构建过程中从 Creativeshop 继承。

构建 Creativeshop

在开始之前，请确保您已经安装了Node.js。

1. 导航到 vendor/creativestyle/theme-creativeshop。
2. 运行 yarn install && yarn build。它将在 app/design 目录中安装依赖项并构建工件。

设置新主题

1. 安装 MageSuite 主题生成器。这是一个小的 NPM 包，它为您创建基于 Creativeshop 的新主题的所有脏活累活。
2. 导航到 vendor/creativestyle 并运行 magesuite-theme-generator 命令，生成器将询问您几个问题。
3. 导航到您的新主题目录（vendor/creativestyle/<your-theme>）并初始化版本控制系统。
4. 以与构建 theme-creativeshop 相同的方式构建您的新主题。
5. 运行 bin/magento setup:upgrade。
6. 将活动 Magento 主题更改为您的新主题。

现在您应该已经设置了带有您的新 Creativeshop 基于主题的 Magento 安装并运行。

不要忘记在内容→设计→配置中将 theme-creativeshop 或您的新主题设置为全局，否则 Magesuite 的内容构造器将无法正常工作。.

开发

Creativeshop 设计用于实现便捷的 Magento 2 开发环境。在您创建了自己的新主题后，您可以使用、修改或添加您在父主题中找到的任何组件。整个继承过程是主题构建过程的一部分，它结合了作为主题开发者需要执行的所有操作。以下是一些您可以选择执行的命令，具体取决于您想实现什么

• yarn build：从 vendor/creativestyle/<your-theme> 构建整个主题到 app/design/frontend/creativestyle/<your-theme> 目录，其中 Magento 可以找到并应用它。
• yarn gulp watch：与上述相同，但每次在源目录中任何更改时，都会自动触发构建。
• yarn start：与上述相同，但设置了额外的Browsersync服务器。它提供浏览器自动重新加载、CSS注入以及隧道本地环境的能力，因此可以在同一网络中的任何设备上打开它。

如果您想知道构建过程的详细情况

• 将清除目标目录中的旧文件，以避免留下任何不需要的残留物。
• 将复制和优化图像。
• 复制不需要任何转换的杂项文件，例如字体和模板。
• 编译和优化SCSS和TypeScript源文件。
• 清除Magento前端缓存。

您已经安装并构建了基于Creativeshop的第一个主题。那么，给它添加一些新组件怎么样？

添加新组件

创建新组件是使用Creativeshop的开发过程的核心。如果您想定制现有组件或从头开始编写自己的组件，这是您应该做的第一件事。

Creativeshop集成了可以称为组件继承的功能。一旦您正确创建了子主题，它就可以继承所有父组件。您可以随意修改这些继承组件——修改到任何程度或直接使用而不做任何更改。这是构建主题的强大工具，这些主题由精选的、易于使用和可定制的部分组成。

记得这个继承过程的一个主要规则——如果子主题中缺少文件，则将包含父主题中相应的文件。这就是为什么您可以安全地省略任何文件，甚至入口文件，主题仍然会被编译。有趣的是，继承链可以与任何数量的主题一起工作，因此您可以有孙子、曾孙主题等等。

让我们在我们的子主题中创建一个新的addtocart组件。这个组件负责显示按钮和产品数量选择。

组件结构

组件存储在~Creativeshop/src/components/<component>目录中。我们将把theme-creativeshop Magento包的路径称为~Creativeshop，将组件的名称称为<component>。您通常可以在该文件夹中找到以下内容

• index.ts：入口文件。包含依赖项导入、TypeScript模块和SCSS文件，以及初始化最终网站中组件的脚本。
• <component>.ts：包含组件定义的TypeScript模块。
• <component>.scss：组件样式。
• mixin.scss：组件样式中使用的混合声明的声明。
• hook.scss：组件混合钩子。

上面列出的文件并非全部必需。从技术上讲，功能性的Creativeshop组件不过是导入所需文件并导出给Webpack使用的TypeScript模块。

现在，让我们在您的~Creativeshop/src/components中创建addtocart文件夹。请注意，您的新组件的路径必须与父组件的路径匹配。

入口文件

您可以看到原始的addtocart组件入口文件

import AddToCart from 'components/addtocart/addtocart';
import 'components/addtocart/addtocart.scss';
new AddToCart();

该文件的责任如下

• 它导入组件TypeScript类。这也可能是纯TypeScript或甚至是JavaScript模块，但我们推荐使用经典面向对象方法。
• 它导入组件样式。
• 它初始化最终网站中的组件。

您可能会注意到许多Creativeshop组件导入并使用jQuery。您可以导入在node_modules中安装的任何其他第三方库。也经常导入其他Creativeshop组件作为依赖项。

如果你的新组件仅用于自定义现有父组件，那就这么简单！从现在起，你可以将任何文件插入到你的组件目录中，它会覆盖父主题中的相应文件。就这么简单。然而，请注意，如果你的组件不仅仅是为了自定义目的，还需要额外的步骤来使其工作。你稍后会了解到这一点。

你刚刚了解了Creativeshop组件的内部工作原理，并添加了你的第一个自定义组件。那么，来定制一些样式怎么样？

样式定制

为店面进行样式设计是每个Magento项目的重中之重。Creativeshop旨在为最终用户和开发者提供最佳的端到端体验——因为我们应该在开发中寻找乐趣，不是吗？

有两种方法可以自定义Creativeshop组件的样式

• 覆盖Sass变量。你可以使用大量变量来快速配置代码的某些部分，例如填充、颜色、动画、图标等等。
• 覆盖CSS规则集。你可以将你的代码与现有代码库混合，得到期望的效果。你可以通过修改原始样式或从头开始编写样式来实现。

如果你曾经使用过Bootstrap或Foundation等现代CSS框架，你可能对第一种方法很熟悉。这在某种程度上是方便的——但是当你想要更多控制前端的外观和感觉时，问题就开始了。通常情况下，唯一的解决办法是复制原始代码中的规则集并修改它们，或者创建新的具有更高特异性的规则集。这两种方法都是非常繁琐的任务，最终会使你的代码库难以维护。

Creativeshop通过允许你直接覆盖子主题中特定的CSS规则集来优雅地解决这个问题。在构建过程中，你的自定义组件样式将与原始样式合并——就像网页浏览器计算最终样式一样。你可以完全控制输出。你可以修改一些声明，或者从头编写全新的代码，最好的是，你总是可以精确控制选择器和特异度。

定制过程

• 在src/config/colors中为颜色名称变量分配颜色——我们使用十六进制颜色代码
• 在src/config/variables中将颜色名称变量分配给主题变量
• 在<your-theme>/src/components/component.scss中添加/修改组件变量

这些依赖项使我们能够通过仅调整变量来非常快速地更改整个主题的颜色设置。

定制 <your-theme>/src/config

颜色

src/config/colors - 在这里，你应该为你的主题中使用的所有颜色创建变量。

• 首先从theme-creativeshop导入颜色，以便也能使用它们：@import '~Creativeshop/config/colors';
• 使用在线工具命名颜色，例如color-name-hue或name-that-color

来自src/config/colors的片段

@import '~Creativeshop/config/colors';

$color_monza: #da001a; $color_monza--hover: #ce0019;

$color_lochinvar: #2b827c; //$color_secondary-500, $color_secondary-200

$color_desert-storm: #f3f3f2; // $color_background-500,灰色背景 $color_alto: #dcdcdc; // $color_border-200, $color_background-600,浅边框，与magesuite相同

$color_gray-nurse: #e6e7e5; // $color_background-800

$color_dust-gray: #9b9b9b; // $color_text-400, $color_border-500, $color_border-700,浅文本，输入（基本）边框 $color_pumice: #bfc0bf; // $color_border-500

#### Variables

`src/config/variables` - here store all the variables used in the whole theme, such as colors - primary, secondary, background, font-sizes, font-weight, etc.

* Start with the import of variables from theme-creativeshop to be able to use them as well: `@import '~Creativeshop/config/variables';`
* Theme-creativeshop provides a lot of variables and most of them should be overwritten.
* Follow the convention: `component_element-modifier` (with one underscore and one hyphen). If modifiers are numbers, they indicate the degree or intensity - 200 is the lightest and 900 is the darkest.

> Snippet from `src/config/variables`

@import '~Creativeshop/config/variables';

$color_text-400: $color_dust-gray; //浅灰色 $color_text-500: $color_abbey; $color_text-600: $color_abbey;

$price_color: $color_primary-500; $price_special-color: $color_primary-500;

$global_header-height-mobile: 5.5rem;

$border-radius_base: 5px;

$global_header-hide-search-item-trigger-breakpoint: '>=laptop';

All the variables in theme-creativeshop are marked as `!default`. This means that they are taken by default, but if you create a variable with the same name, you will overwrite it and the new variable will be taken into account. 

`src/config/base` - basic styling of basic components, such as body, buttons, etc. 

`src/config/breakpoints` - this is where the breakpoints structure is set; likely, you won't have to make any changes to this file. 

#### Variables naming convention

`$component-name_element-name` - use the underscore only once:

> Snippet from `your-theme/src/components/footer/footer.scss`

@import 'config/variables';

$footer_background: $color_background-550;

$footer_section-title-color: $color_text-200; $footer_section-title-font-size: 1.4em;

$footer_section-separator-border: 1px solid $color_border-400;

$footer_section-plus-include: false; $footer_section-dropdown-width: 1.6rem; $footer_section-dropdown-height: 1rem; $footer_section-dropdown-color: $color_primary-500;

$footer_logo-width: 13.5em; $footer_logo-height: 2.3em;

## Customizing existing components

* The styling takes place in component (`<your-theme>/src/components/component`).
* To customize each component, create a component under the same directory in your theme and import the original component into it.
* Do not change anything in theme-creativeshop, but make all the changes in your theme, creating the same structure of components. 

Once the configuration folder is ready, you can start customizing the components. A simple component includes: 

* `new-component.ts` - contains the definition of the component
* `new-component.scss` - contains styling of the component
* `index.ts` - imports the component styles and initializes it. 

Some of them contain subfolders or additional files.

If you customize a component existing in theme-creativeshop, you do not need to create a `.ts` files in your topic unless you want to expand more `.ts` structure.

If you only want to customize SCSS, create a `.scss` file with the same path as the original one and import the original `.scss` file into it.

Don't forget to import the component from theme-creativeshop to be able ro reuse it's variables and functionalities.

> Snippet from `your-theme/components/container/container.scss`

@import 'config/variables'; @import 'vendors/include-media';

@import '~Creativeshop/components/container/container.scss';

.#{$ns}container {

$root: &;

&--page-pdp-details-main {
    @include media('<tablet') {
        padding: 0;
    }
}

}

In each component, you start the customization process by overwriting the variables. Add new variables if needed. Below, import the original component, and then start entering your styles into the existing classes.

Sometimes there are subfolders in the component. During the customization process, it is important to have the same folder structure. Only then the gulp merging process will run correctly.

### Mixins and hooks

* We use SASS mixins to make our code reusable and more versatile.
* You will find mixins files created for components that can have different variants - e.g. buttons, teasers, badges, etc.
* Use the hook files to modify mixins - it is always empty in theme-creativeshop and you can overwrite this file by creating it in your theme to modify a specific mixin. 
* If you want to overwrite the variables declared in the mixin file, do so in the appropriate mixin file in your theme. 

> Snippet from `your-theme/src/components/badge/mixin.scss`

@import 'config/variables'; @import 'components/badge/hook';

$badge_height: 2.1rem; $badge_padding: 0.5rem 1.2rem; $badge_border-radius: 0;

$badge--new-background: $color_background-700; $badge--new-color: $color_white;

$badge--sale-background: $color_primary-500; $badge--discount-background: transparent;

$badge--free-shipping-background: $color_background-700; $badge--popular-background: $color_background-700;

@import '~Creativeshop/components/badge/mixin.scss';

Below snippet from `your-theme/src/components/badge/hook.scss`

@import 'utils/get-value-from-list';

/ stylelint-disable block-no-empty / @mixin badge_hook($type) {

display: flex;
flex-direction: column;
min-width: 5rem;

&:before {
    content: none;
}

}

@mixin badge_type-hook($type) {

@if ($type == 'is_advertised') {
    background-color: $color_background-900;
    color: $color_white;
}

@if ($type == 'discount') {
    min-width: 4.8rem;
    padding: 0 ;
}

}

#### Utils

There are additional useful functions here, often imported in components. It is good to familiarize yourself with them to be able to use them.  

You've just learned about good style customization practices. It's time to find out how to add your own brand new component!

## Split entries

To increase the performance of the pages loading, we decided to use [Webpack's split chunks feature](https://webpack.js.cn/plugins/split-chunks-plugin/), which allows dividing bundles into chunks.
The idea behind was to not load every Magesuite component at once, just to have a commons bundle with components that are always required and the smaller bundles that we can import exactly when we need it.
Webpack takes all the entries and extracts the commons bundles (*commons.js* and *commons.css*) containing components used in most of the entries, then puts the rest in smaller particular bundles.
Build files you can find in `app/design/frontend/creativestyle/theme-creativeshop/web/js` and `app/design/frontend/creativestyle/theme-creativeshop/web/css`.

> Example:
> Assume we have 2 entry points: *pdp.ts* and *category.ts*. Each of them imports components/product-tile plus its specific components, like `pages/pdp` and `pages/category`.
> Based on that, Webpack creates commons.js and commons.css bundles containing the *product-tile* component logic and styling. But it also creates *pdp.js*/*pdp.css* and *category.js*/*category.css* bundles to be used for PDP or category page only.

In ,theme-creativeshop/src/entries, you can find two types of entry points: **entries for pages** (ex. category.ts) and **entries for modules** (ex. magesuite-brand-management.ts). 

### Base entries

They should contain **all components** that are needed for some specific page in the shop.
Bundles produced from these entries we import on particular pages

Regarding CSS, we add the commons.css to every page in the shop and add other bundles via xml inside the `<head>` tag in places where we need them.

> Example: `theme-creativeshop/src/Magento_Catalog/layout/catalog_product_view.xml`

As for the Javascript bundles, they have defined an explicit dependency on the commons.js package (in `theme-creativeshop/src/requirejs-config.js`).

To add the single JS bundle we use the reference to the script block where we can pass the bundle_name argument.

> Example: theme-creativeshop/src/Magento_Catalog/layout/catalog_product_view.xml

**Important:** When we use this script block, we replace the js bundle, not adding another one, so you need to be sure that bundle you use contains all the required components.

Basically, the most important entries are:
* `cms.ts` - cms pages
* `pdp.ts` - product details page
* `category.ts` - products overview page (category)
* `checkout.ts` - checkout, cart pages
* `customer.ts` - user area pages
* `contact.ts` - contact page

They are responsible for basic pages across the shop and contain all the components that are required for them.

By default, we use cms.js bundle as the base one.


### Entries for modules

They can contain styles and logic used by the specific module. Bundles generated form them, we use only as an addition to the base bundles. 
For example, the *magesuite-brand-management.ts* entry imports only styling for the brand list (`MageSuite_BrandManagement/web/css/brands-index.scss`).

Brand page itself relies on category.js and category.css bundles but in addition, we attach magesuite-brand-management.css bundle to it

### Adding components to entries

To add a new component, you have to import it in every entry where you want it. 
For example, if you want to add some "special-product-promo" component, which will be used on category page and PDP only, you have to add below code to the pdp.ts and category.ts entries.

import 'components/special-product-promo';

# Frequently asked questions

* [Unable to add image in Hero Carousel](https://github.com/magesuite/magesuite/issues/25)
* [Admin - console error `Cannot read property 'defaults' of undefined`](https://github.com/magesuite/magesuite/issues/23)
* [Component paragraph fails to render in frontend](https://github.com/magesuite/magesuite/issues/22)