SGJC Setup

Topic information:

If you are creating a storefront project, choose whether you want to base the project on controllers or pipelines. If you include both options, the controller cartridge is used.

In these examples, demo is the name you gave your storefront cartridge when you created it.


                     demo.web.yourcompany.demandware.net

Do not store important data on the demo site. The demo sandbox is reinitialized with each release, which erases any data stored on the instance. Therefore, do not use the demo site for development.

You can also create SiteGenesis storefront cartridges in Eclipse, after you install the B2C Commerce plug-in.

Download SiteGenesis

You can download the source code from GitHub at the Salesforce Commerce Cloud repository for Site Genesis.

Note: If you are updating an existing version of SiteGenesis and want to check the version you have, you can check this in the package.json file.

Set Up Your Local Machine

These instructions assume you are using the MacOS and a bash shell.

Expand the downloaded .zip files.
From a command-line prompt, navigate to the demandware-sitegenesis-community directory.
Download and install Node.js, if it is not already installed. You can test whether the node is installed by entering:
```
node -v
```
If node is already installed, this command returns a version number.
Note: B2C Commerce only uses Node.js for npm dependency management.
Use npm to install the modules included with SiteGenesis.
```
npm install
```
Important: Run this command any time you download a new version of SiteGenesis, because the dependencies included with the application might have changed.
Install one of the following build systems (not both) that watches, processes, and concats SASS code.
- Gulp
```
npm install -g gulp
```
- Grunt
```
npm install -g grunt-cli
```

Upload Code from Your Local Machine to a B2C Commerce Instance

You upload code via a B2C Commerce plug-in to Eclipse.

Note: As of Release 16.1, you must explicitly list the cartridges you want to use. If you are using your demo instance to test your cartridges, We recommend removing the SiteGenesis cartridges that are added to the cartridge path for demo instances. Don't use demo instances for development.

Import SiteGenesis Data into an Instance

To view products in a SiteGenesis storefront site, you must import the standard SiteGenesis data. The standard data includes product information and images.

If you import the SiteGenesis code without importing the data, a broken footer appears. If you are using SiteGenesis in the same sandbox as your custom site, we recommend exporting your current site, importing the site data from the demo_data_no_hires_images directory and then importing your site again.

Never import SiteGenesis into an instance in your PIG, but you can import SiteGenesis into each instance in your SIG. However, if you import SiteGenesis into a sandbox that contains other customized sites, you could overwrite existing attributes and lose data.

It is safe to import SiteGenesis into an empty sandbox. If you also want to import custom sites into the empty sandbox, import SiteGenesis first to retain you custom sites' attributes for your custom sites are retained if there are conflicts, as your custom attributes will overwrite the imported SiteGenesis custom attributes.

If there are conflicts between your attributes and SiteGenesis, your custom attributes overwrite the imported Site Genesis custom attributes. If this occurs, The Site Genesis site might not function properly, but your customer data is kept intact. After importing SiteGenesis, you can validate its behavior by comparing it to the site running on the dedicated instance.

Import High-Resolution Data

The standard SiteGenesis import data contains low-resolution images, a catalog, and other data. If you want to view and work with high-resolution data, you can import it from the SiteGenesis site.

Download the high-resolution images from the SiteGenesis space.
Upload and import the standard import data. Because the hi-res data does not include most catalog and product data, you must import the basic data first to have all the data required for the site.
Upload and import the hi-res images.

After importing SiteGenesis, you can validate its behavior by comparing it to the site running on the latest version of SiteGenesis, available on GitHub.

Note: Because SiteGenesis is on a different release schedule than B2C Commerce, it is possible that the application you download might be more advanced than the version of the application available on the demo instance, which always tracks to the latest B2C Commerce release.

Configure SiteGenesis

You can switch some SiteGenesis features on or off in Business Manager.

To use SiteGenesis, you must have cookies enabled in your browser.

If you do not have cookies enabled, you might see entries similar to the following in the error logs.

ERROR PipelineCallServlet|"TypeError: Cannot read property "calloutMsg" from null ([Template:slots/category/TrendingNow:${slotcontent.calloutMsg}]#1)    at [Template:slots/category/TrendingNow:${slotcontent.calloutMsg}]:1
System Information

