Type
magento2-theme
Alpaca frontend theme for Magento 2
magento2-theme
MIT
None
None
None
None
None
2.26.0
version includes a lot of changes and has different files structure, please go to Migration Guide for more informations
Alpaca Theme for Magento 2 is part of a alpaca-packages
To make it work with all features, we use following modules:
Open source * magepal/magento2-gmailsmtpapp * magepal/magento2-googletagmanager * mailchimp/mc-magento2 * smile/elasticsuite * snowdog/module-alpaca-general * snowdog/module-bullet-points * snowdog/module-csp * snowdog/module-category-attributes * snowdog/module-menu * snowdog/module-product-attribute-description * snowdog/module-shipping-latency * snowdog/module-wishlist-unlocker * webshopapps/module-matrixrate
Alpaca supports also following OS modules:
* paradoxlabs/authnetcim
* paradoxlabs/tokenbase
* authorizenet/magento-module-creditcard
* snowdog/module-alpaca-acm - alpaca customisation for paid blackbird/contentmanager
extension
Additional, non-opensource modules the theme works with to cover additional features: * amasty/adminactionslog * amasty/module-gdpr * amasty/module-gift-card * amasty/module-google-rich-snippets * amasty/module-product-feed * amasty/module-shipping-rules * amasty/module-special-promo * amasty/module-store-locator * amasty/payrestriction * amasty/shiprestriction * apptrian/facebook-pixel * blackbird/contentmanager * vladimirpopov/webforms
Install whole package using composer:
composer require snowdog/module-alpaca-packages
Install snowdog/frontools:
composer require snowdog/frontools
Node.js LTS version. We recommend using Volta.
Create child theme composer repository:
theme.xml
, registration.php
, preview.jpg
, .gitignore
, composer.json
composer.json
example file:{
"name": "vendor/theme-frontend-child-theme",
"description": "Child frontend theme",
"type": "magento2-theme",
"require": {
"snowdog/theme-frontend-alpaca": "<latest-version>",
"vendor/module-child-theme-frontools": "<latest-version>"
},
"autoload": {
"files": [
"registration.php"
]
}
}
theme.xml
set Alpaca theme as a parent: <parent>Snowdog/alpaca</parent>
styles/styles.scss
// Component variables
@import '../Snowdog_Components/components/Atoms/variables/variables';
@import '../Snowdog_Components/components/Atoms/variables/<child-theme>-variables';
// Components
@import '../Snowdog_Components/components/styles';
// Theme styles
@import 'theme';
Snowdog_Components/components/Atoms/variables/_<child-theme>-variables.scss
to overwrite globals variables which you needCreate separate module with frontools configuration (it should be required in theme composer dependencies).
Example: vendor/module-child-theme-frontools
.
+--config
| +--browser-sync.json
| +--themes.json
+--composer.json
config/browser-sync.json
:Basic configuration for browsersync (set path for project's local url):
{
"proxy": "child-theme.test",
"rewriteRules": [
{
"match": ".child-theme.test",
"replace": ""
}
]
}
config/themes.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.
{
"name": "vendor/module-child-theme-frontools",
"type": "magento2-component",
"require": {
"snowdog/frontools": "^1.8.0"
},
"extra": {
"map": [
[
"config",
"dev/tools/frontools/config"
]
]
}
}
composer require vendor/theme-frontend-child-theme
theme-frontend-alpaca/Snowdog_Components
it's separate fractal.build 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.
Copy-paste package.json
, gulpfile.js
, .eslintignore
, .eslintrc
, .sass-lint.yml
, .stylelintrc
files into theme-frontend-<child-theme>/Snowdog_Components
:
Update project names in package.json
and gulpfile.js
Copy styles.scss
and checkout.scss
from theme-frontend-alpaca/Snowdog_Components/docs/styles/
and add child project variables import there.
Your styles.scss
:
// Variables
@import '../../components/Atoms/variables/variables';
@import '../../components/Atoms/variables/<child-theme>-variables';
// Components
@import '../../components/styles';
// Styles necessary only for Fractal purposes
@import 'fractal';
Your checkout.scss
:
// Variables
@import '../../components/Atoms/variables/variables';
@import '../../components/Atoms/variables/<child-theme>-variables';
// Components
@import '../../components/checkout';
// Styles necessary only for Fractal purposes
@import 'fractal';
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"
]
Customize or add new files following the same structure as in Alpaca components
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.
Snowdog_Components/components/Atoms/variables/_<child-theme>-variables.scss
).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
.hbs
, .config.js
, .scss
)More about working with Alpaca Components directly in components' README.md
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
Those styles are also imported inside the theme in main styles file Additionally, inside components, we have separated styles for checkout.
"**/node_modules/**",
"**/Snowdog_Components/docs/**",
"**/Snowdog_Components/build/**"
It should be added in themes.json
in frontools config as ignores files
* Inside theme, we have main styles file and separate styles for gallery and for checkout
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
Used lib: slick slider 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:
<referenceBlock name="some_block_name">
<arguments>
//required option with uniq name
<argument
name="slider_block"
xsi:type="string"
>
some_slider_name
</argument>
//required option for sliders using content type `pictures` as slides
<argument
name="slider_picture_block"
xsi:type="string"
>
some_picture_block_name
</argument>
// optional option used to define slider variant
<argument
name="slider_class"
xsi:type="string"
>
some_class_name
</argument>
// optional option used to define classes for slider title
<argument
name="slider_title_class"
xsi:type="string"
>
heading heading--first-level margin-0
</argument>
</arguments>
// required block with name parameter same as defined in slider_block argument
<block
class="Magento\Framework\View\Element\Template"
name="some_slider_name"
template="Magento_Theme::html/slider.phtml"
/>
</referenceBlock>
if not use:
$sliderBlock = $this->getLayout()
->createBlock("Magento\Framework\View\Element\Template")
->setTemplate("Magento_Theme::html/slider.phtml");
<?php
$sliderBlockBefore = $this->getSliderBlock(); //
$sliderBlockBefore->setData(['slider_html'=>'before-slides', ...]);
?>
<?= $sliderBlockBefore->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
]);
<?php foreach ($items as $key => $item) : ?>
<div class="slider__item">
...
</div>
<?php endforeach ?>
<?php
$sliderBlockAfter->setData(['slider_html'=>'after-slides', ...]);
?>
<?= $sliderBlockAfter->toHtml(); ?>
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"
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
.
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
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 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.
icon
value use icon id (Alpaca components)title
use accessible title that describe the icon imageicon
you can add, adjust class according to your needspicture.phtml
: vendor/snowdog/theme-frontend-alpaca/Magento_Theme/templates/html/picture.phtml
you can adjust it for your needs in the child theme.{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img480="<img-url>" img768="<img-url>" img960="<img-url>" img1024="<img-url>" img1328="<img-url>" img_full="<img-url>" picture_class="image" picture_alt="<descriptive image alternative text>" }}
picture_class
is a required attributeWe use lazysizes in project, so when you implement images with <img>
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 <img>
tag
This solution is already implemented on responsive solution in picture.phtml
template
<div
class="ratio-container"
style="padding-bottom: $aspectRatio%"
>
<img
src="data:image/gif;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAABCAQAAABN/Pf1AAAAC0lEQVR42mNkwAIAACoAAgu1Hc4AAAAASUVORK5CYII="
data-src="<image url>"
alt="<descriptive alternative text for image>"
class="ratio-image"
/>
</div>
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"}}
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 1025pxusage example:
{{block class="Magento\Framework\View\Element\Template" template="Magento_Theme::html/picture.phtml" img_768="<img-url>" img_1024="<img-url>" img_full="<img-url>" img_default="<img-url>" picture_class="image" picture_alt="<descriptive alternative text for image>" 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="<unique-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.
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)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)for Magento version < 2.3.6, mixins.js module patch is required/ Patch provided and explained here
Magepack is already integrated with Frontools
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
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 <config_path>
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:
head.additional
and in custom template add assets:<link
href="<?= $this->getViewFileUrl('Namespace_ModuleName::css/styles-file.min.css') ?>"
rel="stylesheet preload"
as="style"
/>
an example can be found here: vendor/snowdog/theme-frontend-alpaca/Amasty_GdprCookie
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
yarn styles --prod && yarn babel --prod && yarn svg
generate magepack config: yarn magepackGenerate ..
switch to production mode:
bin/magento deploy:mode:set production
/tools
yarn magepackBundle --config <config_path>