Theme Asset Management

At a high level, when you work with themes, you create a theme using the Kibo eCommerce Theme Generator. The theme you create should be based on the Kibo eCommerce Core theme (or on another theme ultimately based on the Core Theme), which provides a robust foundation of functionality so you don't have to start from scratch when creating your theme. After you create your theme, you can edit the theme files, upload the theme to Dev Center, install it on a sandbox, modify the theme as needed, and publish the theme.

Theme Development Lifecycle

The following diagram represents the theme development lifecycle:

Other important theme development concepts include:

Create a Theme Record

Before you can upload theme files, you must create a theme record in Dev Center. You must give a theme a unique name and ID.

  1. Log in to Dev Center.
  2. Click Develop > Themes.
  3. Click Create Theme.
  4. Enter a unique name and ID.
  5. Click Save.

Create or Update a Theme

After you have a theme record in Dev Center, you can create a new theme for that record or (in subsequent visits) update the existing theme files for the record.

Before You Begin

Install the following software on your local machine:

In addition to the listed software, you need access to a Dev Center Account that contains a provisioned sandbox.

Don't have a Dev Center Account? Request a Demo

Create a New Theme

The Kibo eCommerce Theme Generator is a Yeoman plugin that generates the scaffolding (e.g., directory structure, reference files, and build files) necessary to package a Kibo eCommerce theme and upload it to Dev Center. It’s designed to augment, not overwrite, existing themes. If you have a theme that extends the Kibo eCommerce Core theme, you can safely run this tool in that directory without overwriting your existing files. Whenever Kibo eCommerce releases a Core theme upgrade, you can use this tool to merge changes from the Core theme ( or any other theme Git repository) with your theme.

To create a brand new theme that inherits from the latest Kibo eCommerce Core theme:

  1. Open a terminal (OS X) or a command prompt (Windows).
  2. Install the Yeoman command-line tool globally:
    npm install -g yo
  3. Install the Grunt command-line tool globally:
    npm install -g grunt-cli
  4. Install the Kibo eCommerce Theme Generator globally:
    npm install -g generator-mozu-theme
  5. Create a new folder for your theme on your local machine and navigate to it:
    mkdir your_theme && cd your_theme
  6. Run the Yeoman generator inside your theme directory:
    /your_theme/$ yo mozu-theme
  7. Note: If you have an old version of the tool installed, you’ll be prompted to update it. Press <Ctrl+C> to exit the application and enter the following command: npm install -g generator-mozu-theme
  8. Select Brand new theme.
  9. Enter the public name of your theme.
  10. (Optional) Enter a short description of your theme.
  11. Enter the initial version.
  12. Select Mozu Core Theme as the base theme from which your new theme will inherit.
  13. Select which version of the Kibo eCommerce Core theme from which your new theme will inherit.
  14. Enter your theme’s Dev Center Application Key.
  15. Note: If you’re using a package other than Release, make sure you enter the correct Application Key. Package names are appended to the Application Key of each package for identification purposes. The build tools rely on the Application Key to upload files to the right place in Dev Center.

  16. Enter your Developer Account login email.
  17. Enter your Developer Account password.
  18. Select your developer account.

You now have a blank theme based on the latest Kibo eCommerce Core theme, which you can modify, build, and upload to Dev Center. Since the Kibo eCommerce Core theme Git repository is connected to this Git repository as a remote, you’ll be able to merge upstream updates from the Core theme with your theme in the future.

Although the Kibo eCommerce Theme Generator is the recommended method for creating and uploading themes, you can also complete the process manually. To manually upload theme files from within Dev Center:

  1. Compress your local theme project into a .zip file.
  2. Log in to Dev Center.
  3. Click Develop > Themes.
  4. Double-click the theme where you want to upload files.
  5. Click the Packages tab.
  6. Select the package you want to upload files to from the Active Package drop-down menu.
  7. Click More > Upload.
  8. Drag and drop your theme .zip file into the Upload files dialog box.
  9. Wait for confirmation that the upload is complete.
  10. Click Done.
  11. You should see the contents of your theme in the Packages tab.

Merge Updates from the Latest Kibo eCommerce Core Theme

