agencies

Setting Up Styla CSS

This page shows you how to set up CSS for a newly created Styla domain. It also discusses the structure of such settings and gives you tipps on how to do this in an efficient way.

Contents:

Introduction
Using the tool
Theme settings
Module settings
Hints for saving time and effort
Examples set up by Styla
Setting up module presets

Introduction:

Styla CSS works in separation from the CSS of a parent website on which Styla content is embedded, Styla CSS classes are very specific in order for them not to be influenced by the external CSS. So any style rules needed for Styla content to match the appearance of the parent website need to be set up separately.

Styla sets up CSS for every new client during the onboarding phase, based on their CI guides and website front-end where Styla content will be embedded on. You will be able to do this for your clients using Styla account management tool - the Organization Manager.

Styla CSS 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.

Styla CSS levels:

Desktop and mobile:

One more thing important for you to understand on how CSS is applied to Styla content is that on any of the four levels above rules are applied to all view port widths and then can be overridden for mobile widths specifically.

Styla front-end only 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.

Using the Tool

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

You configure CSS and other settings directly via JSON editor. We are aware that this is not the most efficient and user-friendly way but as Styla is developing their product at a very high pace, this approach lets us save some effort on a user interface that would need to be updated every time a new feature is released. Also, JSON data may contain thousands of fields and such a UI would be extremely detailed.

A proper user interface to configure CSS per domain will probably be released in the future.

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 front-end 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 front-end. 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).

Once your CSS has been approved, you can switch the avoid_font_loading feature flag on. This will prevent Styla content from loading external font files when embedded on the parent website while still load them in the Editor.

Leading and line height

Instead of directly setting up font-size and line-height for each font format, Styla front-end 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.

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.

The bodyCopy is the most important format and should always be defined. It is per default used for every module paragraph text and inherited by many other fields, for instance, price and product name fields in Product module.

Colours

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.

Colour 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.

Max widths, page margins, gutters examples:

The smallScreenMaxWidth sets the only breakpoint for Styla content, usually separating mobile phone layouts from any wider ones. You can modify it in Theme settings by setting a different pixel value if you want smallScreen overrides to kick in on a lower or higher width. The default is 767px.

Other settings of importance

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.

templateModuleIds - this array holds references to preset modules that can be used by this domain. 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 domain to use presets you've created for another one.

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. The best way to start with it is by creating a page with each of 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.

In case lack of a specific HTML element in Styla DOM is limiting implementation of your design, try adding pseudoelements in Module settings. For every HTML element on every module you can set :hover or :after or :nth-of-type(n). This is the only way to add some custom elements into Styla DOM.

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:
"backgroundPosition": "93% center",
"boxShadow": "0 2px 6px 0 rgba(0, 0, 0, 0.12)",
"fontSize": "1.4em",
"width": "calc(100% - 60px)"
and you use strings to reference Styla variables too:
"backgroundColor": "{colors.primary}",
"fonts.formats": "price"

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:
"bottom": 0,
"marginTop": -1.2,
"paddingLeft": 0.5

Many non-CSS settings take Boolean values, some of them are numbers or strings:
"isExternalLink": false,
"priceMinFractions": 2,
"priceTemplate": "#{price} €".

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 on 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 textLayer container) 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.

Editorial Shopping:

This is a very complex module in terms of HTML and needs JavaScript to work as intended. It features overlays displaying on clicking pins that users place manually on a background image, so it's complex in terms of Editor UI too. Same as Product and Product Details modules, it uses product data provided via Styla Product API.

Settings:

• pinImageWidth - sets width (in pixels) for product image on the overlay,
• priceMinFractions - sets a minimal number of characters to be used price fractions (cents, pennies etc.), the default is 1,
• priceTemplate - sets template for displaying price, will only be applied if no such field delivered by Styla Product API, can also be changed with the module's UI in the Editor
• productClassification - selects one of fields to display label above product name with: brand or category, will only work if these fields are provided by the Product API, can also be changed with the module's UI in the Editor
• showOldPrice - outputs old price next to current price, will only work if this field is provided by the Product API, the default is true

Feed:

This module is what the "Your Stories" from the modules list in the Editor. It displays a feed consisting of pages with the type: story and has multiple settings that are really hard to customise as the appearance of the feed depends on all of them and almost each of them influences the others. You might need Styla's help to make this module look exactly as you need it.

Settings:

• copyMinWords - intro text won't be rendered for a story if number of words lower than set here,
• copyMaxWords - intro text will display a (...) marker for stories with more words than set here,
• imageSelectionVariant - sets a template for sourcing content and product images into story in the feed. The possible values are: DEFAULT, FIRST_COLLAGE, FIRST_IMAGE, FIRST_COLLAGE_AND_ALL_PRODUCTS, FIRST_COLLAGE_AND_SECOND_COLLAGE_PRODUCTS, MAX_IMAGES, MAX_PRODUCTS_AND_MAX_VISUALS
• showCTA - displays a "read more" button for each story, the default is false,
• storyMarginHorizontal - sets margins (in base units) on the left and right of a story
• storyMarginVertical - sets margins (in base units) above and below a story

In the layouter node:

• storySizeScale - customises story size, the default is 1, the minimum is 0,
• maxRelevance - sets number of headline sizes for story titles in the feed, possible values: 1, 2, 3 (the default),
• infiniteScroll - sets the module to display an endless feed loading new pages on scrolling down, the default is true,
• useGrid - changes the feed layout to CSS grid with equal space and shape assigned per each image and all stories rendered in the same layout. This overrides most other settings and changes the CSS classes names for headlines and intro copy. The default number of columns is 3 but can be changed with:

"feedGrid": {
   "all": {
     "gridTemplateColumns": "repeat(4, 1fr)"
   }
}

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 only settings you always want inherited here (example: a font format).

Product:

This module displays a list of products populated with product images and text field sourced via Styla Product API. Editor UI for its settings features several switches, the most important ones being three layout variants: slider, grid, spread, each of them resulting in a different HTML structure and CSS classes. Editor users can also change number of products per row easily. Therefore you don't need to set these in Module settings JSON.

There are some quite complex calculations done to count product container sizes depending on how many products displayed per row, so if you will need to change paddings around them or apply some borders/shadows to get a very specific look, you might need to hardcode them for 3, 4 or 5 products per row.

Settings:

• isExternalLink - opens product details page in the same or new tab, the default is true - new tab,
• imageBoxRatio - tailors product container aspect ratio to match product images coming from the Product API, you can calculate it by dividing pack shot height by ist width, the default is 1, so if you use portrait images with it, these will have lots of spaces on the left and right,
• priceMinFractions - sets a minimal number of characters to be used price fractions (cents, pennies etc.), the default is 1,
• priceTemplate - sets template for displaying price, will only be applied if no such field delivered by Styla Product API, can also be changed with the module's UI in the Editor
• productClassification - selects one of fields to display label above product name with: brand or category, will only work if these fields are provided by the Product API, can also be changed with the module's UI in the Editor
• showControls - forces slider arrows to be always displayed on mobile view ports,
• showHoverIndication - switches the little zoom-out effect and "product details" button showed on hovering a product, the default is true,
• showOldPrice - outputs old price next to current price, will only work if this field is provided by the Product API, the default is true

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 is a rarely used module consisting of a product slider, product text with multiple fields and a button. It also can display external product content fetched via APIs: BazaarVoice (product reviews) and Commerce Connector (links to external shops selling the specific SKU). Here's an example.

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 a banner with an .mp4 video file in the background. Same as banner, it display a text container with CTA buttons that can be customised with the Editor UI.

Remember that you can override every general setting from all node in smallScreen just for mobile views. Even without any explicit settings in smallScreen most modules will look differently once you make you shrink your browser window below 767px as they inherit a set of CSS for this media query from default Layout Engine app settings. This is especially valid for Banner, Product and Editorial Shopping modules.

Inspecting Styla content

When inspecting Styla HTML with your browser developer tools, you will see CSS classes and properties applied to each of them on different levels. Classes will almost always include one of the modules' names and then a specific HTML element name, separated by a couple underline characters.

This information is enough for you to first test applying some CSS properties in your browser window and then apply these in module settings JSON.

Still, there are some HTML elements/CSS classes in Styla DOM for which you won't be able to apply custom CSS rules. You can recognize them by the initial part of their class names not matching any of the modules above. Here's an example:

While you can modify modules' appearance in many different ways, the only two ways to change layout rows that contain modules are a) the Editor UI for row b) direct manual changes in page JSON structure. The latter is a bit risky operation and settings from a modified page can only be reused by copying the whole page.

Hints for saving time and effort

Please find some hints below on how to approach the whole process of setting up CSS for Styla domain. These are based on experience of the author of this guide and should help you save time and effort.

1. Insist on a briefing from the client on what typography settings, colours et.c they want to use. No briefing usually increases number of feedback rounds.
2. Prepare a page with collection of all modules the client is going to use. This will let them review all of them at once and provide you a consistent feedback.
3. This feedback will be even more relevant if they actually use the CSS to set up some pages themselves in the Editor and see how the style works with the content they have in mind.
4. Don't hardcode settings that can be changed with the Editor UI. This would make users frustrated as changing settings won't influence module appearance.
5. Use Styla's magazine-display service to see your CSS changes reflected without any caching. Paths will look like this: https://magazine-display.prod.us.magalog.net/prophet/area/{domain-name}/{page-path}. Alternatively you can use https://{domain-name}.styla.live/{page-path} which might not reflect CSS changes right away.
6. Review the parent website on which the Styla content is to be embedded to make sure the font-families you are to apply will display fonts from the website and that you set up the same colours in Styla CSS.
7. Use font formats and colour names when setting up modules. If you use font-site in px or em or enter colours directly as hex numbers, it will cost you more work to update them in several places. A client might want to completely redesign their website in the future.
8. Some modules will probably be rarely used so you can always set their custom CSS later.
9. If a client needs several variants of a module and cannot achieve a look their need with the Editor UI, you will need to create module presets for them. This effort only makes sense if presets will be reused.
10. Remember that each module type can be drag&dropped everywhere and displayed 1-3 per row. Therefore their CSS should be as universal as possible.
11. Whole pages with multiple modules arranged in a specific order can be used as page templates. Editor users can create copies of such pages and update content (text, images, products) on each instance. This will reduce work needed for drag&dropping several modules on a page and then updating their settings.
12. If you want to test something and are afraid of breaking your layout, create a copy of a module/page and modify CSS in Editor JSON directly, which will only influence this page/module. You can send such copies for client's approval - they can be published but stilled not linked to anywhere hence not indexed by search engines.

Examples set up by Styla

The below .zip pack contains Theme and Module settings for a couple clients set up by Styla team. You can copy&paste this JSON into your domain Theme and Module settings to see how various properties can influence module content.

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.

This is how you create a preset:

1. Log in as the target user/domain, 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. 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 domain's Module settings.
5. 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.

Presets that you set in the way described above are added in the templateModuleIds JSON node in Theme settings, as in the example below:

"templateModuleIds": [
  1363771,
  1364397,
  1364398
],

You can copy this into another domain to reuse the presets.
Also, make sure you update these settings if you're editing JSON in a local file. If you remove or don't include this node, the Editor won't display your presets for this specific domain.