Styling a Storefront

Introduction

Styla expects partners agencies to set up the styling for every new client during the onboarding phase, based on the client's CI guides. This can be done via our account management tool - the Organization Manager.

Styling levels

Styling can be applied on several levels, depending on how specific a rule should be. Each of the levels inherits settings from its parent and can override them for its own scope.

Breakpoints

Any of the four levels rules above are applied to all view port widths and then can be overridden for mobile widths specifically.

Styla Frontend features one breakpoint applied with standard media queries. This breakpoint is set per default to 767px and can be modified in Theme settings. This means there is no intermediate breakpoints you'd normally use to apply a different CSS to tablets, laptop screens etc.

You can apply any CSS property (not just widths, margins or font-sizes) to any Styla HTML element separately. This is in line with the Editor UI which lets users override certain settings from desktop on mobile.

Organization Manager (admin.styla.eu)

The Organization Manager tool in which you create new organizations, storefronts and users, is also where you configure CSS per storefront. You do this in the THEME SETTINGS and MODULE SETTINGS tabs:

Open

THEME SETTINGS in Styla Admin/Organization Manager

Theme settings

This is where settings affecting any module are set. This includes typography, colours, sizes, gutters etc. They are inherited and can be modified on lower CSS levels.

Base unit:

Almost all sizes in this tab are defined in base unit which itself is defined in pixels. You define it by simply setting: "baseUnit": 10, on the highest JSON level. Setting it to 10 will make every other setting multiply its value by 10px. This way you can make every CSS property larger/smaller by changing this one setting. This will not be possible if you use px, rem, vw or any other CSS unit on a (lower) module level. These would keep their values in standard CSS units no matter what you change the base unit to.

Defaults: all: 8, smallScreen: 7

Defining fonts families:

Styla can use external sources of font files to be loaded by Styla frontend and Editor preview. Setting them up is only needed for displaying text with a specific font outside of the parent website. Styla content embedded on a website will use font files loaded by this website, so the only thing you need to set up for such case is proper font-family rules.

However, you may need to load external font files to demo content and approve the CSS with your client - even before Styla content has been embedded on the website and is able to use the external font files.

Setting font-family without loading external fonts:

The only thing you need is to set up a list of font names that will populate the font-family CSS property in Styla frontend. They need to match font files loaded by the website or installed on user's machine, otherwise browser will fall back to whatever is defined in the fallback field.

Setting font-family and loading external font files:

Obviously, you need to host font files (best: .woff or .wof2) somewhere and use the same font family names as defined in your CSS. You can upload both the CSS file and fonts on your static files for this use specifically, or just reference the files your website uses.

Styla has a loader mini app for Google Fonts and will load them via Google Fonts API as long as you set them up correctly (example below).

Leading and line height

Instead of directly setting up font-size and line-height for each font format, Styla frontend needs them to be configured in leading and lineHeight fields, which will result in the above CSS properties in pixels. It's done this way to enable baseUnit changes influence any text size.

The leading field defines overall text line height, from the top to the bottom of every possible character. It is counted by multiplying the value you set by baseUnit. The lineHeight defines a fraction of font-size that the lineHeight will be. It's a bit hard to get the math done in your head, so we've created a spreadsheet for you to convert the standard CSS properties into the Styla properties and the other way round. Add it to your bookmarks if you are going to use it often.

Font formats

Once you've set up your font-families, you use them to set up font formats. These are typography definitions which you can reuse on any number of modules and presets by adding a 
"fonts.formats" : "formatName" reference there. You can then update this format for all modules using it by changing its properties in Theme settings.

Font formats you define here can also be selected by users in the Editor in the "Advanced" tab for any module. Selecting them from the below dropdown list will make a specific field on your module load typography properties from the format assigned.

Open

Font format examples:

The below JSON node shows how to set them up. Please don't use any non-typography CSS settings (paddings, colours, transitions) there. They won't work as they are applied on the module level.

As you can see, properties can be set just for mobile views in the smallScreen node.

Color

The same way you create font formats to be reused in many different modules, you configure colours to be able to reference their name and change them in Theme settings for any module using it. You set them up by giving them a name and then assigning a CSS hex or RGB scheme value.

