Salesforce B2C Commerce 19.2 > Getting Started > Getting Started for Developers > Getting Started with SGJC

SGJC Setup

SiteGenesis is a full-featured demonstration ecommerce site to explore Salesforce B2C Commerce and its capabilities. You can use it as the basis of your own custom site. For developers, it provides sample code—pipelines, scripts, and ISML templates. For merchants, it offers sample configurations for catalogs, categories, products, and so on.

Topic information:

Download SiteGenesis

Set Up Your Local Machine

Import SiteGenesis Data into an Instance

Build SiteGenesis

Automated Testing

Build JSDoc and the Styleguide

Customize Your Application

Build and Testing Tools

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 from XChange

You can download the source code, functional specs, wireframes, and release notes for SiteGenesis in the B2C Commerce XChange portal.
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.
  1. Go to the SiteGenesis downloads page.
  2. Click the source code link for the latest version, and choose where you want to save the file.
  3. Unzip XChange_Download.zip.
    Note: On MacOS, we recommend that you use the command-line unzip utility to expand the file. For example, unzip XChange_Download.zip.

    The .zip file expands to demandware-sitegenesis-community-19b5dd867378, where the last part of the name is the commit ID.

  4. You can also download any available SiteGenesis projects, such as the hi-resolution images or content sharing site.

Set Up Your Local Machine

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

  1. Expand the downloaded .zip files.
  2. From a command-line prompt, navigate to the demandware-sitegenesis-community directory.
  3. 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.
  4. 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.
  5. 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. See Getting Started for Developers. Specifically, review the sections on Connect to a Server, Configure your Server Connection, and Register your Cartridge.
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. See Import SiteGenesis Data into a Sandbox.

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.
  1. Download the high-resolution images from the SiteGenesis space.
  2. 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.
  3. 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 through the See SiteGenesis link in the SiteGenesis space on Xchange.
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 configure these features, see Configure Storefront Preferences.

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




Note: The SiteGenesis cartridges included with the demo instance are built just before they are uploaded to the demo instance, unlike cartridges created from Studio - how do these work in comparison? or downloaded from Xchange.

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:
  1. Open a command-line terminal and navigate to the top level in your SiteGenesis download.
  2. before telling user to enter a command, state why.? 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

replace this text with what the user is building.

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:

  1. Open a command-line terminal, and navigate to the top level in your SiteGenesis download.
  2. 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.

not clear why this mentions JSHint

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:

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

  1. Install all dependencies.

    % npm install 
  2. 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:

  1. Open a terminal and navigate to the top directory of your repository.
  2. Enter:
    grunt doc

    This starts a server that is used to host the documentation. Don't close the terminal or enter other commands.

  3. 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.

  1. Select site > Merchant Tools > Site Preferences > Storefront URL.
  2. 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.

Related Links

SiteGenesis Standards Compliance

Migrate Your Storefront to Controllers