CSS - WEBSALE Dokumentation

This page describes where CSS files are located in the shop, how you create your own stylesheets, and the different ways to include them in your templates. It assumes that you are familiar with the structure of the template directories and have SFTP access to your shop. The WEBSALE V8s sample shop is based on Bootstrap. It already contains the unmodified standard Bootstrap CSS files as well as an additional CSS file with WEBSALE-specific directives. All of these files are available both minified and non-minified. The central tool for working with CSS is the PageSpeed tool. It combines individual CSS files into groupings, minifies them, and adds URL fingerprinting. With URL fingerprinting, the file name automatically changes with every content change. This forces the browser to reload the file instead of showing an outdated version from the cache. By default, the shop uses only these minified files with URL fingerprinting. The benefit of the groupings lies in the loading time. Per template, you only include the CSS files that are actually needed for the respective page. So that you do not have to reference these files individually, you combine them under a freely chosen grouping ID. A shorter loading time affects both the user experience and the search engine ranking of your shop. You find the PageSpeed tool in the Online Service Area (OSB) under the Configuration service, on the “PageSpeed tool” tab. If the tab is not visible there, please contact your WEBSALE AG contact.

This page only covers CSS. For JavaScript files a largely identical procedure applies, with its own folders and its own tags, described in the guide “JavaScript and jQuery”.

Folder structure

In the directory of your online shop you will find the templates folder, which contains all available templates as well as two folders for stylesheets:

benutzer/templates/css_upload
benutzer/templates/css_min

You upload your own CSS files via SFTP into the css_upload folder. That is also where you edit and delete them. The css_min folder, on the other hand, is filled exclusively by the PageSpeed tool. All files it contains are minified and provided with URL fingerprinting. You do not edit these files yourself, because they are overwritten on the next publication. If this folder structure does not yet exist in your shop, please create it accordingly. Without both folders the PageSpeed tool cannot work.

Creating a CSS file

Under benutzer/templates/css_upload the sample shop already contains stylesheet files that you can use as templates. You add further files to the same folder with a simple SFTP client. You are free in the naming, as long as you follow the HTML conventions for file names. Source (external link): HTML conventions for file names A split into two types of files has proven effective:

a “base framework file” with all directives that are needed on every page
several small files for directives that only concern a single template, for example the shopping cart

The reason for the small files lies in the groupings. Only what is stored in separate files can later be combined per page or per topic. The more precisely you separate, the fewer superfluous directives a visitor has to load on a page request.

All CSS files must be stored under benutzer/templates/css_upload. The PageSpeed tool cannot find files in other locations.

Including with the PageSpeed tool (recommended)

After you have provided your files via SFTP in the css_upload folder, you assign them to the desired templates. We recommend the route via the PageSpeed tool, because it means your shop uses the minified files with URL fingerprinting rather than the unprocessed originals. The route consists of three steps: activate the tool, group files, include the grouping in the template.

Only have non-minified file versions processed by the PageSpeed tool. Minifying an already minified file again can lead to errors.

Activate the PageSpeed tool

In the OSB “Configuration” service, the PageSpeed tool is visible by default and therefore active. If the tab is not present in your case, contact your WEBSALE contact. For the shop to actually access the generated files, an additional entry in the shop configuration shop.config is required. Activation by WEBSALE is not necessary for this, but the folder structure described above must be in place. Add the parameter UseMinifiedCSSAndJS in the <TopRank> section:

<TopRank>
...
   UseMinifiedCSSAndJS = yes
...
</TopRank>

Reference: TopRank section

Grouping CSS files

A CSS file can only be included via the PageSpeed tool if it is assigned to a grouping. The grouping is therefore the smallest unit that the shop later references. You create groupings in the Online Service Area (OSB) under the Configuration service. Choose the “PageSpeed tool” tab there and then the “CSS” tab. In the left column under the heading “Groupings” you create as many page- or topic-specific groupings as you like. Each grouping is given a freely chosen grouping ID when it is created. In the examples on this page, this ID is start. In the right column you see all CSS files that you have provided via SFTP in the css_upload folder. If a just-uploaded file is missing, click the refresh icon. Drag and drop the required files inside the OSB into the respective grouping. Then click the globe icon to generate the files for the grouping. For each grouping ID, an optimized CSS file is created in the css_min folder. Each further click on the globe icon generates a new version, provided you have made content changes.