You can then reference these names as variables when setting up in any properties. For instance: "color": "{colors.black}" or "borderBottomColor": "{colors.secondary}". This does not work in shorthand definitions, where you need to use a full hex number.

Colours you define here can also be selected by users in the Editor in the "Advanced" tab for any module. Selecting them from the below dropdown list updates will apply a CSS property with this colour to a given HTML element.

Examples

The contrast is per default used for all background elements and in 90% of cases will be white. The bodyCopy will per default be applied to paragraph copy and in 90% of cases will be black or dark grey. Some other names like primary or link will also be automatically applied to some HTML elements in some modules unless you override them in module settings.

As you can see below, every CSS-compliant colour notation can be used, including colour hex and RGB numbers with opacity.

Max widths, page margins and gutters

Theme settings feature a property for setting a max-width for any Styla content (which will be used for the row "Default Width" in Editor) and a separate one for the "Smaller" width. These are set in pixels. "Full Bleed" will always use 100% of browser width unless Styla content sits in an external HTML that has its own width or margins/paddings set.

It is good practice to set the pageMaxWidth to the same pixel value parent website uses. This will make content appear more or less the same in the Editor. In addition, you can set a pageMargin value in base units which will apply paddings on the left and right, visible once you resize the browser window below the pageMaxWidth.

Values from the gutters array populate the dropdown in the Editor where you can apply margin-top to layout rows, spaces between modules in a row and external paddings for a row background. They are defined in base units and can be set for desktop and mobile separately. This lets you space rows or modules differently on smaller screens.

Applying row margin-top in the Editor:

Applying row background padding in the Editor:

Applying row inner padding in the Editor:

Other settings of importance

Quality compression for Images

imgixParams - you can modify image compression across all pieces of content with it. The setting will be used by Styla's imgix account, which provides image analysis and manipulation. Useful if your client tells you the load sizes/times for Styla content are too big. The default is 45.

Using presets from other storefronts

templateModuleIds - this array holds references to preset modules that can be used by this storefront. It is updated automatically every time you add a new preset in the presets management list in the Editor. You can add new IDs manually if you want a storefront to use presets you've created for another one.

Max width for Texts

textMaxWidth - this field sets a max-width value (in base units) for the textWrapper HTML div in which content of Text module sits. The default is 88.

Module Settings

Once Theme settings have been configured, you can start configuring Module settings. We recommend creating a page with each of the module types you or your client want to use in the future. This way you will see how each of them looks with only theme settings applied (typography, colours and spacings).

The next step would be to start updating settings for each specific module. You do this by applying CSS and other settings in a JSON node named after the module.

Each module node contains a styles subnode, where CSS is applied and a settings subnode where non-CSS settings are applied. These include some switches/feature flags for which there is no UI in the Editor, some of them very client-specific features that Styla had been asked to develop for them.

CSS that you set for a module is delivered by Styla to your browser and will work as CSS on any other website. So any CSS property can be set and will be rendered, as long as your browser supports it. You can transform, animate objects, change their position, display and z-index properties - which of course can break module layouts.

Naming convention and property values

CSS properties are represented by JSON nodes named after them, but written in camel cases. So, for instance, align-content becomes alignContent. Property values, however, stay as in CSS, so flex-start does not change and if you want to set it, you write: "alignContent": "flex-start" in module styles JSON.

Most CSS properties should be set as strings, for instance:

and you use strings to reference Styla variables too:

However, any size properties that you normally set in px or em can be set in base units if you simply use numbers (positive or negative) to set them:

Many non-CSS settings take Boolean values, some of them are numbers or strings:

Any JSON you enter into the Organization Manager or Editor will be validated before saving. If it's invalid the changes won't be saved and will be lost, so if you're planning to enter a big chunk of JSON into the editor, better validate it somewhere else beforehand or back it up. The best approach is small incremental changes.

App

This is where you set CSS properties that you want inherited to every other module. Examples would be: a background colour and some instructions for browsers on how to render fonts.

Banner

This is one of the most complex and definitely the most often used module. It consists of a text and buttons (in textLayercontainer) and an image (in imageLayer container).

Carousel Controls

This is a generic module reused for carousel arrows left and right on Product slider and Product Details modules. If you change settings here, they will be updated for both of them.

Divider / Section Title

