From 9f0dbd4861beb71767988691da051f90da8f275e Mon Sep 17 00:00:00 2001 From: Ania Date: Tue, 29 Mar 2022 01:07:19 +0000 Subject: [PATCH] 80366 update docs --- README.md | 547 ++--------------------------------- Snowdog_Components/README.md | 19 +- docs/alpaca-step-by-step.md | 74 ++++- docs/magento-setup-guide.md | 60 +++- docs/working-with-alpaca.md | 420 ++++++++++++++++++++++++++- 5 files changed, 550 insertions(+), 570 deletions(-) diff --git a/README.md b/README.md index 6460cba32..34590b707 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,9 @@ # Alpaca - components & theme for Magento 2.4 ## Migration guide for Alpaca theme >= 2.26.0 `2.26.0` version includes a lot of changes and has different files structure, please go to [Migration Guide](.doc/MIGRATION_GUIDE.md) for more informations + +Latest Alpaca version supports work with Magento 2.4.3.
+If you use lower Magento versionb, check the [Changelog file](../CHANGELOG.md) to decide which version to use.
. ## Description Alpaca Theme for Magento 2 is part of a `alpaca-packages` To make it work with all features, we use following modules: @@ -41,537 +44,25 @@ Additional, non-opensource modules the theme works with to cover additional feat * blackbird/contentmanager * vladimirpopov/webforms -## Installation -Install whole package using composer: -`composer require snowdog/module-alpaca-packages` - -Install [snowdog/frontools](https://github.com/SnowdogApps/magento2-frontools): -`composer require snowdog/frontools` - -Node.js [LTS version](https://nodejs.org/en/about/releases/). We recommend using [Volta](https://volta.sh/). - -### Theme -1. Create child theme composer repository: - * default Magento 2 theme files: `theme.xml`, `registration.php`, `preview.jpg`, `.gitignore`, `composer.json` - * `composer.json` example file: - ```json - { - "name": "vendor/theme-frontend-child-theme", - "description": "Child frontend theme", - "type": "magento2-theme", - "require": { - "snowdog/theme-frontend-alpaca": "", - "vendor/module-child-theme-frontools": "" - }, - "autoload": { - "files": [ - "registration.php" - ] - } - } - ``` - * in `theme.xml` set Alpaca theme as a parent: `Snowdog/alpaca` - * add following files: - * `styles/styles.scss` - ```scss - // Component variables - @import '../Snowdog_Components/components/Atoms/variables/variables'; - @import '../Snowdog_Components/components/Atoms/variables/-variables'; - - // Components - @import '../Snowdog_Components/components/styles'; - - // Theme styles - @import 'theme'; - ``` - * `Snowdog_Components/components/Atoms/variables/_-variables.scss` - to overwrite globals variables which you need -2. Create separate module with frontools configuration (it should be required in theme composer dependencies). -Example: `vendor/module-child-theme-frontools`. - * File structure: - - ``` - +--config - | +--browser-sync.json - | +--themes.json - +--composer.json - ``` - * `config/browser-sync.json`: - - Basic configuration for browsersync (set path for project's local url): - ```json - { - "proxy": "child-theme.test", - "rewriteRules": [ - { - "match": ".child-theme.test", - "replace": "" - } - ] - } - ``` - * `config/themes.json` - - Themes configuration: - - ```json - { - "alpaca": { - "src": "vendor/snowdog/theme-frontend-alpaca", - "dest": "pub/static/frontend/Snowdog/alpaca", - "locale": ["en_US"], - "ignore": [ - "**/node_modules/**", - "**/Snowdog_Components/docs/**", - "**/Snowdog_Components/build/**" - ] - }, - "child-theme": { - "parent": "alpaca", - "src": "vendor/theme-frontend-child-theme", - "dest": "pub/static/frontend/Vendor/child-theme", - "locale": ["en_US"], - "ignore": [ - "**/node_modules/**", - "**/Snowdog_Components/docs/**", - "**/Snowdog_Components/build/**" - ] - } - } - ``` - * `composer.json`: - - add `snowdog/frontools` as a dependency, - it is recommended to use latest version but you can choose the frontools version you need. - ```json - { - "name": "vendor/module-child-theme-frontools", - "type": "magento2-component", - "require": { - "snowdog/frontools": "^1.8.0" - }, - "extra": { - "map": [ - [ - "config", - "dev/tools/frontools/config" - ] - ] - } - } - ``` -3. Install theme with frontools dependencies using composer: - -`composer require vendor/theme-frontend-child-theme` - -### Components -`theme-frontend-alpaca/Snowdog_Components` it's separate [fractal.build](https://fractal.build/guide/) project integrated with Magento 2 Theme. It is not set as a separate composer package (neither separate git repository) to work with Magento theme easier and faster. -But you can work on components separately and run them outside of Magento. - -#### To build custom components based on Alpaca components: - -1. Copy-paste `package.json`, `gulpfile.js`, `.eslintignore`, `.eslintrc`, `.sass-lint.yml`, `.stylelintrc` files into `theme-frontend-/Snowdog_Components`: - -2. Update project names in `package.json` and `gulpfile.js` - -3. Copy `styles.scss` and `checkout.scss` from `theme-frontend-alpaca/Snowdog_Components/docs/styles/` and add child project variables import there. -Your `styles.scss`: - -```scss -// Variables -@import '../../components/Atoms/variables/variables'; -@import '../../components/Atoms/variables/-variables'; - -// Components -@import '../../components/styles'; - -// Styles necessary only for Fractal purposes -@import 'fractal'; -``` - -Your `checkout.scss`: -```scss -// Variables -@import '../../components/Atoms/variables/variables'; -@import '../../components/Atoms/variables/-variables'; - -// Components -@import '../../components/checkout'; - -// Styles necessary only for Fractal purposes -@import 'fractal'; - -``` - -4. Create `modules.json` file with an array of paths to parent components libraries. -To inherit dependencies from Alpaca components, you have to define path to `theme-forntend-alpaca/Snowdog_Components`. -In most cases it will look like this: - ```json - [ - "../../../snowdog/theme-frontend-alpaca/Snowdog_Components" - ] - ``` -5. Customize or add new files following the same structure as in Alpaca components - -6. Run `yarn` and `yarn dev` to run components in fractal :tada: - -If you don't work with Magento and want to use only components for some other project, you can create separate repository or/and composer/npm package from `theme-frontend-alpaca/Snowdog_Components` and set dependence to Alpaca components (`theme-frontend-alpaca/Snowdog_Components`) inside it. - -## Working with components & theme - customisation guide - -### Customising components with variables - -* Overwrite any variable in child theme global variable files (`Snowdog_Components/components/Atoms/variables/_-variables.scss`). -* Overwrite component's variable file: - -Almost every component has its own `_component-variables.scss` file. -You can overwrite single variable and add it to the global file or copy particular file to the same structure inside `theme-frontend-child-name/Snowdog_Components` folder and change variables there. -* Create custom file with overwritten variables and import it in the main styles file - -### Customising components - -* Overwrite the same file in Snowdog_Components files structure (`.hbs`, `.config.js`, `.scss`) -* Creating new components and import styles for it - -More about working with Alpaca Components directly in components' [README.md](Snowdog_Components/README.md) - -### Customising theme files -* Follow standard Magento way to work with [Theme inheritance](https://devdocs.magento.com/guides/v2.3/frontend-dev-guide/themes/theme-inherit.html) -Remember: -* Layout XML file extends the one from parent theme, so there is no need to copy file, just add particular Layout XML file and add/remove/customize what you need. -* Template has to be overwritten in the child theme - -### styles - -Styles in Alpaca are separated: -* Components styles inside `theme-frontend-alpaca/Snowdog_Components` to work with components directly. - Components are divided into Atomic groups (Atoms, Molecules, Organisms, Templates) and imported in [main styles file](Snowdog_Components/docs/styles/styles.scss) - - Those styles are also imported inside the theme in [main styles file](styles/styles.scss) - Additionally, inside components, we have separated styles for [checkout](Snowdog_Components/docs/styles/checkout.scss). - -* To add new component and import style for it, copy-paste the file for import styles inside group (ex. [Molecules styles import](Snowdog_Components/components/Molecules/_components.scss), and add your import there. -* During styles compilation for theme, following directories are ignored: -``` -"**/node_modules/**", -"**/Snowdog_Components/docs/**", -"**/Snowdog_Components/build/**" -``` -It should be added in `themes.json` in [frontools config](#theme-configuration) as ignores files -* Inside theme, we have main styles file and separate styles for [gallery](styles/gallery-styles.scss) and for [checkout](Magento_Checkout/styles/checkout.scss) - +## What Alpaca is? +Alpaca is a Magento 2 theme based on components system. -### JS -JS files from components are not imported in theme, they are only demonstrative. For theme we need to build JS files using RequireJS. -If you use ES6, you should use babel support, just add `.babel` in file name before `.js` extension, ex: [script for tabs](Magento_Theme/web/js/tab.babel.js) +### Alpaca features: +* Components system, build with fractal as a separate tool, on which you can work outside of Magento. You can customise it with variables or change and overwrite whole components. +* SVG icons - easily used also in CMS content +* Menu build with [Snowdog Module Menu](https://github.com/SnowdogApps/magento2-menu) +* Optimised images - responsive images, lazyloading, webp, and aspect ratio +* Customisable content with banners +* Sliders build with Blackbird Content type and slick slider. -### Sliders -Used lib: [slick slider](https://kenwheeler.github.io/slick/) -Magento Theme: One template for all sliders (theme-frontend-alpaca/Magento_Theme/templates/html/slider.phtml) -How to use: -1. If possible define block in xml: -``` - - - //required option with uniq name - - some_slider_name - +And much more. Check how to work with different features in [Working with Alpaca guide](./docs/working-with-alpaca.md) - //required option for sliders using content type `pictures` as slides - - some_picture_block_name - - - // optional option used to define slider variant - - some_class_name - - - // optional option used to define classes for slider title - - heading heading--first-level margin-0 - - - - // required block with name parameter same as defined in slider_block argument - - -``` -if not use: -``` -$sliderBlock = $this->getLayout() - ->createBlock("Magento\Framework\View\Element\Template") - ->setTemplate("Magento_Theme::html/slider.phtml"); -``` -2. Initialize "before-slides" block in .phtml file -``` -getSliderBlock(); // -$sliderBlockBefore->setData(['slider_html'=>'before-slides', ...]); -?> -toHtml(); ?> -``` - -"..." - additional config options: -``` -$sliderBlock->setData([ - 'slider_html' => 'before-slides', //required option - 'slider_class' => '', //optional slider class name - 'wrapper_class' => '', //optional slider wrapper class name - 'display_title' => '', //optional bool value - 'slider_title' => '', //optional slider title - 'title_class' => '', //optional slider title class name - 'content_before' => '', //optional content before slides - 'arrows' => '', //optional bool value - 'is_ajax' => '', //bool value - set to true when slides are loaded with ajax - - //below options are optional and described in: [https://kenwheeler.github.io/slick/#settings] - 'infinite' => '', //default true - 'mobile_first' => '', //default true - 'center_mode' => '', //default false - 'dots' => '', //default true - 'autoplay' => '', //default false - 'autoplay_speed' => '', //default 3000 - 'pause_on_focus' => '', //default true - 'pause_on_hover' => '', //default true - 'slides_to_show' => '', //default 1 - 'slides_to_scroll' => '', //default 1 - 'responsive_config' => '', //default false -]); -``` - -3. Render html for slides - -``` - $item) : ?> -
- ... -
- -``` - -4. Initialize "after-slides" block in .phtml file -``` -setData(['slider_html'=>'after-slides', ...]); -?> -toHtml(); ?> -``` - -5. Sliders created using Advanced Content Manager can be placed in any CMS content using Content Manager Content List widget. -Click on "Insert Widget..." button when editing CMS content with wysiwyg editor. Select "Content Manager Content List" as Widget Type. Set options: -"Content Type" -> "Sliders" -"Number of Contents to Display" -> 1 -"Template" -> "Slider Content List Template" -"Condition" -> Slider ID is "your-slider-id" -"Attributes to show" -> not required -Click on "Insert Widget" - -6. Full width variant - -To display slider full width, just add class `slider--full-with`, by extending block `home-slider` with argument `slider_class` in `cms_index_index.xml`. - -## Alpaca Content - Set up your store, admin / db changes for alpaca theme - -### Menu - to display menu use [Snowdog's magento2-menu](https://github.com/SnowdogApps/magento2-menu) module -1. Desktop menu: - * identifier: main-desktop - * Menu Main CSS Class: mega-menu -2. Mobile menu: - * identifier: main-mobile - * Menu Main CSS Class: dropdown-list -3. Footer links menu - * identifier: main-footer - * Menu Main Class: dropdown-list - - -You can use Alpaca styles implementation to use different configuration of menu items, by adding classes to nodes, check Alpaca components for details to build menu's adjusted to your project's needs, for example: to create a column, create node "wrapper" with Node CSS Classes: list__column list__column--hidden - -### Header & Footer CMS blocks - -We use CMS blocks to display some customizable content in header and footer. Check `vendor/snowdog/theme-frontend-alpaca/Magento_Theme/layout/default.xml` to see which CMS blocks are displayed by default. When creating these CMS blocks, you can use templates from `vendor/snowdog/theme-frontend-alpaca/Snowodg_Components` as a base for the HTML structure. - -### Homepage blocks - -Homepage content is built using static blocks. Check `vendor/snowdog/theme-frontend-alapca/Magento_Cms/layout/cms_index_index.xml` to see which CMS blocks are displayed by default. When creating these CMS blocks, you can use templates from `vendor/snowdog/theme-frontend-alpaca/Snowodg_Components` as a base for the HTML structure. - -### SVG icons in cms block: - -* {{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/svg-icon.phtml" icon="" icon_class="icon" title="" role="presentation" focusable="false"}} -* as `icon` value use icon id (Alpaca components) -* as `title` use accessible title that describe the icon image -* base class for icon is `icon` you can add, adjust class according to your needs -* a11y - use role="presentation" and focusable="false" if an icon is only decorative to hide in a11y API tree - -### Responsive images - -* to display responsive image for banners and slider items, we use: -* template `picture.phtml`: `vendor/snowdog/theme-frontend-alpaca/Magento_Theme/templates/html/picture.phtml` you can adjust it for your needs in the child theme. -* usage of phtml in cms block/page: -``` -{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img480="" img768="" img960="" img1024="" img1328="" img_full="" picture_class="image" picture_alt="" }} -``` -* by default you can use different image for media query breakpoints, you can also implement images with different device-pixel-ratio, check the template's code for details -* `picture_class` is a required attribute - -### Lazyloading images -We use [lazysizes](https://github.com/aFarkas/lazysizes) in project, so when you implement images with `` tag (ex. in CMS content), use: -* placeholder in `src` attribute: `data:image/gif;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAABCAQAAABN/Pf1AAAAC0lEQVR42mNkwAIAACoAAgu1Hc4AAAAASUVORK5CYII=` -* image url in `data-src` attribute -* `lazyload` class on `` tag - -This solution is already implemented on responsive solution in `picture.phtml` template - -### Preventing images from jumping on load -* to prevent jumping we need aspect ratio of image which we can calculate with formula: $aspectRatio = (imgHeight / imgWidth) * 100 -* usage for single image (with lazyloading): -``` -
- <descriptive alternative text for image> -
-``` -* usage for images added with picture.phtml. To work we need set `img_ratio_width` and `img_ratio_height`: -``` -{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img_default="cms/home/banners/my-file.jpg" picture_class="image" img_ratio_width="656" img_ratio_height="264"}} -``` -* aspect ratio for responsive images implemented using `picture.phtml`: -If responsive images - images for different viewports - have different aspect ratio than the default image, we should implement each of them: either in picture content type (if blackbird contentmanager is used), or in picture.phtml template. We need to add a unique `id` and `picture_class` attribute, which is required to make it works. -Use additional attributes for responsive aspect ratio: - `img_ratio_width_480` -> for image max-width 480px - `img_ratio_width_768` -> for image max-width 768px - `img_ratio_width_1024` -> for image max-width 1024px - `img_ratio_width_1328` -> for image min-width 1025px - -usage example: -``` -{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img_768="" img_1024="" img_full="" img_default="" picture_class="image" picture_alt="" img_ratio_width="1200" img_ratio_height="600" img_ratio_width_768="768" img_ratio_height_768="500" img_ratio_width_1024="472" img_ratio_height_1024="376" img_ratio_width_1328="1328" img_ratio_height_1328="1200" id=""}} -``` -!Important Note: -If responsive image aspect ratio is added, additional styles inline are generated, so use it ONLY if needed (if aspect ratio for responsive image is different that for default image) to keep your code as clean as possible. - -### Blog -* we use Blackbird Content Manager (paid extension) for blog - -### Shipping latency - snowdog/module-shipping-latency - -* is an extension to display additional information about shipping time -* Extension work on catalog and product detail page, to customise it you need to set attribute (dropdown) option and create cms block for popup content -* check [Shipping latency extension details](https://github.com/SnowdogApps/magento2-shipping-latency) and theme implementation in: `vendor/snowdog/theme-frontend-alpaca/Magento_Catalog/templates/product/list.phtml` (for catalog) and `vendor/snowdog/theme-frontend-alpaca/Magento_Catalog/templates/product/view/shipping-latency.phtml` (for product detail page) - -### Bullet points - snowdog/module-bullet-points -* Extension is used to display product attributes listed on product list item on catalog page -* check [Bullet points extension details](https://github.com/SnowdogApps/magento2-bullet-points) - -### Category attributes - snowdog/module-category-attributes -* it add a field for additional content on the bottom of catalog page -* check [Category attributes extension details](https://github.com/SnowdogApps/magento2-category-attributes) - -### Product attribute description - snowdog/module-product-attribute-description -* Extension allow to add additional description for attribute, implemented from admin level -* check [Product attribute description extension details](https://github.com/SnowdogApps/magento2-product-attribute-description) -* in theme is implemented on catalog level as an additional tooltip, check implementation: - * `vendor/snowdog/theme-frontend-alpaca/Smile_ElasticsuiteCatalog/templates/layer/filter/attribute.phtml` - * `vendor/snowdog/theme-frontend-alpaca/Magento_Swatches/templates/product/layered/renderer.phtml` (swatches) - * `vendor/snowdog/theme-frontend-alpaca/Smile_ElasticsuiteCatalog/templates/layer/filter/slider.phtml` (range filter) - -### Wishlist unlocker - snowdog/module-wishlist-unlocker -* This extension allow to show more than 3 items in sidebar wishlist (M2 default is 3) -* Limit value can be set in admin: Store -> COnfiguration -> Customer -> Wish List -> General option -> Items Limit -* check [Wishlist unlocker extension details](https://github.com/SnowdogApps/magento2-wishlist-unlocker) - -## Magepack -for Magento version < 2.3.6, mixins.js module patch is required/ [Patch provided and explained here](https://github.com/magento/baler/issues/23) - -Magepack is already integrated with [Frontools](https://github.com/SnowdogApps/magento2-frontools) - -### Generate magepack config -To start using magepack we need to generate magepack config. -Before start: -* clear Magento cache -* compile assest for production mode (in `/tools` directory): -``` -yarn styles --prod && yarn babel --prod && yarn svg -``` -* generate config with command (with appropriate path for each site): -``` -yarn magepackGenerate --cms-url="https://baseUrl/" --category-url="https://baseUrl/categoryPage" --product-url="https://baseUrl/productPage" -``` -Magepack config will be generated in `/tools` as `magepack.config.js` (which is a symlink to vendor/snowdog/frontools/magepack.config.js). -You can move this file to main repo or to other location, add this to `.gitignore` and commit changes. - -With commited magepack config, during deployment, after assets compilation, run magepack bundling: -``` -yarn magepackBundle --config -``` - -### Add assets -* If you added fonts or external assets that can be load with `preload`, add them in: -`vendor/snowdog/theme-frontend-alpaca/Magento_Theme/templates/root.phtml` with `preload` attribute. - -* if assets come from external module which is not always enable, add preload assets in following way: -in module folder inside theme: - * using xml layout add block in `head.additional` and in custom template add assets: - ``` - - ``` - an example can be found here: `vendor/snowdog/theme-frontend-alpaca/Amasty_GdprCookie` +## Installation +Check [Alpaca installation step by step guide](./docs/alpaca-step-by-step.md) -### Test magepack locally +## Alpaca preview -To test magepack locally: -* clear and enable cache, -* enable merging, minifying and magepack budnling in your db: -``` -bin/magento config:set dev/js/enable_magepack_js_bundling 1 -bin/magento config:set dev/js/merge_files 1 -bin/magento config:set dev/js/minify_files 1 -bin/magento config:set dev/css/minify_files 1 -bin/magento config:set dev/css/merge_css_files 1 -``` -* run tools compilation for production: -``` -yarn styles --prod && yarn babel --prod && yarn svg -``` -* generate magepack config: -yarn magepackGenerate .. +* [Alpaca components preview](https://magento2-alpaca-theme-git-master-snowdog1.vercel.app/) +* [Alpaca theme on Magento 2 Community](https://alpaca-community.snowdog.dev/) +* [Alpaca theme on Magento 2 Commerce](https://alpaca-commerce.snowdog.dev/) -* switch to production mode: -``` -bin/magento deploy:mode:set production -``` -* bundle magepack -in `/tools` -``` -yarn magepackBundle --config -``` -* clear cache -* check results in browser diff --git a/Snowdog_Components/README.md b/Snowdog_Components/README.md index eeffec0f9..9b09438a4 100644 --- a/Snowdog_Components/README.md +++ b/Snowdog_Components/README.md @@ -9,7 +9,7 @@ It's separate npm package, created based on [Alpaca Components](https://github.c Magento 2 experience is not required to work with this code. ## Requirements -- node version >=12.13.0 <13.0.0 installed globally +- node version >=16 <17.0.0 installed globally - npm or yarn installed globally ## Installation @@ -22,20 +22,7 @@ Magento 2 experience is not required to work with this code. 2. Update project name in `package.json` and `gulpfile.js` -3. Copy `styles.scss` from `theme-frontend-alpaca/Snowdog_Components/docs/styles/` and add child project variables import there. -The file should look like this: - -```scss -// Variables -@import '../../components/Atoms/variables/variables'; -@import '../../components/Atoms/variables/-variables'; - -// Components -@import '../../components/styles'; - -// Styles necessary only for Fractal purposes -@import 'fractal'; -``` +3. Copy `styles.scss` and `checkout.scss` from `theme-frontend-alpaca/Snowdog_Components/docs/styles/` and add child project variables import there. 4. Create `modules.mjs` file with an array of paths to parent components libraries. To inherit dependencies from Alpaca components, you have to define path to `theme-forntend-alpaca/Snowdog_Components`. In most cases, inside Magento, it will look like this: @@ -46,6 +33,8 @@ The file should look like this: ``` 5. Customize or add new files following the same structure as in Alpaca components +6. Components imports are located in files in: `vendor/snowdog/theme-frontend-alpaca/Snowdog_Components/components/styles`, copy appropriate file(s) from there in your child theme to import extended or new component(s) + 6. Run `yarn` and `yarn dev` to run components in fractal.build. :tada: ## Directory structure diff --git a/docs/alpaca-step-by-step.md b/docs/alpaca-step-by-step.md index ff22bb307..191650228 100644 --- a/docs/alpaca-step-by-step.md +++ b/docs/alpaca-step-by-step.md @@ -22,10 +22,18 @@ More info: [alpaca boilerplate npm project page](#to-do-here) ## Requirements * Working Magento 2.4 project -* Node ver 16 +* Node version 16 +* [yarn](https://yarnpkg.com/) (we recommended yarn but you can also use npm to install dependencies and run node command). ## Alpaca versions -// TO DO - information about Alpaca Version for Magento OS versions +This guide is adjusted to the latest version of Alpaca theme: ^2.26 and work with Magento 2.4.3 +If you work with older Magento version, use appropriate Alpaca Theme: +* Alpaca 2.14.0 supports Magento 2.4.2 +* Alpaca 2.13.0 supports Magento 2.4.1 +* Alpaca 2.12.* supports Magento 2.3.6 + +Check [Changelog file](../CHANGELOG.md) for more details
. + ## Set up Alpaca Theme When using **Valet Plus** run commands in main project directory, with **Warden** remember to launch shell session see [Warden usage and common commands](https://docs.warden.dev/usage.html) @@ -51,13 +59,56 @@ More info: [alpaca boilerplate npm project page](#to-do-here) ``` bin/magento setup:upgrade ``` -6. Go to `vendor/snowdog/frontools` and run commands: +6. Setup frontools + * in `/` create files: + `theme.json`: + ```json + { + "alpaca": { + "src": "vendor/snowdog/theme-frontend-alpaca", + "dest": "pub/static/frontend/Snowdog/alpaca", + "locale": ["en_US"], + "ignore": [ + "**/node_modules/**", + "**/Snowdog_Components/docs/**", + "**/Snowdog_Components/build/**" + ] + } + } + ``` + + `browser-sync.json`, adjust file for your local domain: + ```json + [ + { + "proxy": ".test", + "rewriteRules": [ + { + "match": "..test", + "replace": "" + } + ] + }, + { + "proxy": "b2b..test", + "rewriteRules": [ + { + "match": ".b2b..test", + "replace": "" + } + ] + } + ] + ``` + + * Go to `vendor/snowdog/frontools` and run commands: ```` - yarn install + yarn yarn setup yarn styles && yarn svg && yarn babel ```` Setting up frontools creates symlinks. After set up, `yarn` commands are available from `/tools`
+ 7. Log in to admin panel. - You can find admin page URL in `app/etc/env.php` file in `backend` section (`frontName` parameter) - You can create new admin user by using magento CLI: @@ -76,13 +127,13 @@ More info: [alpaca boilerplate npm project page](#to-do-here)

Congrats! You've installed Alpaca Theme successfully!
-To create your own child theme see instructions below: +To create your own child theme, see the instruction below: ## Set up Alpaca Child Theme After installing Alpaca theme, you can create child theme based on Alpaca Theme as a separate composer package (in `vendor` directory) or in `app/design/frontend` directory. In this guide, we will create it in `app/design/frontend`. -1. Go to `app/design/frontend` and create directories with your Vendor name and with your theme name: `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME`, example: `app/design/frontend/Snowdog/alpaca-child` -2. Create configuration theme files: +1. Go to `app/design/frontend` and create directories with your Vendor name and with you theme name: `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME`, example: `app/design/frontend/Snowdog/alpaca-child` +2. Create configuration theme's files: Inside `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME`, create `registration.php` and `theme.xml` files. * `registration.php`: @@ -121,13 +172,13 @@ You can create also `README.md` and `CHANGELOG.md` files. 4. Adjust styles inheritance in child theme: ### Add basic styles and child theme variables: In components: - * `app/design/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components/components/Atoms/variables/_CHILD_THEME_NAME-variables.scss` - child theme variables, where you can create basic variables for a child theme or overwrite those from `vendor/snowdog/theme-frontend-alpaca/Snowdog_Components/components/Atoms/variables/_variables.scss` - change assigned value without `!default`) + * `app/design/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components/components/Atoms/variables/_CHILD_THEME_NAME-variables.scss` - child theme variables, where you can create basic variables for a child theme or overwrite those from `vendor/snowdog/theme-frontend-alpaca/Snowdog_Components/components/Atoms/variables/_variables.scss` - change assigned value without `!default` * `app/design/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components/docs/styles/styles.scss`: ```scss // Variables @import '../../components/Atoms/variables/variables'; - // Child theme variables + // Child theme variables (imported after alpaca variables) @import "../../components/Atoms/variables/CHILD_THEME_NAME-variables"; // Components @@ -300,7 +351,7 @@ More details about styles in Alpaca Theme & components and theits inheritance, y * `gulpfile.mjs` * `package.json` -2) in `package.json` and `gulpfile.mjs` replace Alpaca name to `CHILD_THEME_NAME` +2) in `package.json` and `gulpfile.mjs` replace `Alpaca` name to `CHILD_THEME_NAME` 3) Set inheritance from Alpaca component by creating `modules.mjs` file with following content: ```mjs export default [ @@ -311,7 +362,7 @@ export default [ 5) run `yarn dev` to work with components in dev mode. 6. Create frontools config file to compile theme static assets: -Go to `dev/tools/frontools/themes.json` and add your theme: +Go to `dev/tools/frontools/themes.json` and add or adjust your theme: ```json { "alpaca": { @@ -364,7 +415,6 @@ Go to `dev/tools/frontools/themes.json` and add your theme: 12. Flush cache storage. ## Useful Links - * [Alpaca Theme details](https://github.com/SnowdogApps/magento2-alpaca-theme) * [Snowdog Frontools](https://github.com/SnowdogApps/magento2-frontools) * [Valet Plus](https://github.com/weprovide/valet-plus/wiki/Database) * [Fractal guide](https://fractal.build/guide/) diff --git a/docs/magento-setup-guide.md b/docs/magento-setup-guide.md index 07fafcb09..d9bf2edbb 100644 --- a/docs/magento-setup-guide.md +++ b/docs/magento-setup-guide.md @@ -41,6 +41,7 @@ Valet+ is a development environment for macOS. It doesn't use Vagrant or Docker ``` * See Valet Plus [database documentation.](https://github.com/weprovide/valet-plus/wiki/Database) 3. Configure database for Magento. Go to main directory of your project and run: +(adjust `project-name`) ````sh bin/magento setup:install --db-host="127.0.0.1" \ --db-name="db-name" \ @@ -56,17 +57,11 @@ Valet+ is a development environment for macOS. It doesn't use Vagrant or Docker Adjust options: * `db` fields - name, password and root * Your project local URL and your admin credentials -4. Create `env` file: - * To work with custom database you'll need `env.php` file located in `app/etc`. [Read magento docs](https://devdocs.magento.com/guides/v2.4/config-guide/prod/config-reference-envphp.html) to see it's structure. - * Valet Plus allows you to run command that will create `env.php` file for you: - ``` - valet configure - ``` -5. Go to `app/etc/env.php` to check that all fields are properly set. +4. Go to `app/etc/env.php` to check that all fields are properly set. * Set `frontName` to `admin`. - * Example - `'frontName' => 'admin'` will result in `yourpage.test/admin` as your admin panel URL. + * Example - `'frontName' => 'admin'` will result in `project-name.test/admin` as your admin panel URL. * Make sure that database fields are the same as you set in step 2. - * Set rest of the fields according to your own needs. + * Adjust rest of the fields according to your own needs. * See example `env.php` file below: ```php @@ -196,7 +200,7 @@ See [Warden Magento 2 docs.](https://docs.warden.dev/environments/magento2.html) composer create-project --repository-url=https://repo.magento.com/ magento/project-community-edition ``` Change `` to name of folder in which you wish to install your Magento project. -2. Inside project directory run +2. Inside project directory run (adjust project-name): ``` warden env-init project-name magento2 ``` @@ -222,6 +226,40 @@ See [Warden Magento 2 docs.](https://docs.warden.dev/environments/magento2.html) 'enable_http_auth' => 0 ] ], + 'dev' => [ + 'js' => [ + 'merge_files' => 0, + 'enable_js_bundling' => 0, + 'minify_files' => 0 + ], + 'css' => [ + 'merge_css_files' => 0, + 'minify_files' => 0 + ], + 'static' => [ + 'sign' => '0' + ] + ], + 'web' => [ + 'cookie' => [ + 'cookie_domain' => 'project-name.test' + ], + 'unsecure' => [ + 'base_url' => 'https://project-name.test/', + 'base_link_url' => 'https://project-name.test/', + 'base_static_url' => 'https://project-name.test/static/', + 'base_media_url' => 'https://project-name.test/media/' + ], + 'secure' => [ + 'base_url' => 'https://project-name.test/', + 'base_link_url' => 'https://project-name.test/', + 'base_static_url' => 'https://project-name.test/static/', + 'base_media_url' => 'https://project-name.test/media/' + ], + 'seo' => [ + 'use_rewrites' => '1' + ] + ] ] ], 'crypt' => [ @@ -348,7 +386,7 @@ See [Warden Magento 2 docs.](https://docs.warden.dev/environments/magento2.html) defaultFileMode: "0644" defaultDirectoryMode: "0755" ``` -5. Set up SSL and start project environment +5. Set up SSL and start project environment (adjust url): ``` warden sign-certificate project-name.test warden env up diff --git a/docs/working-with-alpaca.md b/docs/working-with-alpaca.md index bdf01420a..08a8a4345 100644 --- a/docs/working-with-alpaca.md +++ b/docs/working-with-alpaca.md @@ -1,5 +1,417 @@ -// TO DO -Move majority of content from [README.md](../README.md) here. +# Working with Alpaca -Use (refactor if needed) this guide: - To learn how to work with Alpaca Theme see [working with Alpaca Theme.](https://lab.snowdog.pro/patrykbura/alpaca-boilerplate/-/tree/feature/80366#working-with-alpaca-theme) +You'll find here information how to work with different features of Alpaca Theme. +For installation details, check [Step by step Alpaca installation guide](./alpaca-step-by-step.md) + +## Table of Contents + * [Requirements](#requirements) + * [Frontools](#frontools) + * [Components](#components) + * [Customisation of Alpaca Components](#alpaca-components-customisation) + * [Customising theme files](#customising-theme-files) + * [Styles](#styles) + * [JS](#js) + * [Images](#images) + * [Responsive images](#responsive-images) + * [Lazyloading images](#lazyloading-images) + * [Preventing images from jumping on load](#preventing-images-from-jumping-on-load) + * [SVG icons](#svg-icons) + * [Sliders](#sliders) + * [Header and Footer](#header-and-footer) + * [Homepage](#homepage) + * [Working with Snowdog Modules](#working-with-snowdog-modules) + * [Magepack](#magepack) + +## Requirements +* Working Magento 2.4.3 +* Node version 16 +* [yarn](https://yarnpkg.com/) (we recommended yarn but you can also use npm to install dependencies and run node command). + +## Frontools + Set of front-end tools for Magento 2. Run commands below in `tools`. + - When developing run comand below to watch for style changes and running processing tasks: + ```` + yarn watch + ```` + - You can also use `yarn dev` to run [browserSync](https://browsersync.io/) and inheritance, babel, styles, watch tasks. + ```` + yarn dev + ```` + **NOTE!** To run `yarn dev`, set correct proxy values in file - `dev/tools/frontools/config/browser-sync.json` + - After every application upgrade (`bin/magento setup:upgrade` command) run: + ```` + yarn styles && yarn svg && yarn babel + ```` + - Config files are kept in `dev/tools/frontools/config`. + - `themes.json` file is essential. It needs to be set properly, without it frontools won't work. See [themes.json example.](https://github.com/SnowdogApps/magento2-frontools/blob/master/config/themes.json.sample) + - Setting up frontools creates symlink, after set up, `yarn` commands are available from `/tools` + - To learn how to fully utilize frontools see [frontools readme.md](https://github.com/SnowdogApps/magento2-frontools#magento-2-frontools) + +## Components + * `theme-frontend-alpaca/Snowdog_Components` it's separate [fractal.build](https://fractal.build/guide/) tool integrated with Alpaca Theme, which allows you to work with Magento UI styles easier and faster. It is not set as a separate composer package (neither separate git repository) to work with Magento theme easier and faster. But you can work on components separately and run them outside of Magento. + * Check it out, go to **Snowdog_Components** (`app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components`), install node dependencies and run dev command: + ```` + yarn + yarn dev + ```` + * Go to `http://localhost:4000/` to play with components. To learn how to change components, **read section below**. + * Component styles in Alpaca follow [Atomic Design Methodology](https://atomicdesign.bradfrost.com/chapter-2/). Components are divided into Atomic groups, that is: + * Atoms + * Molecules + * Organisms + * Templates
+ * Styles written in fractal components are used in Magento theme. JS scripts and hbs templates are only for fractal purpose and they are not used inside Magento theme. + * Check full styles structure in `vendor/snowdog/theme-frontend-alpaca/Snowdog_Components` + * **NOTE!** Detailled instruction how to set child theme inherited from Alapca theme you can find in out [Step by step Alpaca installation guide](./alpaca-step-by-step.md) +## Alpaca Components customisation + - Customising components with variables + * You can overwrite any of Alpaca Components variabales in child theme in + `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components/components/Atoms/variables/_CHILD_THEME_NAME-variables.scss` + * Child theme variables should be imported after Alpaca variables. Use values without `!default` to change variables declared in Alpaca theme or create new variables for your needs. + * You can customise your styles by changing variables values - global or components variables), extending styles by using Alpaca's and custom and overwrite styles by creating totally new styles for components. + * For Components, we use 2 create 2 main `.scss` files in `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components/docs/styles/`: + * `styles.scss` + * `checkout.scss` + * Main `.scss` files are required in child components to use custom child theme's variables. + - Customising components + * Customize or add new files following the same structure as in Alpaca Components. + Create file `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components/components/Molecules/button/_button-extend.scss` + ```scss + @import 'CHILD_THEME_NAME-button-variables'; // optional; + @import 'button'; + @import 'CHILD_THEME_NAME-button'; + ``` + Inside `button-extend.scss`, `CHILD_THEME_NAME-button-variables` is a file where you change component's variable, `button` is an original Alpaca Component style and `CHILD_THEME_NAME-button` contains additional or overwritten by child theme styles.
+ * you need to import extended component, to do it, copy file(s) from `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/Snowdog_Components/components/styles` and change `@import '../Molecules/button/button';` to `@import '../Molecules/button/button-extend';` + * You can overwrite any component in your child theme by maintaining the same file structure (`.hbs`, `config.js`, `.scss`). + * Read more about Alpaca components [here](https://github.com/SnowdogApps/magento2-alpaca-theme/blob/master/Snowdog_Components/README.md) +## Customising theme files + * To customise layout `XML` files and template `.phtml` files, follow Magento theme inheritance [standard.](https://devdocs.magento.com/guides/v2.3/frontend-dev-guide/themes/theme-inherit.html) + * Rememeber that: + * Templates have to be overwritten in child theme + * Layouts can be extended from parent theme, so there is no need for copying and overwriting file. Add, remove, change what you need. +## Styles +Are was mentionned before, Styles in Alpaca are separated: +* Components styles inside `theme-frontend-alpaca/Snowdog_Components` to work with components directly.
+ +Those styles are also imported inside the theme in `theme-frontend-alpaca/styles/` directory +* For Magento we need to create 3 main `.scss` files inside child theme: + * `styles.scss` in `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/styles/styles.scss` where components and theme styles are imported. And where child theme variable are imported after Alpaca variables + * `critical.scss` in `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/styles/critical.scss` to load basic critical styles for page loading. + * `critical-checkout.scss` in `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/styles/critical-checkout.scss` to load basic critical styles for checkout page loading. + * `gallery-styles.scss` in `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/styles/gallery-styles.scss` to load styles for fotorama gallery. + * `checkout.scss` in `app/design/frontend/VENDOR_NAME/CHILD_THEME_NAME/Magento_Checkout/styles/checkout.scss` where components and checkout styles are imported + +* During styles compilation for theme, following directories are ignored: +``` +"**/node_modules/**", +"**/Snowdog_Components/docs/**", +"**/Snowdog_Components/build/**" +``` +It should be added in `themes.json` in [frontools config](#https://github.com/SnowdogApps/magento2-frontools/blob/master/config/themes.json.sample) as ignores files + +## JS +* JS files from components are not imported in theme, they are only demonstrative. For theme we need to build JS files using RequireJS. +* If you use ES6 in theme's js files, you should use babel support, just add `.babel` in file name before `.js` extension, example: [script for tabs](../Magento_Theme/web/js/tab.babel.js) and run `yarn babel` with frontools + +## Images +### Responsive images + +* to display responsive image for banners and slider items, we use: +* template `picture.phtml`: `vendor/snowdog/theme-frontend-alpaca/Magento_Theme/templates/html/picture.phtml` you can adjust it for your needs in the child theme. +* usage of phtml in cms block/page: +``` +{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img480="" img768="" img960="" img1024="" img1328="" img_full="" picture_class="image" picture_alt="" }} +``` +* by default you can use different image for media query breakpoints, you can also implement images with different device-pixel-ratio, check the template's code for details +* `picture_class` is a required attribute + +## Lazyloading images +We use [lazysizes](https://github.com/aFarkas/lazysizes) in project, so when you implement images with `` tag (ex. in CMS content), use: +* placeholder in `src` attribute: `data:image/gif;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAABCAQAAABN/Pf1AAAAC0lEQVR42mNkwAIAACoAAgu1Hc4AAAAASUVORK5CYII=` +* image url in `data-src` attribute +* `lazyload` class on `` tag + +This solution is already implemented on responsive solution in `picture.phtml` template + +## Preventing images from jumping on load +* to prevent jumping we need aspect ratio of image which we can calculate with formula: $aspectRatio = (imgHeight / imgWidth) * 100 +* usage for single image (with lazyloading): +``` +
+ <descriptive alternative text for image> +
+``` +* usage for images added with picture.phtml. To work we need set `img_ratio_width` and `img_ratio_height`: +``` +{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img_default="cms/home/banners/my-file.jpg" picture_class="image" img_ratio_width="656" img_ratio_height="264"}} +``` +* aspect ratio for responsive images implemented using `picture.phtml`: +If responsive images - images for different viewports - have different aspect ratio than the default image, we should implement each of them: either in picture content type (if blackbird contentmanager is used), or in picture.phtml template. We need to add a unique `id` and `picture_class` attribute, which is required to make it works. +Use additional attributes for responsive aspect ratio: + `img_ratio_width_480` -> for image max-width 480px + `img_ratio_width_768` -> for image max-width 768px + `img_ratio_width_1024` -> for image max-width 1024px + `img_ratio_width_1328` -> for image min-width 1025px + +usage example: +``` +{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img_768="" img_1024="" img_full="" img_default="" picture_class="image" picture_alt="" img_ratio_width="1200" img_ratio_height="600" img_ratio_width_768="768" img_ratio_height_768="500" img_ratio_width_1024="472" img_ratio_height_1024="376" img_ratio_width_1328="1328" img_ratio_height_1328="1200" id=""}} +``` +!Important Note: +If responsive image aspect ratio is added, additional styles inline are generated, so use it ONLY if needed (if aspect ratio for responsive image is different that for default image) to keep your code as clean as possible. + +## SVG icons + +* {{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/svg-icon.phtml" icon="" icon_class="icon" title="" role="presentation" focusable="false"}} +* as `icon` value use icon id (Alpaca components) +* as `title` use accessible title that describe the icon image +* base class for icon is `icon` you can add, adjust class according to your needs +* a11y - use role="presentation" and focusable="false" if an icon is only decorative to hide in a11y API tree +## Sliders +Sliders in Alpaca re build with `blackbird/contentmanager` extension
+* There is one template for all sliders. You can find it in [Magento_Theme/templates/html/slider.phtml](../Magento_Theme/templates/html/slider.phtml). It is based on [slick slider](https://kenwheeler.github.io/slick/).
+How to use: +1. If possible define block in xml: +``` + + + //required option with uniq name + + some_slider_name + + + //required option for sliders using content type `pictures` as slides + + some_picture_block_name + + + // optional option used to define slider variant + + some_class_name + + + // optional option used to define classes for slider title + + heading heading--first-level margin-0 + + + + // required block with name parameter same as defined in slider_block argument + + +``` +if not use: +``` +$sliderBlock = $this->getLayout() + ->createBlock("Magento\Framework\View\Element\Template") + ->setTemplate("Magento_Theme::html/slider.phtml"); +``` +2. Initialize "before-slides" block in .phtml file +``` +getSliderBlock(); // +$sliderBlockBefore->setData(['slider_html'=>'before-slides', ...]); +?> +toHtml(); ?> +``` + +"..." - additional config options: +``` +$sliderBlock->setData([ + 'slider_html' => 'before-slides', //required option + 'slider_class' => '', //optional slider class name + 'wrapper_class' => '', //optional slider wrapper class name + 'display_title' => '', //optional bool value + 'slider_title' => '', //optional slider title + 'title_class' => '', //optional slider title class name + 'content_before' => '', //optional content before slides + 'arrows' => '', //optional bool value + 'is_ajax' => '', //bool value - set to true when slides are loaded with ajax + + //below options are optional and described in: [https://kenwheeler.github.io/slick/#settings] + 'infinite' => '', //default true + 'mobile_first' => '', //default true + 'center_mode' => '', //default false + 'dots' => '', //default true + 'autoplay' => '', //default false + 'autoplay_speed' => '', //default 3000 + 'pause_on_focus' => '', //default true + 'pause_on_hover' => '', //default true + 'slides_to_show' => '', //default 1 + 'slides_to_scroll' => '', //default 1 + 'responsive_config' => '', //default false +]); +``` + +3. Render html for slides + +``` + $item) : ?> +
+ ... +
+ +``` + +4. Initialize "after-slides" block in .phtml file +``` +setData(['slider_html'=>'after-slides', ...]); +?> +toHtml(); ?> +``` + +5. Sliders created using Advanced Content Manager can be placed in any CMS content using Content Manager Content List widget. +Click on "Insert Widget..." button when editing CMS content with wysiwyg editor. Select "Content Manager Content List" as Widget Type. Set options: +"Content Type" -> "Sliders" +"Number of Contents to Display" -> 1 +"Template" -> "Slider Content List Template" +"Condition" -> Slider ID is "your-slider-id" +"Attributes to show" -> not required +Click on "Insert Widget" + +6. Full width variant + +To display slider full width, just add class `slider--full-with`, by extending block `home-slider` with argument `slider_class` in `cms_index_index.xml`. + +## Header and Footer + * To display and customise content in header or footer we use CMS block ([read more](https://docs.magento.com/user-guide/cms/blocks.html)) + * See default structure - `vendor/snowdog/theme-frontend-alpaca/Magento_Theme/layout/default.xml`. +## Homepage + * To display homepage content we use static blocks. + * See default structure - `vendor/snowdog/theme-frontend-alpaca/Magento_Cms/layout/cms_index_index.xml` + +## Working with Snowdog Modules + Snowdog Modules is a set of open source modules used with Alpaca Theme installed via [Magento 2 Alpaca Packages](https://github.com/SnowdogApps/magento2-alpaca-packages). You can find list of installed modules in [README description](../README.md#description) section. + + ### Magento2 menu - snowdog/magento2-menu + * Provides powerful menu editor to replace category based menus in Magento 2. + * Displays desktop menu, mobile menu or footer links menu + * You can use Alpaca styles implementation to use different configuration of menu items, by adding classes to nodes, check Alpaca components for details to build menu's adjusted to your project's needs, for example: to create a column, create node "wrapper" with Node CSS Classes: list__column list__column--hidden + * Example data can be imported [with alpaca db queries](https://github.com/SnowdogApps/create-alpaca-theme/blob/master/templates/database/queries.sql)). + * See [Magento 2 menu details](https://github.com/SnowdogApps/magento2-menu). + ### Shipping latency - snowdog/module-shipping-latency + * It is an extension allowing to display additional informations about shipping time + * Extension work on catalog and product detail page, to customise it you need to set attribute (dropdown) option and create cms block for popup content + * See [Shipping latency module details](https://github.com/SnowdogApps/magento2-shipping-latency). + * [Theme implementation for catalog](../Magento_Catalog/templates/product/list.phtml) + * [Theme implementation for PDP](../Magento_Catalog/templates/product/view/shipping-latency.phtml) + + ### Bullet points - snowdog/module-bullet-points + * Extension is used to display product attributes listed on product list item on catalog page + * See [Bullet points module details](https://github.com/SnowdogApps/magento2-bullet-points). + + ### Category attributes - snowdog/module-category-attributes + * This extension adds a field for additional content on the bottom of catalog page + * See [Category attributes module details](https://github.com/SnowdogApps/magento2-category-attributes). + + ### Product attribute description - snowdog/module-product-attribute-description + * This extension allows to add additional description for attribute, implemented from admin level + * See [Product attribute description module details](https://github.com/SnowdogApps/magento2-product-attribute-description). + * [theme implementation on catalog level as an additional tooltip](../Smile_ElasticsuiteCatalog/templates/layer/filter/attribute.phtml) + * [theme implementation in swatches](../Magento_Swatches/templates/product/layered/renderer.phtml) + * [theme implementation in range filter](../Smile_ElasticsuiteCatalog/templates/layer/filter/slider.phtml) + ### Wishlist unlocker - snowdog/module-wishlist-unlocker + * This extension allows to show more than 3 items in sidebar wishlist (M2 default is 3) + * Limit value can be set in admin: `Store -> Configuration -> Customer -> Wish List -> General Option -> Items Limit` + * See [Wishlist unlocker description module details](https://github.com/SnowdogApps/magento2-wishlist-unlocker). + +## Blog +* we use Blackbird Content Manager `blackbird/contentmanager` for blog + +## Magepack +for Magento version < 2.3.6, mixins.js module patch is required/ [Patch provided and explained here](https://github.com/magento/baler/issues/23) + +Magepack is already integrated with [Frontools](https://github.com/SnowdogApps/magento2-frontools) + +### Generate magepack config +To start using magepack we need to generate magepack config. +Before start: +* clear Magento cache +* compile assest for production mode (in `/tools` directory): +``` +yarn styles --prod && yarn babel --prod && yarn svg +``` +* generate config with command (with appropriate path for each site): +``` +yarn magepackGenerate --cms-url="https://baseUrl/" --category-url="https://baseUrl/categoryPage" --product-url="https://baseUrl/productPage" +``` +Magepack config will be generated in `/tools` as `magepack.config.js` (which is a symlink to vendor/snowdog/frontools/magepack.config.js). +You can move this file to main repo or to other location, add this to `.gitignore` and commit changes. + +With commited magepack config, during deployment, after assets compilation, run magepack bundling: +``` +yarn magepackBundle --config +``` + +### Add assets +* If you added fonts or external assets that can be load with `preload`, add them in: +`vendor/snowdog/theme-frontend-alpaca/Magento_Theme/templates/root.phtml` with `preload` attribute. + +* if assets come from external module which is not always enable, add preload assets in following way: +in module folder inside theme: + * using xml layout add block in `head.additional` and in custom template add assets: + ``` + + ``` + an example can be found here: `vendor/snowdog/theme-frontend-alpaca/Amasty_GdprCookie` + +### Test magepack locally + +To test magepack locally: +* clear and enable cache, +* enable merging, minifying and magepack budnling in your db: +``` +bin/magento config:set dev/js/enable_magepack_js_bundling 1 +bin/magento config:set dev/js/merge_files 1 +bin/magento config:set dev/js/minify_files 1 +bin/magento config:set dev/css/minify_files 1 +bin/magento config:set dev/css/merge_css_files 1 +``` +* run tools compilation for production: +``` +yarn styles --prod && yarn babel --prod && yarn svg +``` +* generate magepack config: +yarn magepackGenerate .. + +* switch to production mode: +``` +bin/magento deploy:mode:set production +``` +* bundle magepack +in `/tools` +``` +yarn magepackBundle --config +``` +* clear cache +* check results in browser