If you later edit an already assigned CSS file again in the css_upload folder, the change becomes visible only after you have re-published the entire grouping with the globe icon. If you make many small changes during the design phase, use the direct access instead.

Including a grouping as an external CSS file

An external CSS file has one decisive advantage: it is used by several templates but only needs to be loaded once by the browser. For each grouping ID, the PageSpeed tool already generates such a file. You include it with the link HTML element at any position in your template. The path is delivered by the WS-CSSURL() tag, in whose parentheses you specify the grouping ID. Example: the start grouping is to be included in the <head> of the template.

<head>
   ...
   <link rel="stylesheet" type="text/css" href="~WS-CSSURL(start)~">
   ...
</head>

The tag generates the reference to the minified file of the grouping for the browser:

<head>
   ...
   <link rel="stylesheet" type="text/css" href="/$WS/<ShopID>/websale8_shop-<ShopID>/benutzer/templates/Deutsch/../css_min/start_753e2835a4.min.css">
   ...
</head>

The name component 753e2835a4 is the URL fingerprint. It changes with each new version of the grouping. Reference: WS-CSSURL()

An external CSS file must not contain WEBSALE tags or text variables. The shop does not parse these files, so WEBSALE tags are not replaced. In addition, the folder is not considered by the text maintenance platform, so text variables also remain unreplaced. In these two cases, include the CSS inline in the desired template.

Including a grouping inline

Stylesheets do not have to be included via an external file. With the style HTML element you place them directly in the HTML document. This is the right approach if your CSS directives contain WEBSALE tags or text variables. The content of all files of a grouping is delivered by the WS-CSSInline() tag, in whose parentheses you specify the grouping ID. Example: the stylesheets of the start grouping are to be included inline inside the <body>.

<body>
   ...
   <style type="text/css">
      ~WS-CSSInline(start)~
   </style>
   ...
</body>

The tag outputs all stylesheets of the grouping for the browser:

<body>
   ...
   <style type="text/css">
      .text-normal {font-weight: normal;}
      .text-fett   {font-weight: bold;}
   </style>
   ...
</body>

Reference: WS-CSSInline()

Direct access during the design phase

When you include files via the PageSpeed tool, changes to CSS files only become visible after a click on the globe icon. When building a new shop, this intermediate step is time-consuming because it has to be repeated after every correction. For this case, there is direct access. Instead of the generated files in the css_min folder, the shop accesses the original files in the css_upload folder that are assigned to the grouping. Changes are then visible immediately after upload and a browser reload. Direct access consists of two parts. First, a setting in the shop configuration shop.config that determines when the mode applies. Second, a bracketing in the template that covers both cases.

Permanent direct access

With the following setting, the shop permanently accesses the original files. This setting is recommended while you are building a shop and making frequent changes.

<TopRank>
   ...
   ActivatePermanentDirectJSCSSTest    =    yes
   ...
</TopRank>

Direct access on demand only

With the value no, permanent direct access is deactivated. The shop then only accesses the original files when you call it with the parameter &jscssdirect-test=on. With &jscssdirect-test=off it returns to the files in the css_min folder.

<TopRank>
   ...
   ActivatePermanentDirectJSCSSTest    =    no
   ...
</TopRank>

Guide: Switching test modes of the shop on and off

Example: external CSS file with direct access

With direct access, the shop delivers each file of the grouping individually, not a combined file. The template must therefore iterate over all files of the grouping. The bracketing WS-DirectCSS() with the grouping ID is used for this, and inside it the loop @WS-DirectCSS, which delivers the path of one file per iteration via WS-DirectCSSURL. So that the template works in both states, the bracketing ST-DirectJSCSSTest encloses the direct access case and !ST-DirectJSCSSTest the normal case. Example: the start grouping has the two files font.css and color.css assigned to it.

<head>
   ...
   <!-- Bracketing for activated direct access -->
   {ST-DirectJSCSSTest}
      {WS-DirectCSS(start)}
         {@WS-DirectCSS}
            <link rel="stylesheet" href="~WS-DirectCSSURL~">
         {/@WS-DirectCSS}
      {/WS-DirectCSS(start)}
   {/ST-DirectJSCSSTest}

   <!-- Bracketing for deactivated direct access -->
   {!ST-DirectJSCSSTest}
      <link rel="stylesheet" href="~WS-CSSURL(start)~">
   {/!ST-DirectJSCSSTest}
   ...