This is the module used for graphically separating some other modules (groups) while not being semantically a headline. When updating its appearance, you should pay attention to Section Title too, where default font format will come from and whose module settings will influence it too.

Image

A simple module consisting of an image and caption text. Still, you can adjust typography or caption background for it.

Navigation

This module displays a list with relative or absolute links that you set in the Editor. As the Editor features a very advanced UI with which you can set colours, paddings, margins and flex box properties, make sure you only apply settings you always want inherited here (example: a font format).

Slider

This actually is not a module, but a set of row settings that lets you manage every new slider row created in the Editor. The most important is selecting between three types of navigation available and setting an animation delay.

Settings:

• autoPlay - switches autoplay on/off, the default is true,

• autoPlayDelay - sets a delay (in milliseconds) between modules in the slider being animated,

• showArrows - switches navigation arrows left and right on/off, the default is false

• showDotNavigation - switches navigation dots below slider on/off, the default is true

• showThumbnailNavigation - switches navigation image thumbnails on/off, the default is false, you need modules with images in the slider for this to make sense

If you need to override these settings for a single slider instance, you need to do this in. page JSON directly. There is currently no Editor UI for doing this.

Product details

This module consisting of a product slider, product text with multiple fields and a button.

Settings:

• autoPlay - switches autoplay on/off, the default is true,

• autoPlayDelay - sets a delay (in milliseconds) between product images in the slider being animated

• arrowsIconsSize - sets navigation arrows size (in pixels),

• infiniteScroll - switches animation looping on/off, the default is true,

• showArrows - switches navigation arrows left and right on/off, the default is false

• showDotNavigation - switches navigation dots below slider on/off, the default is true

• showThumbnailNavigation - switches navigation image thumbnails on/off, the default is false,

• targetRatio - sets a target shape to which product images will be autocropped to fit into the slider, the default is 1 (square), 0.5 is landscape rectangle, 1.5 portrait rectangle, 0 switches the autocropping off and uses the original image ratio,

• transitionDuration - sets CSS transition time (in milliseconds)

Text

A very straightforward module consisting of a text field for which background and paddings can be customised with the Editor UI. Its width is per default set to 88 base units, which you can change in Theme settings.

Text on video

This module is a banner with an .mp4 video file in the background. Same as banner, it displays a text container with CTA buttons that can be customised with the Editor UI.

All the defaults and settings as .json files

In order to make working with Styla easier for you, we prepared some .json files with all the default theme and module settings and inline comments where needed. You can download them as a .zip pack below.

One pair of files is a valid JSON with all the defaults while the other one in addition contains comments hence does not validate but will probably be even module useful.

Download a .zip pack with examples here.

Setting up Module Presets

If your client need several appearance variants of the same module and cannot achieve it with the default set of presets available for every client, you will need to create a set of custom presets for them.

As the Editor features a UI to create and manage such presets, clients themselves can create presets there. But the usual UI in the Editor does not enable them to apply any CSS property to any HTML element. Therefore, you will need to set up some more advanced things directly in module JSON data.

Here’s how you create a preset:

1. Log in as the target user/storefront, click your user name top-right, then "Preset Manager" on the overlay menu.

2. Click "the Create" button top-left of the list. Then select module type from the dropdown, fill in the new Preset's name and click "Create" bottom-right.

3. Configure any CSS properties you can with the usual Editor UI on the next screen and click "Save changes" top-right.

4. Anything you cannot configure with the UI, you need to enter into this module's styles JSON directly.

5. Click the "edit as JSON" button bottom-left or simply add /json to the page's URL and then add nodes for HTML elements and their CSS properties as you'd do in the storefront's Module settings.

Once you are done, save the changes and check desktop and module preview if the modules looks all right. You will probably need to go through several iterations.
Once this is done, the CSS and other settings from the preset you've just created can be applied to any other module of the same type with the "Presets" dropdown in the "Settings" tab. They will be saved in the "presets" node of its JSON data and merged to any other CSS it already has set. In case the same CSS property is set differently on both of them, the original settings in the module will prevail, being on a lower-level.

The preset that you've created will be available in the "Preset Manager" until you remove it. You can modify its JSON data and the changes will be reflected on any module you apply the preset to. The changes won't be automatically reflected on the modules you'd applied the preset to before. You'll need to re-apply it.