Design customization

Attention. By using the recommendation widget, you accept the risks laid out in section 3.20 Offers. Before you start designing your template, we recommend reading the current advertising legislation, including the requirements set for mandatory advertisement elements and their size.

Use the visual code designer to configure the widget's design: choose the Design section and click the Code tab. We recommend using one of the preset templates if you don't yet have any experience with HTML and CSS.

  1. Main widget elements
  2. CSS class styles
  3. General design settings

Main widget elements

Each element corresponds to its own HTML tag.

Here is a simple template that uses all the widget elements:

<div class="wrapper">
  <div class="headline">Read also</div>
  <ya-units-grid cols="${grid_columns}" rows="${grid_rows}">
    <div class="image"><ya-unit-image /></div>
    <div class="title"><ya-unit-title /></div>
    <div class="desc"><ya-unit-desc /></div>
    <div class="domain"><ya-unit-domain /></div>
    <div class="meta">
                      <ya-unit-category class="category"/>
                      <ya-unit-date  class="date"/></div>
    <ya-unit-close />
  </ya-units-grid>
  <ya-recommendation-label />
</div>
You can create templates from your own custom design. Elements can be swapped without disrupting nesting or wrapped in other HTML tags. You can also remove any elements if you don't want them displayed in the widget. For example, you can remove the publication date by deleting the <ya-unit-date /> element.
Important.
  • However, you cannot delete <ya-units-grid> as it's required for the widget to work properly.
  • You can hide the publication category and only display the \"Ad\" label by adding the parameter ad-only to <ya-unit-category>.
  • You don't need to specify the CSS class for the <ya-unit-category> element, but you need one for the wrapper. This needs to be done so that styles are applied correctly to the \"Ad\" label when a category is missing, which happens if it's not been specified in the metatags or the ad-only parameter is enabled.

CSS class styles

CSS classes have multiple formatting styles:
  • headline — widget header
  • title — cell header
  • category — content category or the \"Ad\" label
  • wrapper — the overall appearance of the widget
  • grid-row — grid row
  • grid-item — grid cell
  • grid — grid
  • unit-wrapper — recommendation
  • unit-image — image used in recommendation
  • recommendation-label — widget label

You can also create your own CSS classes and customize their styles.

General design settings

This section lists general design settings which don't require any advanced markup skills.

Restricting the number of rows displayed
The restriction is useful for headers and recommendation descriptions. If you want to limit the number of rows displayed in the widget, wrap the element you need into the <ya-clamp> tag. For example:
HTML
Original header style:
<div class="title"><ya-unit-title /></div>
After limiting the number of displayed rows to 2:
<ya-clamp lines="2" class="title"><ya-unit-title /></ya-clamp>
Or
<div class="title"><ya-clamp lines="2"><ya-unit-title /></ya-clamp></
div>
Text formatting
You can use CSS to format your text. Choose the class of the element you wish to configure and change its values. For example:
Configuring text display
CSS
.headline {
  font-family: Helvetica, sans-serif; /* font */
  font-size: 18px; /* font size — 18 pixels */
  font-weight: bold; /* font thickness (weight) — bold */
  font-style: italic; /* font style — italics */
  line-height: 24px; /* line spacing — 24 pixels */
  letter-spacing: 1px; /* character spacing — 1 pixel*/
  text-decoration: underline; /* text decoration — underlined */
  text-transform: uppercase; /* text case — all uppercase */
  text-align: right; /* text alignment — right */
  color: #373e44; /* text color — dark gray */
  background: #fff; /* background color — white */
}

.category {
  color: #093; /* text color — green */
  font-size: 12px; /* font size — 12 pixels */
  text-transform: uppercase; /* text case — all uppercase */
}
Configuring margins
CSS
.headline {
  padding-top: 10px; /* top margin — 10 pixels */
  padding-right: 10px; /* right margin — 10 pixels */
  padding-bottom: 10px; /* bottom margin — 10 pixels */
  padding-left: 10px; /* left margin — 10 pixels */
}
Making a border around text
CSS
.headline {
  border: 1px solid #000; /* border: thickness — 1 pixel, border type — solid color, color — black */
}
Customizing the overall widget appearance
To customize your widget's overall appearance, such as the text background color or margins, you need to wrap all of the widget's code into the wrapper-class tag and set up parameters for that CSS class. For example:
HTML
<div class="wrapper">
  <ya-units-grid cols="${grid_columns}" rows="${grid_rows}">
  ...
  </ya-units-grid>