Build SiteGenesis

The JavaScript and CSS used in SiteGenesis is modularized. You can compile it into a single app.js and style.css to optimize performance and prevent namespace collisions. If you don't compile the appropriate files using the build, the storefront does not appear the same, because it does not use JavaScript:

Before Build	After Build

Detect File Changes During the Build Process

You can use the SiteGenesis build tools to detect changes to files. The SiteGenesis build compiles all the .css files into the style.css file, and the client-side JavaScript files into the app.js file. Client-side JavaScript files are in the cartridge scripts/js directory.

To watch files and build if there are changes:

Open a command-line terminal and navigate to the top level in your SiteGenesis download.
Enter the following command:
```
grunt watch
```

This command runs the default task in the background and watches for changes in *.scss or *.js files. If changes are detected, the task recompiles the style.css and app.js files. Don't close the tab or enter other commands in the terminal if you want the build to continue to watch.

Note:

When you use watching to build, Watchify is used instead of browserify for faster bundling by taking advantage of caching. This shouldn't result in any differences in the resulting compiled files.

Note: To upload the compiled files to your sandbox, you must have Studio open with the style.css and app.js files open.

Build Manually

This section describes all commands in grunt, but similar commands can also be run in gulp.

To run any build command, open a terminal and navigate to the top directory of the SiteGenesis repo. This is the parent directory for the app_storefront_controllers folder.

To perform all compilation tasks for SiteGenesis:

Open a command-line terminal, and navigate to the top level in your SiteGenesis download.
Enter the following command. You can also use gulp.
```
grunt build
```

Summary of build commands

