/SXA.Styleguide.Frontend.SXAUmbrella

SXA.Styleguide.Frontend project by Mark van Aalst redone with SXA Umbrella

Primary LanguageCSS

NOTA BENE

This is a modified version of the original SXA.Styleguide.Frontend project by Mark van Aalst to showcase how SXA Umbrella - a project structure and tooling to optimize front-end team development workflow in any Sitecore SXA project - can optimize the front-end development of this SXA sample website as well.

Fixing the SASS

Because the SXA.Styleguide.Frontend project did heavily modify the SASS code of the default Sitecore theme as provided by the @sxa/Theme npm package, this project contains special code to "fix" the SASS of the theme to make it Webpack compatible and include it in the src of the theme.

The "legacy" version of the theme is located in the folder legacy. This folder contains tooling to fix the SASS code (npm run fix), and copy the fixed SASS code to the folder Media Library\Themes\Sitecore\Styleguide\Styleguide\src\theme.

The code in the legacy folder is completely generic and can be used in any project to convert legacy theme SASS code into Webpack compatible the SASS code using the following steps:

  1. Copy the SASS code of your theme into the folder legacy\theme\sass
  2. Edit package.json in the legacy folder and change the value of destinationTheme to the correct path where the fixed code must be deployed to, e.g. ../Media Library/Themes/Sitecore/Styleguide/Styleguide
  3. Do an npm install in the legacy folder
  4. Execute npm run fix
  5. Done

Converting SXA.Styleguide.Frontend

The following steps are taken to convert the original SXA.Styleguide.Frontend project into an SXA Umbrella compatible project:

  1. Copy the Scriban files from the original folder src\-\scriban to Rendering Variants\Styleguide\-\scriban
  2. Copy the image files from the original folder src\-\media\Project to Media Library\Project
  3. Copy the Extension Theme files src\-\media\Extension Themes\CSS Animations to Media Library\Extension Themes\CSSAnimations\src, so to the src folder
  4. Install animate.css used by CSSAnimation with npm install animate.css --save-dev
  5. Add a file Media Library\Extension Themes\CSS Animations\src\wow-init.js as entry-point for Webpack to build the JavaScript bundle for the extension theme, and make modifications to require animate.css and wow.js
  6. Add a file Media Library\Themes\Sitecore\Styleguide\Styleguide\src\index.ts as entry-point for Webpack to build the JavaScript bundle for the theme - this file references some additional created files for including the SASS files in the correct order
  7. Configure the file config\webpack.config.js to have the correct entry points
  8. Modify the .gitignore file to exclude the folders that are generated by SXA Umbrella
  9. Configure the file config\config.json to point to the correct Sitecore server

Getting it up and running

To get the front-end code working on Sitecore I first deployed the SXA.Styleguide project to a Sitecore server, and then cleaned the following folders in the Sitecore content editor:

  • /sitecore/media library/Extension Themes/CssAnimations (remove scripts, styles)
  • /sitecore/media library/Themes/Sitecore/Styleguide/Styleguide (remove scripts, styles, fonts, images) and then executed the command: npm run build-deploy-watch to build and deploy the new front-end code to the site an go in watch mode for further development.

Next steps

The next step is to modify the SXA.Styleguide project to serialize only the needed items to Sitecore using Unicorn, and use the output of npm run build:dist to deploy all theme-related artifacts.

Known issues

  • There is some collision is styling that must be fixed, so the site looks different from the original SXA Styleguide site.
  • When you switch to the Danish language the screen goes blank (clear cookies to switch back to English)

THE REST OF THE DOCUMENTATION IS THE ORIGINAL DOCUMENTATION OF SXA Styleguide

The SXA Styleguide is an education site based on SXA that helps explaining the inner working and illustrating best practices.

This repository holds all the frontend code needed to run the site. It consists of two parts, the SXA themes and the Scriban templates used on the site. The folder structure used in this repository mimics the SXA Creative Exchange output, therefore you can find the sources for the themes and the separate Scriban templates in the following folders:

Type Location
Theme \src-\media\Themes\Sitecore\Styleguide\Styleguide\
Extension Theme \src-\media\Extension Themes\CSS Animations
Scriban \src-\scriban

Requirements

The Styleguide is built to support Sitecore Experience Platform 9.3 using Sitecore Experience Accelerator (SXA) 9.3.

Prerequisites

If you have already configured Creative Exchange you can skip the first step

  1. Open PathToSitecoreInstance/Website/App_Config/Include/z.Feature.Overrides folder and remove .disabled from z.SPE.Sync.Enabler.Gulp.config.disabled file;

  2. Clone the repository

  3. Switch to this repository and open \src\-\media\Themes\Sitecore\Styleguide\Styleguide\gulp\config.js

  4. Update config file for Gulp tasks: serverOptions.server - path to sitecore instance. Example server: 'http://www.sxa.sc';

  5. go to the folder \src\-\media\Themes\Sitecore\Styleguide\Styleguide\ using the command prompt (or VS Code terminal)

  6. Run npm install (node.js and npm should be already installed);

  7. Run the gulp task to start Creative Exchange Live

For detailed instructions on how to setup Creative Exchange Live please read the readme file

Visual Studio Code

In the repository there is a Visual Studio code workspace that directly adds the folder locations mentioned previously.

Recommended VS Code extensions:

More information and documention on Scriban can be found at the authors website Sitecore extensions to Scriban are documented on the official Sitecore Documentation website

Disclaimer

The code, samples and/or solutions provided in this repository are unsupported by Sitecore Support. Support is provided on a best-effort basis via GitHub issues.

It is assumed that you already have a working instance of Sitecore XM and all prerequisites prior to installing this site. Support for product installation issues should be directed to relevant Community channels or through regular Sitecore support channels.

Warranty

The code, samples and/or solutions provided in this repository are for example purposes only and without warranty (expressed or implied). The code has not been extensively tested and is not guaranteed to be bug free.