TABLE OF CONTENTS
- Creating a Custom Theme
- Setting up the admin view within the Znode theme
The Znode WebStore UI is rendered by MCV Razor view templates. All templates and other content files (fonts, styles, etc.) are contained in a Znode 'theme'. These themes can be easily plugged in and switched at any time.
Creating a Custom Theme
The following steps walk through the process of creating a new custom theme.
Step 1: Copy Default Theme
To create a new custom theme, use the default theme (i.e. B2B theme) as a starting point.
- Make a copy of the default theme (i.e. B2B theme) in the 'Views/Themes' folder. Name the copied folder to the desired custom theme name. The name NewTheme is used as an example throughout these instructions.
- Important: Commit the new theme to source control. Immediately committing to source control ensures a full history of theme customizations are captured in source control.
- In Visual Studio, add the custom theme to the project so that it appears in the IDE.
Step 2: Configure Style Transpilation
Many Znode styles are written in SASS to allow global variable definitions to be shared and leverage other features of SASS. The browser only understands CSS though, so the Visual Studio solution must be configured to transpile *.scss files to *.css files.
OPTIONAL PART: Visual Studio may or may not have a built-in ability to transpile *.scss to *.css files, depending on the installation. If needed, the following compiler plugin can be used.
- Install the Visual Studio Web Compiler Plugin if not already done.
- In Visual Studio, right-click on the compilerconfig.json file and go to the “Web Compiler” submenu, check the “Enable Compile on Build…” option.
MANDATORY PART: Visual Studio must be told which file is the root file from which to build the tree of files to transpile.
- Edit the compilerconfig.json file to tell the plugin how to transpile *.scss styles to *.css styles.
- Replace 'Default' with the custom theme's folder name.
The compilerconfig.json, before updating:
The compilerconfig.json, after updating:
Step 3: Register New Theme with Znode
Before enabling the new theme, it must be "registered" in Znode's Admin UI.
- Create a ZIP file of the contents of the NewTheme folder. Note that the “Content”, “DynamicGrid”, etc. folders need to be at the root of the ZIP file.
- For the next step, Znode must be running, so “Start” the solution in Visual Studio and open the Admin UI (http://localhost:6766 by default).
- In the Admin UI, go to CMS > Site Themes.
- Create a new theme, uploading the ZIP file when prompted.
Step 4: Enable New Theme
Once the theme is "registered" in the Admin UI, it can be enabled for a store.
- In the Admin UI, go to CMS > Store Experience.
- Select your store from the list of stores.
- On the General Settings tab, for Theme choose NewTheme to be the theme associated with the store, and choose the first site.css option to be the active CSS file.
- Publish the store by clicking the globe icon next to the store on the CMS > Store Experience page. This moves the state from the SQL database to the MongoDB database, which means the new theme will become active in the WebStore.
- Load the WebStore (http://localhost:3288 by default) in a browser tab to verify everything is working.
Step 5: Edit New Theme
Now that the theme is successfully applied to the store, it is time to confirm that it's possible to edit the theme and see the changes reflected in the UI.
- In the _base.scss file, change the primary color variable from being red to another color.
- Build the solution and run it.
- Refresh the WebStore in the browser and verify the color change has taken effect.
The _base.scss file, before updating:
The _base.scss file, after updating:
Setting up the admin view within the Znode theme
An Administrator has two options for setting up the admin view within the Znode theme.
Administrators can manually copy the views found in the webstore and put them into the admin view.
Administrators can create a symbolic link between the two. The second option is the most efficient approach, this will take care of all the files that need to be copied.
Copy the same views found in the webstore and put them in the admin. (Continuously)
Navigate to the current path of your local Znode install and copy the Themes folder found in
Paste the Themes folder into the Admin folder
So Znode.Engine.Admin contains the newly copied Themes folder.
Using the source control to manage the templates and not relying on uploading/editing templates through the admin is recommended.
Checking the templates into source control and deploying them solves most cases of there being a mismatch as described.
The webstore is rendering templates based on what’s in the webstore directory, these files are versioned control and deployed by what’s in the repo.
The administrator has the content pages, where the pages can be configured and previewed, to do this it’s pulling from its own directory which is a copy or symbolic link from the webstore.
The upload tool, which accepts a template file and puts it on disk in the admin directory.
Uploading templates through the admin is used as a registration tool to make templates available for pages to inherit from. The admin is not meant as a place to continuously upload changes to templates. For this purpose, it is recommended that development is done, commit the changes/templates to source control, and then deploy a new build.