How to write a Theme

Owned by Former user (Deleted)
Nov 13, 2017
4 min read

How to write a Theme for SmartStore.NET

Files and folders:

  • theme.config
  • preview.png
  • /Content (optional)
  • /Views (optional)
  • /Views/Shared/ConfigureTheme.cshtml (optional)
  • /Content/_user.scss (optional)

theme.config

The file theme.config is the most important file of a theme. Here, you can configure the basic values such as title, author or version. Also, you can declare variables that can be configured by the user.

<Theme 
	baseTheme="Flex" 
	title="Flex Sample" 
	previewText="The 'Flex Sample' shop theme." 
	author="My Company" 
	version="1.0">
	<Vars>
		<Var name="SiteBackground" type="Color">#E8F5E9</Var>
		<Var name="BaseFontSize" type="String">14px</Var>
		<Var name="ShopBarLabel" type="Select#ShopBarLabels">label</Var>
	</Vars>
	<Selects>
		<Select id="ShopBarLabels">
		      <Option>label</Option>
		      <Option>label-primary</Option>
		</Select>
	<Selects>
</Theme>

 

Attributes of the Theme-Node

  • baseTheme: determines the theme from which your theme is derived (find more information about theme inheritance further below)
  • title: determines the title of your theme
  • previewText: determines the preview text which is shown within the admin area next to the theme
  • author: contains information about the company or person who has written the theme
  • version: determines the version of the theme

Theme inheritance

Before you start a design from scratch, you can also derive everything from a base theme and just alter the parts of it that you don't like. Therefore, you just need to determine a base theme within the baseTheme attribute in the theme.config.

We've structured our css files to be very granular so that in most cases, you only need to overwrite small parts in order to change the design of a certain area. Sometimes, you may just want to change or add a line, in which case we recommend using the file _custom.sass to overwrite other css declarations. This is an empty file that gets rendered last, so its declarations have the highest priority. When you work like this, you can update your base theme to a higher version without any problems. You have the latest code and your changes remain as they were before the update.

Whereas the file _custom.sass is set up to be edited for theme developers, the file _user.sass is there to be edited by shop admins.

You can also derive your theme from one that has also been derived from another, thanks to multi-level inheritance. The SmartStore.NET theme engine tries to locate the actual physical file by looking up all corresponding paths in the hierarchy chain.

If you just want to alter certain lines in a particular css file, you can also import the css file of one of the parent themes and add your lines to it. This way, your theme keeps up to date with the current code and your changes also remain intact.

/*
    The 'explicit' query at the end is extremely important here,
    as it forces the theme engine to load the referenced file explicitly
    without looping through the hierarchy chain (beginning with the current theme)
*/
@import "../../Flex/Content/block.sass?explicit";

.block.block-bordered .block-title a {
    color: #fff;
}

 

Theme variables

You can define your own variables within the variables node in the theme.config file. These variables can be used within your css. There are 5 different variable types as listed below:

  • Select: any value defined within a corresponding selection. The type attribute of select always has to refer to the id of a select node (see example above). Variable type and select id are separated by a #
  • String: string value
  • Color: hexadecimal color value
  • Boolean: boolean value (true or false)
  • Number: integer value (e.g.: 1, 2, 1024)

The file ConfigureTheme.cshtml has to be placed in the directory Views\Shared. Its purpose is to provide an administration area for your theme. This is optional as long as you derive from a base theme. You only have to create it when you have defined new theme-specific variables. To add an editor for the variables that are defined in your theme.config, simply add the following code for every variable you have determined.

@ThemeVarEditor("MyVariable")

This code will automatically render an editor depending on the variable type.

  • Select: Select-Box
  • String: Textbox
  • Color: Color-Picker
  • Boolean: Selectbox (with the values true or false)
  • Number: Textbox

Once you've defined your variables, you can use them in css like this:

body {
    background: @var_MyVariable;
}

 

preview.png

The preview.png will be shown within the admin area, where the themes are selected by the Shop-Adminstrator.

/Content

Within the /Content directory, you can override any content of the base theme or the /Content directory from the SmartStore.Web project.

/Views

When you want to restructure the HTML structure, you need to have a look in the /Views directory in the SmartStore.Web project where all views are located. Once you've found the view that contains the HTML you want to alter, create a directory with the same name in your theme and copy the view into it. Now, you can alter the HTML structure within your theme.

Own Resources

Should you need to access your own resources for a theme, you can refer to them in Views/Shared/Head.cshtml as follows.

Html.AppendCssFileParts(false, "~/Themes/MyTheme/Content/mysassfile.sass");
Html.AppendCssFileParts(false, "~/Themes/MyTheme/Content/mycssfile.css");
Html.AppendScriptParts(false, "~/Themes/MyTheme/Scripts/myscriptfile.js");

 

Packaging

To package a theme so that it can be installed by SmartStore.NET, open the SmartStore Packager src\Tools\SmartStore.Packager\bin\Debug\SmartStore.Packager.exe

The root path is your SmartStore.Web project which contains your theme. After entering this path, you can read the extensions that are included within. Then, you just choose your theme and an output path and click on Create package

Components

Sass

Sass is a CSS pre-processor, meaning that it extends the CSS language, adding features that allow variables, mixins, functions and many other techniques that allow you to make CSS that is more maintainable, themable and extendable.

http://lesscss.org/

Bootstrap

Bootstrap is the most popular HTML, CSS, and JS framework for developing responsive, mobile first projects on the web.

http://bootstrapdocs.com/v2.1.0/docs/getting-started.html

Font Awesome

Font Awesome gives you scalable vector icons that can instantly be customized — size, color, drop shadow, and anything that can be done with the power of CSS.

http://fortawesome.github.io/Font-Awesome/

ASP.NET MVC

ASP.NET MVC gives you a powerful, patterns-based way to build dynamic websites, enabling a clean separation of concerns, giving you full control over markup for enjoyable, agile development.

http://www.asp.net/mvc