If the latest Kibo eCommerce Core theme is already connected to your repository as a remote, you can merge changes from the Core repository into your theme. You must resolve any merge conflicts that arise and commit your changes to complete the upgrade process. Kibo eCommerce recommends conducting user acceptance, automated unit, and end-to-end testing of your site to ensure the latest Core theme works for your site.

To merge updates from the latest Kibo eCommerce Core theme:

  1. Examine the merged Github Pull Requests or Theme Release Notes to see what individual features are coming over from the latest Core theme. You can also use the Compare View in Github to compare different versions of the Kibo eCommerce Core Theme.
  2. Open a terminal or command prompt and navigate to your local theme directory.
  3. Enter grunt mozutheme:check to see if any updates are available.
  4. Select the version you’d like to merge with your theme and use the following command syntax to merge: git merge <commitID>
  5. Replace <commitID> with the value displayed next to the selected version:
  6. Resolve all merge conflicts and ensure your repository is in a clean state before proceeding. 
  7. Install your upgraded Core-based theme on a development sandbox and activate it.
  8. Activate Debug Mode in the storefront by adding the query parameter debugMode=true to any storefront URL. For example, yourSite.com/about-us?debugMode=true.
  9. Visually examine your theme for problems.
  10. Test your site for issues:
    • View a category
    • Search for products
    • Configure a product
    • Manipulate the cart
    • Check out and place an order
    • Make changes to your account page, etc.
  11. Make any necessary corrections based on visual or console errors.
  12. Continue testing and developing until your theme is free from errors and regressions.

Upgrade a Legacy Theme

You must manually upgrade themes that extend legacy versions of the Kibo eCommerce Core theme (version 8 and earlier) to use the latest Core theme instead. The Kibo eCommerce Theme Generator connects the latest Core theme to your repository as a remote so you can merge changes from the Core Git repository into your theme. You must resolve all merge conflicts and commit your changes to complete the upgrade process. Kibo eCommerce recommends conducting user acceptance, automated unit, and end-to-end testing of your site to ensure the latest Core theme works for your site.

To upgrade a legacy theme:

  1. Examine the merged Github Pull Requests or Theme Release Notes to see what individual features are coming over from the latest Core theme. You can also use the Compare View in Github to compare different versions of the Kibo eCommerce Core Theme.
  2. Run the Kibo eCommerce Theme Generator to upgrade your theme to inherit from the latest Core theme:
    1. Open a terminal or command prompt and navigate to your local theme directory.
    2. Enter yo mozu-theme.
    3. Select Upgrade now.
    4. Resolve all merge conflicts and ensure your repository is in a clean state before proceeding.
  3. Install your upgraded Core-based theme on a development sandbox and activate it.
  4. Activate Debug Mode in the storefront by adding the query parameter debugMode=true to any storefront URL.
  5. Visually examine your theme for problems.
  6. Test your site for issues:
    • View a category
    • Search for products
    • Configure a product
    • Manipulate the cart
    • Check out and place an order
    • Make changes to your account page, etc.
  7. Make any necessary corrections based on visual or console errors.
  8. Continue testing and developing until your theme is free from errors and regressions.

Install a Theme on a Sandbox

Only the Release package can be installed in a sandbox.

  1. Log in to Dev Center.
  2. Click Develop > Themes.
  3. Double-click the theme you want to install in a sandbox.
  4. Click Install.
  5. Select a sandbox from the list and click OK.

Enable a Theme for a Site

After you install a theme to a sandbox, it is available for use on any site within that sandbox. Complete the following steps to enable the theme for a particular site:

  1. In Dev Center, view the theme record.
  2. Under Theme installations, right-click a sandbox and select View Sandbox.
  3. In Admin, got to Site Builder > Themes.
  4. For the site of your choice, click the actions menu for the theme you installed and select Apply.

Publish a Theme

When you're finished developing and testing your theme, publish it as a final version to prevent any unauthorized changes. Only the Release package can be published.

To publish a theme:

  1. Log in to Dev Center.
  2. Click Develop > Themes.
  3. Locate your theme in the grid, right-click it, and select Edit.
  4. Click More > Publish > Publish.