</div>
CSS
.wrapper {
  background: #fff; /* background color — white */
  padding: 10px; /* margins inside the border, all sides — 10 pixels */
  margin: 5px; /* margins outside the border, all sides — 5 pixels */
  border: 2px solid #000; /* border: thickness — 1 pixel, border type — solid color, color — black */
  border-radius: 6px; /* rounding the border's corners after 6 pixels */
}
Customizing the grid appearance

The <ya-units-grid> element is used to draw the grid based on parameters specified in the Grid size fields. You can only change the grid size using these fields.

However, you need to use a different method if you want to specify multiple grid sizes for different screens. For such cases, set the corresponding values in the sizes parameter. The last option with variables ${grid_columns}x${grid_rows} must be included. For example:
HTML
<ya-units-grid sizes="(max-width: 1024px) 2x2, (max-width: 600px) 2x1, ${grid_rows}x${grid_columns}">
Here is how grids are going to be matched to different screen sizes in this example:
  • A 2 × 1 grid will be displayed on screens less than 600 pixels wide.
  • A 2 × 2 grid will be displayed on screens between 601 and 1024 pixels wide.
  • Screens wider than 1025 pixels will display a grid based on the values set in the Grid size fields on the General tab.
Important. Keep in mind that you should set the number of displayed widget cells in HTML code. To specify the number of recommendations and ad places to load, change the values in the Grid size fields. For example, if you set the Grid size to 5 × 2 while the <ya-units-grid> element is configured to display a 2 × 2 grid for this screen size instead, then only 4 out of 10 loaded recommendations will be displayed. The opposite is also possible: if you have a 5 × 2 grid while the number of recommendations is set to 2 × 2, then the widget will display six empty cells.
The grid layout is configured via CSS classes grid, grid-row, and grid-item. For example:
CSS
.grid-row {
  margin-top: 10px; /* vertical distance between cells — 10 pixels */
}
.grid-item {
  margin-left: 20px; /* horizontal distance between cells — 20 pixels
*/
}
.grid {
  border: 1px solid #000; /* border around the grid: thickness — 1 pixel, border type — solid color, color — black */
}
Configuring cell design

You can use the unit-wrapper class to configure the background color or border for each cell. For example:

CSS
.unit-wrapper {
  background: #fff; /* background color — white */
  border: 1px solid #666; /* border: thickness — 1 pixel, border type — solid color, color — gray */
  padding: 5px; /* margins inside cell — 5 pixels */
  border-radius: 5px; /* rounding the border's corners after 6 pixels */
}

Cells that host content without images can have their own unique layout, which you can set using the class unit-wrapper.unit-without-image. For example:

CSS
.unit-wrapper.unit-without-image {
  background: #fff; /*  background color — white */
  border: 1px solid #666; /*  border: thickness — 1 pixel, border type — solid color, color — gray */
  padding: 5px; /* margins outside the border — 5 pixels */
  border-radius: 5px; /* rounding the border's corners after 6 pixels */
}
Setting up image layout inside a cell
To configure image layout in the HTML template, use the element <ya-unit-image>. You can set the image's aspect ratio with the ratio parameter. You can specify the path to a placeholder image (used when your content doesn't have any other images for display) with the src parameter. For example:
HTML
<ya-unit-image ratio="0.5" src="https://example.com/image/image.png">
You can set other parameters in CSS (such as the image's maximum height or the rounding of corners) by changing the parameters in the unit-image class. For example:
CSS
.unit-image {
  max-height: 200px; /* maximum height — 200 pixels */
  border-radius: 4px; /* rounding the border after 4 pixels */
}
Configuring the widget label
The <ya-recommendation-label> element sets the configuration of the label. If you delete the element from the template, the label won't appear in the widget. You can set your own label text using the text parameter. For example:
HTML
<ya-recommendation-label text="Recommendations" />
The label is aligned to the right and uses the color gray by default. You can change this parameters by configuring the recommendation-label CSS class. For example:
CSS
.recommendation-label {
  color: black; /* text color — black */
  text-align: left; /* aligning text to the left */
}