</head>

Depending on the state, the browser either gets one reference per original file or a single reference to the minified grouping file:

<head>
   ...
   <!-- Activated direct access: all files of the grouping, not minified -->
   <link rel="stylesheet" href="/$WS/<ShopID>/websale8_shop-<ShopID>/benutzer/templates/Deutsch/../css_upload/font.css">
   <link rel="stylesheet" href="/$WS/<ShopID>/websale8_shop-<ShopID>/benutzer/templates/Deutsch/../css_upload/color.css">

   <!-- Deactivated direct access: one minified grouping file -->
   <link rel="stylesheet" href="/$WS/<ShopID>/websale8_shop-<ShopID>/benutzer/templates/Deutsch/../css_min/start_753e2835a4.min.css">
   ...
</head>

Reference: ST-DirectJSCSSTest Reference: WS-DirectCSS() Reference: WS-DirectCSSURL()

Example: inline inclusion with direct access

Inline-embedded stylesheets can also be used with direct access. Instead of the path, WS-DirectCSSInline here delivers the content of the respective file. Example: the stylesheets of the start grouping are to be included inline inside the <body>.

<body>
   ...
   <!-- Bracketing for activated direct access -->
   {ST-DirectJSCSSTest}
      {WS-DirectCSS(start)}
         <style type="text/css">
         {@WS-DirectCSS}
            ~WS-DirectCSSInline~
         {/@WS-DirectCSS}
         </style>
      {/WS-DirectCSS(start)}
   {/ST-DirectJSCSSTest}

   <!-- Bracketing for deactivated direct access -->
   {!ST-DirectJSCSSTest}
      <style type="text/css">
         ~WS-CSSInline(start)~
      </style>
   {/!ST-DirectJSCSSTest}
   ...
</body>

With direct access, the browser gets the unchanged content of the original files, and in the normal case the minified content of the grouping:

<body>
   ...
   <!-- Activated direct access: original content, not minified -->
   <style type="text/css">
      .text-normal {
         font-weight: normal;
      }
      .text-fett   {
         font-weight: bold;
      }
   </style>

   <!-- Deactivated direct access: minified content of the grouping -->
   <style type="text/css">
      .text-normal {font-weight: normal;}
      .text-fett   {font-weight: bold;}
   </style>
   ...
</body>

Reference: WS-DirectCSSInline()

Trying out new groupings in the design test mode

A new grouping does not have to be built into the live mode straight away. The bracketing ST-DesignTest is available for all integration variants described. This way, only you see the new assignment in the design test mode, while visitors continue to receive the previous version.

{ST-DesignTest}
   Assignment of the CSS files to be used in the design test mode
{/ST-DesignTest}

{!ST-DesignTest}
   Assignment of the CSS files to be used in live mode
{/!ST-DesignTest}

Reference: ST-DesignTest Guide: Switching test modes of the shop on and off

Debug mode for troubleshooting in the browser

If the CSS directives do not take effect as intended, troubleshooting in a minified file is tedious. Therefore, you can suppress the inclusion of the minified file via a URL parameter and use the non-minified version in the browser instead. The PageSpeed tool stores this version in the css_min folder at the same time as the minified file. If you include your CSS files via direct access, you do not need this mode. The browser gets the non-minified originals there anyway. To activate, append the parameter &jscssminified-test=off to any shop call. The shop must be in test mode for this.

https://www.xyz.de/?test=on&jscssminified-test=off

The browser then gets the non-minified version, recognizable by the missing .min in the file name:

<link rel="stylesheet" href="/$WS/<ShopID>/websale8_shop-<ShopID>/benutzer/templates/Deutsch/../css_min/start_753e2835a4.css">

With &jscssminified-test=on you return to the minified files:

https://www.xyz.de/?test=on&jscssminified-test=on

<link rel="stylesheet" href="/$WS/<ShopID>/websale8_shop-<ShopID>/benutzer/templates/Deutsch/../css_min/start_753e2835a4.min.css">

Guide: Switching test modes of the shop on and off

Including without the PageSpeed tool