Command	Description
`grunt`	Runs grunt in watch mode, compiling changed .scss files into style.css and .js files into app.js as needed.
`grunt css`	Compiles the .scss code into the style.css file and runs Auto-Prefix to set vendor prefixes. This task is also run automatically on any .`scss` file change by using the `gulp watch` task.
`grunt js`	Compiles the client-side JavaScript files into the app.js file. The JavaScript modules rely on Browserify to compile JavaScript code written using the CommonJS modules standard. The entry point for browserify is `app_storefront/cartridge/js/app.js`, and the bundled JavaScript is output to `app_storefront/cartridge/static/default/js/app.js`.
`grunt jshints`	Runs JSHint on all *.js files.
`grunt jscs`	Runs jscs on all *.js files. JSHint detects errors and potential problems in your JavaScript code. This runs jshint on every.js file and creates a report of any problems it finds. The SiteGenesis team uses this on every commit to check out JavasScript code and we encourage its use by all of our customers and partners.
`grunt --sourcemaps`	Creates the source maps for the .scss and .js files. You can create mappings between app.js and source files that, when uploaded, let you set JavaScript breakpoints directly in the source files (such as pages/account.js) rather than only in the huge app.js file. You set breakpoints in your browser (Chrome, Safari, or Firefox. Using sourcemaps, you can quickly identify the source JavaScript file the code you are inspecting refers to and debug issues more easily. Likewise, source files for .scss files are identified when inspecting elements so that you can quickly identify and modify the relevant .scss file while editing the pages in your browser. SiteGenesis only supports external sourcemaps because Eclipse tends to crash with inline sourcemaps. As a result, if you use Grunt, sourcemaps are only available when the build steps are run explicitly and a type is specified. For example: `grunt js --sourcemaps`. Note: Sourcemaps are not enabled if you are using watching to build.
`grunt test:unit`	Runs all the unit tests in the `test/unit` directory.
`grunt test:application`	Runs all the application tests in the `test/application` directory.
`grunt test:application --suite checkout`	Runs all the tests in the `test/application/checkout` directory.
`grunt doc`	Generates the client-side and server-side documentation and style guide and serves all resources over a static server at port 5000. The style guide demonstrates all styles used by your project. To access the generated doc, use `http://localhost:5000/`

See Build and Testing Tools and consult the README files in the app_storefront_core/cartridge/scss directory and the app_storefront/cartridge/js directory.

Automated Testing

SiteGenesis has a series of application tests and unit tests that are run from the command line using either grunt or gulp. Application tests are used for specific test cases, and unit tests exercise specific areas of functionality. These tests are enhanced and changed with each release to reflect the features in the application.

The SiteGenesis automated testing strategy is built on a set of tools that include:

Selenium and phantomjs - Selenium server is used for unit tests. phantomjs is an option for running tests. However, we do not guarantee that all tests will pass if using phantomjs, because phantomjs is used primarily for headless testing, and some tests require the site user interface to run correctly.
Webdriver for multiple browser and headless testing.
Mocha is a JavaScript test framework.

Tests are written in JavaScript and executed via grunt and gulp on the command line of a terminal window.

Directory Structure for Testing

The test directory contains all the files needed to configure and execute these tests.

test
├── README.md 
├── application 
│ ├── homepage 
│ │ └── general.js 
│ ├── productDetails 
│ │     └── index.js 
│ └── webdriver 
│   ├── client.js 
│   ├── config.json 
│   └── config.sample.json 
└── unit 
      └── util 
           └── index.js

Installing and Configuring the Tests

Install all dependencies.
```
% npm install 
```

Install phantomjs and the standalone Selenium driver.

% npm install -g phantomjs 
% npm install --production -g [email protected] 
% selenium-standalone install

Run the Tests

After installing the dependencies, start the Selenium server each time you want to run the tests.

% selenium-standalone start

It's important to keep this command-line instance running in the background. Do not enter other commands or close the terminal.

Unit Tests

Run this command to test JavaScript methods without accessing a server. It uses mock data to simulate server responses, which means that the tests execute quickly. They do not need a browser in which to run.

% grunt test:unit

Application Tests

The application tests require a browser (either a real one or a, headless browser that represents a site in memory, but does not render the user interface). They also contact the server and compare the HTML generated by a server with the expected responses in the tests.

To run all the application tests:

% grunt test:application

To run just the tests contained in a single subdirectory suite use:

% grunt test:application --suite checkout

Build the Jsdoc and Styleguide

To build a representation of the styles compiled in the style.css:

Open a terminal and navigate to the top directory of your repository.
Enter:
```
grunt doc
```
This starts a server that is used to host the documentation. Don't close the terminal or enter other commands.
In your browser, navigate to: http://localhost:5000/.

Development Settings in Business Manager

Caching

You might want to turn off caching for the site you are working on during development. If you are working with SiteGenesis, to disable caching. See also Disabling Page Caching for Development.

Site URLs

You might want to use the standard B2C Commerce URL syntax in the early phases of development.

Select site > Merchant Tools > Site Preferences > Storefront URL.
On the Storefront URL Preferences page, make sure the Enable Storefront URLs option is not selected.

This lets you enter a URL such as https://localhost/on/demandware.store/Sites-SiteGenesis-Site/default/Hello-World directly in your browser to test new controllers or pipelines.

Customizing SiteGenesis Features

When using SiteGenesis as the basis of your storefront application, you might want to take advantage of existing or new features that might not be automatically included in the storefront. These features, typically configured as custom preferences, include slide show effects, responsive design, and multi-shipping. See Configuring Storefront Preferences.

See the SiteGenesis wireframes for application details.

See SiteGenesis and CSS for details on customizing the look and feel of your storefront.

Build and Testing Tools

The following tools can be automatically installed using npm, a feature of node. js.

Tool / technology	Description
Gulp	The gulp.js build system used to watch, process, and concatenate SASS code.
Grunt	Also a build system, similar to gulp. Parallel SiteGenesis build tasks exist in both gulp and Grunt.
SCSS	SCSS (Sassy CSS) is a syntax used for Sass (Syntactically Awesome StyleSheets), a CSS extension.
Autoprefixer	Compiles and processes SASS files into CSS files.
Jscs	Used for code linting and style checking. Use JSCS to programmatically enforce your programming style guide. This runs jscs on every client-side JavaScript file and creates a report of any problems it finds. The SiteGenesis team uses this on every commit to check out JavaScript code and we encourage its use by all of our customers and partners.
Browserify	Compiles JavaScript code written in CommonJS standard. Assuming a modular JavaScript architecture.
Selenium	Used for web browser automation.
Webdriver	Used for multiple-browser testing.
Mocha	Used for the test framework.