You can't modify a theme once you publish it, but you can develop and publish a new version of an existing theme if necessary.

Deploy to Production

Contact your Kibo eCommerce Account Executive or Solutions Partner to deploy published themes to a production site.

Work on Themes as a Team

Whether you work on themes individually or as team, it is important to understand that you can use the Packages tab in Dev Center to organize your theme files into discrete packages. When a developer first creates a theme in Dev Center, the system automatically creates a Release package for the theme version. The benefit of creating additional packages, however, is that each developer can work on their theme features independently and test their themes on different sandboxes before merging the work of the entire team into the Release package.

Package Types

There are two types of packages in Dev Center:

Development Modes

Until a developer uploads theme files, packages don’t contain any files; they act as containers for the theme files that change. The Kibo eCommerce build tools upload the delta of changed files to Dev Center. When a developer is ready to publish a theme, the published code is contained in the release package. Developers work on a theme in either solo or team development mode.

Solo Development Mode

Solo development mode lets one developer work on one theme. In this mode, the recommended best practice is for the developer to store the base theme files in the release package and create a separate development package. Working in the development package lets the developer make changes without altering the base files. When the theme has been tested and is ready to be published, the developer uploads the production-ready files to the release package.

Team Development Mode

Team development mode lets multiple developers work on one theme by dividing the files between independently working developers; logically similar to feature branches. This mode works well in large companies and with solution or implementation partners. The recommended best practice is to store the base files in the release package and create separate packages for each developer.

The source control component of the file management process is handled outside Dev Center and is the task of the development team, but Kibo eCommerce recommends using Git if possible. When all theme development is complete, the development team merges the file changes, uploads the final theme files to the release package, and publishes the theme.

Get Started with Team Development

The following tutorial provides a quick walkthrough of the team development workflow for themes:

Note:  This tutorial assumes you are using Git for source control, which is also what the Kibo eCommerce Theme Generator uses to enable theme inheritance. For more information about Git, refer to their website

In addition, this tutorial guides you through creating the initial theme record, scaffolding the initial project files based on the Kibo eCommerce Core theme, and uploading these files to an online Git repository. If your team already has a theme repository to begin work off of, you can skip to the Create Development Packages for the Theme in Dev Center section of this tutorial.

Create the Parent Theme in Dev Center

In this section, you create the parent theme record in Dev Center. This theme record will contain all the packages associated with the theme your team works on, but in this section, you only create the release package:

The lead developer should:

  1. Create a theme record in Dev Center.
  2. Note the application key for the theme record.

Scaffold the Parent Theme

In this section, you create the initial version of the theme files that your team will then work on. You can install this theme to a sandbox of your choice for testing purposes:

The lead developer should:

  1. Create a directory on your local machine in which to scaffold theme files.
  2. Open a command prompt within the newly-created project directory.
  3. Run yo mozu-theme to use the Kibo eCommerce Theme Generator to scaffold a new theme. This is the parent theme from which all shared development packages will inherit and will become the release package in Dev Center. During scaffolding, select to:
    • Create a brand-new theme.Note:  If you are basing your work off a theme other than the Kibo eCommerce Core theme, you would specify the repository for that theme instead.
    • Base the theme on the latest version of Kibo eCommerce Core.
    • Enter the application key for the theme record you created in Dev Center. Because this is the parent theme, the application key should match the application key of the Release package.

If you want to test the initial version of the theme that your team will begin working off of:

  1. After scaffolding is complete, run grunt in the project directory to build the theme files and upload them to Dev Center.
  2. In Dev Center, install the theme to a sandbox.
  3. View the sandbox and use Site Builder to enable the theme.

Create a Git Repository for the Parent Theme

Once you are happy with the initial version of the parent theme, make it available to your team members by connecting the local files with an online Git repository:

The lead developer should:

  1. Create a Git repository to house your theme files on GitHub or a similar website.
  2. Note the repository URL (for example, git@github.com:yourProfile/yourRepoName.git).
  3. Open a command prompt in your local theme directory.
  4. Connect your local theme files to your online repository:
    1. Run git remote add origin yourRepositoryURL to add the remote repository.
    2. Run git push -u origin master to push your local files to the remote repository.