Using the PageSpeed tool is not mandatory in WEBSALE V8s. You can also include CSS files in every template via a relative path or write stylesheets directly in the template. This route is simpler, but it does without minification and URL fingerprinting. When including via a relative path, the base element must be considered. It defines the base for all relative references and usually points to the subshop template directory, for example benutzer/templates/Deutsch.

<head>
   ...
   <base href="~URL-Template~">
   <link rel="stylesheet" type="text/css" href="../css_upload/styles.css">
   ...
</head>

Guide: base-href Guide: URL-Template

On this route too, use only the files in the css_upload folder. Automatic URL fingerprinting and automatic minification do not take place. You must do both manually after every change, otherwise the browser will deliver an outdated file from the cache.Here too: an external CSS file must not contain WEBSALE tags or text variables, because the shop does not parse these files and the text maintenance platform does not consider the folder. In these cases, include the CSS inline.

When including directly in the source code, the base element only matters if you include background images via background or background-image.

<body>
   ...
   <style type="text/css">
      .text-normal {font-weight: normal;}
      .text-bold   {font-weight: bold;}
      .background  {background-image: url(../images/bg.png);}
   </style>
   ...
</body>

Notes on Bootstrap CSS

The files bootstrap.css and bootstrap.min.css as well as bootstrap-theme.css and bootstrap-theme.min.css provided in the sample shop are the unmodified standard files from Bootstrap with all directives and components. Apart from the email templates, all sample shop templates already use bootstrap.min.css and bootstrap-theme.min.css. If you want to adapt the sample shop to your design, use the customizing of Bootstrap for this primarily. We advise against changing the Bootstrap files delivered, because this will cause you to lose Bootstrap’s update and compatibility capabilities. If a design adjustment cannot be solved via customizing, override the Bootstrap directives. Both routes described above are available for this: the external CSS file and inclusion directly in the source code. Guide: Bootstrap

WEBSALE class names and IDs

All HTML elements generated automatically by WEBSALE V8s are given class names and IDs. One example is the paging navigation for product lists:

This tag creates a complete table with links, numeric values, and graphics. You can influence the design via stylesheet using the assigned class names and IDs, without having to change the generated markup itself.

Do not use the class names and IDs assigned by WEBSALE for your own HTML elements. Otherwise your directives will unintentionally also apply to the generated elements.

An overview of all assigned class names and IDs can be found in the following references:

Styles for products
Styles for product ratings
Styles for paging in categories and products
Styles for the currency dropdown list
Styles for login
Styles for billing and different shipping addresses
Styles for bank details
Styles for multiple customer data
Styles for Trusted Shops information
Styles for wish list variants
Styles for error messages in online clearing
Styles for paid additional services
Styles for storable shopping carts
Styles for the WWS information data interface
Styles for wish list
Styles for consent to advertising
Styles for product comparison
Styles for filters at category level

SEO-optimized delivery of CSS files

The performance of a page is one of the most important criteria for a good search engine ranking. Because of their size, CSS files are particularly significant in this regard. The following sources explain how you can keep your design and still achieve good performance.

Optimize CSS delivery: Minify resources and Optimize CSS delivery
Use browser caching
URL fingerprinting and caching headers
Prioritize visible content

​Folder structure

​Creating a CSS file

​Including with the PageSpeed tool (recommended)

​Activate the PageSpeed tool

​Grouping CSS files

​Including a grouping as an external CSS file

​Including a grouping inline

​Direct access during the design phase

​Permanent direct access

​Direct access on demand only

​Example: external CSS file with direct access

​Example: inline inclusion with direct access

​Trying out new groupings in the design test mode

​Debug mode for troubleshooting in the browser

​Including without the PageSpeed tool

​Notes on Bootstrap CSS

​WEBSALE class names and IDs

​SEO-optimized delivery of CSS files

Folder structure

Creating a CSS file

Including with the PageSpeed tool (recommended)

Activate the PageSpeed tool

Grouping CSS files

Including a grouping as an external CSS file

Including a grouping inline

Direct access during the design phase

Permanent direct access

Direct access on demand only

Example: external CSS file with direct access

Example: inline inclusion with direct access

Trying out new groupings in the design test mode

Debug mode for troubleshooting in the browser

Including without the PageSpeed tool

Notes on Bootstrap CSS

WEBSALE class names and IDs

SEO-optimized delivery of CSS files