Create Development Packages for the Theme in Dev Center

When you are ready to begin developing as a team, create a separate theme package for each developer that will work on the theme:

The lead developer or each individual developer should:

  1. In Dev Center, click your theme record.
  2. Open the Packages tab.
  3. Click New to create a new package for each developer working on the theme.

Complete Feature Work on the Different Theme Packages

Each developer can now work on their features for the theme within separate theme packages and Git repositories.

Each developer on your team should:

  1. Navigate to the theme record in Dev Center.
  2. Click the Packages tab.
  3. Select the package you want to work on and note the application key.Note:  Make sure to note the application key for your development package and not the Release package.
  4. To get the parent theme onto your local machine, you have two options:Tip:  If you connect to your Git repository using SSH, the second option is recommended (cloning from Git). If you connect to your Git repository using HTTPS, both options work equally well.Use the Kibo eCommerce Theme Generator to scaffold theme files based on the parent theme's Git repository:
    1. Create a directory on your local machine in which to scaffold theme files.
    2. Open a command prompt within the newly-created project directory.
    3. Run yo mozu-theme to use the Kibo eCommerce Theme Generator to scaffold a theme based on the parent theme. During scaffolding, select to:
      • Create a theme based on a repository URL (use the repository URL where the parent theme lives, as created in a prior section of this tutorial).
      • Enter the application key for the development package you want to work on.

    Clone the parent theme repository using Git and then update the cloned theme files to point to your unique package application key:
    1. Navigate to a directory in which you want to pull down the Git repository folder.
    2. Open a command prompt within the directory.
    3. Run git clone yourRepositoryURL to clone the Git repository (use the repository URL where the parent theme lives, as created in a prior section of this tutorial).
    4. Change directories into the cloned theme folder.
    5. In the root directory of the cloned theme folder, create a new file called mozu.config.json and configure it as shown in the following code block, making sure to use the application key for your development package:Tip:  To identify you developer account ID, click Launchpad under your user name in Dev Center, and then hover over the link to the account you want to access. You should see your developer account ID appended to the URL, typically as a four-digit number.
      clonedDirectory/mozu.config.json
      {
      	"baseUrl": "https://home.mozu.com",
      	"developerAccountId": yourDevAccountId,
      	"developerAccount": {
      		"emailAddress": "yourDevEmailAddress"
      	},
      	"workingApplicationKey": "yourPackageApplicationKey"
      }
    6. In the cloned directory, run npm install to install all the project dependencies.

  5. After scaffolding is complete, create a Git branch for your feature work by running git checkout -b feature/branchName. Creating branches makes merging your changes easier down the line, and aligns with the organizational model in Dev Center, where development packages (your feature branches in Git) are kept separate from the Release package (the master branch in Git) until they are ready to be combined.
  6. Run grunt in the project directory to build the theme files and upload them to Dev Center.Tip:  Alternatively, run the grunt watch command so that any changes you make locally will be continuously synced with Dev Center. Just refresh your web browser to see the changes on your storefront.
  7. In Dev Center, select the package you are working on and install the theme to a sandbox.Note:  Each developer should use their own sandbox to prevent overwriting the theme files in another developer's sandbox.
  8. View the sandbox and use Site Builder to enable the theme.
  9. Modify the theme files as needed for your feature work. Test the theme changes in the storefront using grunt or grunt watch (recommended since it saves you the time of typing the command each time you make a change).
  10. When you are done working on your feature, complete the following Git operations:
    • If you created new files, add them for tracking: git add -A
    • Commit your changes: git commit -a -m "Your commit message."
    Tip:  Because theme development might take some time, you can also push your ongoing feature commits to the remote repository to back up your work during development.

Merge Feature Branches into Master

When all the developers on your theme are done with their feature work and made their final commit, it's time to merge the separate packages into the Release package:

Each developer on your team should:

  1. Open a command prompt in your local project directory.
  2. Run git checkout master to switch to the master branch.
  3. Run git pull to obtain the latest changes to the parent theme.
  4. Run git checkout feature/branchName to switch to your feature branch.
  5. Run git rebase master to place your feature changes on top of what's in the master branch.Note:  You can also merge master into your feature branch, but in general, the rebase preserves a cleaner working history. For more information on the different merging strategies, refer to web articles on the topic.
  6. Resolve any merge conflicts that may occur. Tip:  The default Git merge tool can be difficult to use. Refer to web articles to learn about other merge tools available to you.
  7. Run git checkout master to switch to the master branch.
  8. Run git merge feature/branchName to merge your feature branch into master.
  9. Run git push to update the remote repository.

After every developer on your team completes this process, the master branch should contain the final version of the theme files, which includes everyone's changes.

Publish Your Theme in Dev Center

After you merge every feature branch into your master branch, upload the latest version of the parent theme to Dev Center and publish it:

The lead developer should:

  1. Open a command prompt in your local project directory.
  2. Run git checkout master to switch to the master branch.
  3. Run git pull to ensure you have the final version of the parent theme.
  4. Update the application key in mozu.config.json to use the Release package application key.
  5. Run grunt to upload the theme assets to Dev Center.
  6. In Dev Center, open your theme record.
  7. In the Packages tab, select the Release package.
  8. Spot-check the uploaded assets to ensure the final theme uploaded correctly to Dev Center.
  9. Install the theme to a sandbox and test it to make sure you are happy with the final version of the theme. If you need to make changes, modify the theme files and use Git and grunt to commit and upload your changes before proceeding to the next steps.
  10. (Optional Clean-Up) In the Packages tab, select each development package and click Delete to delete any package that is not the Release package.
  11. In the Packages tab, select the Release package.
  12. Click More > Publish to publish your theme.Note:  After you publish a theme, you cannot make further changes to the theme assets, including deleting packages. However, you can version a theme.

Theme Versioning and Notifications

Note: You must configure your themes to take advantage of versioning and upgrade notifications in Dev Center. Upgrades are only available when a new version of a parent theme has been published in Dev Center and you have child themes that extend that parent theme uploaded to your Dev Account. Refer to Enable Theme Versioning and Notifications for more information.

If you’ve configured your themes accordingly, Dev Center leverages parent/child links to:

There are two ways to version themes within Dev Center. The following image shows the versioning option within the Theme Grid:

This image shows the upgrade option within the Theme Editor:

Applying a theme upgrade in Dev Center only creates a new version of your existing theme with all the corresponding metadata (e.g., name, application key, incremented version number). Assets from a previous child theme version are not carried over. To complete the upgrade process, you must:

  1. Download the updated theme files.
  2. Merge the changes with your theme in source control.
  3. Resolve conflicts between your theme and the updated theme.
  4. Upload the new theme files to Dev Center.

Refer to Merge Updates from the Latest Kibo eCommerce Core Theme for more information.

Note: If multiple child theme versions (e.g., v1.0.0, v2.1.0, v3.4.2) all inherit from the same parent them, only the most recent child theme version will be upgraded (e.g., v3.4.2).

Whether you’re a solution partner or a developer managing internal theme development at your company, these features simplify theme versioning and preserve the stability of extended themes.

Solution Partners

Solution partners typically leverage upgrades to service multiple clients across multiple tenants. For example, you may want to create a parent theme containing templates and workflows that can be customized to quickly on-board new clients. You can create as many child branches of this parent theme as you need to support as many clients. When you need to add features or fix bugs in a parent theme, your clients will receive notifications that upgrades are available for their child themes as soon as you publish an upgraded version of the parent theme in Dev Center. Your clients can determine if and when to upgrade their child themes.

Development Managers

Development managers typically leverage upgrades to manage multiple theme versions on the same tenant. For example, as a development manager working for a company doing internal theme development, you may need to develop several themes for different sites on the same tenant based on uniform branding. You can create a parent theme by extending the latest Kibo eCommerce Core theme that includes all of the fonts, logos, and colors specific to your company brand, then create child themes for each of your individual site requirements. When you publish an upgraded parent theme, Dev Center will display upgrade notifications for all child themes that have been configured to inherit from the parent theme.