Cascading Style Sheets with RenoirSt

2.1.1. Lengths, Angles, Times and Frequencies

The library provides out-of-the-box support for the length, angle, time and frequency units in the CSS spec. There are extensions for Integer and Float classes allowing to obtain lengths.

The supported length units are:

• em relative to font size
• ex relative to "x" height
• ch relative to width of the zero glyph in the element's font
• rem relative to font size of root element
• vw 1% of viewport's width
• vh 1% of viewport's height
• vmin 1% of viewport's smaller dimension
• vmax 1% of viewport's larger dimension
• cm centimeters
• mm millimeteres
• in inches
• pc picas
• pt points
• px pixels (note that CSS has some special definition for pixel)

The supported angle units are:

• deg degrees
• grad gradians
• rad radians
• turn turns

The supported time units are:

• s seconds
• ms milliseconds

The supported frequency units are:

• Hz Hertz
• kHz KiloHertz

RenoirST also supports the creation of percentages: 50 percent is mapped to 50% in the resulting CSS.

Some properties require integer or floating point values. In these cases just use the standard Pharo integer and float support. For example:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div ]
   with: [ :style | style zIndex: 2 ];
   build

2.1.2. Colors

The library supports abstractions for properties requiring color values. The shared pool CssSVGColors provides easy access to colors in the SVG 1.0 list, and the abstractions CssRGBColor and CssHSLColor allow the creation of colors in the RGB and HSL spaces including alpha support.

For example,

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div ]
   with: [ :style |
      style
         backgroundColor: CssSVGColors aliceBlue;
         borderColor: (CssRGBColor red: 0 green: 128 blue: 0 alpha: 0.5) ];
         build

evaluates to:

div
{
   background-color: aliceblue;
   border-color: rgba(0,128,0,0.5);
}

In a real scenario you should avoid hard coding colors as in the examples. It is recommended to put colors in objects representing a theme or something that gives them a name related to your application.

RGB-Colors also support percentage values:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div ]
   with: [ :style |
      style borderColor: (CssRGBColor red: 0 percent green: 50 percent blue: 0 percent) ];
   build

evaluates to:

div
{
   border-color: rgb(0%,50%,0%);
}

Notice the difference in the used message because there is no alpha channel specification.

2.1.3. Constants

A lot of values for CSS properties are just keyword constants. This support is provided by the classes CssConstants and CssFontConstants.

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div ]
   with: [ :style | style textAlign: CssConstants justify ];
   build

evaluates to:

div
{
   text-align: justify;
}

2.1.4. Several Property Values

Some properties support a wide range of values. For example the margin property can have 1, 2 , 3 or 4 values specified. If you only need one value, just pass it as a parameter. For more than one value, use an array:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div ]
   with: [ :style | style margin: { 2 px. 4 px } ];
   build

evaluates to:

div
{
   margin: 2px 4px;
}

2.1.5. URLs

ZnUrl instances can be used as the value for properties requiring an URI. Both relative and absolute URLs are accepted. A relative URL is considered by default relative to the site root.

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div class: 'logo' ]
   with: [ :style | style backgroundImage: 'images/logo.png' asZnUrl ];
   declareRuleSetFor: [ :selector | selector div class: 'logo' ]
   with: [ :style | style backgroundImage: 'http://www.example.com/images/logo.png' asZnUrl ];
   build

Evaluates to:

div.logo
{
   background-image: url("/images/logo.png");
}

div.logo
{
   background-image: url("http://www.example.com/images/logo.png");
}

To use a URL relative to the style sheet, send to it the message relativeToStyleSheet.

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div class: 'logo' ]
   with: [ :style | style backgroundImage: 'images/logo.png' asZnUrl relativeToStyleSheet];
   build

Evaluates to:

div.logo
{
   background-image: url("images/logo.png");
}

2.3.1. Mathematical Expressions

The library provides support for math expressions using the CssMathExpression abstraction:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div ]
   with: [ :style | style margin: (CssMathExpression on: 2 pc) / 3 + 2 percent ];
   build

evaluates to:

div
{
    margin: calc(2pc / 3 + 2%);
}

2.3.2. Toggling Between Values

To let descendant elements cycle over a list of values instead of inheriting the same value, one can use the CssToggle abstraction:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector unorderedList unorderedList ]
   with: [ :style | style listStyleType: (CssToggle cyclingOver: { CssConstants disc. CssConstants circle. CssConstants square}) ];
   build

evaluates to:

ul ul
{
   list-style-type: toggle(disc, circle, square);
}

2.3.3. Attribute References

The attr() function is allowed as a component value in properties applied to an element or pseudo-element. The function returns the value of an attribute on the element. If used on a pseudo-element, it returns the value of the attribute on the pseudo-element's originating element. This function is supported using the CssAttributeReference abstraction and can be used simply providing an attribute name:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div before ]
   with: [ :style | style content: (CssAttributeReference toAttributeNamed: 'title') ];
   build

Evaluates to:

div::before
{
   content: attr(title string);
}

RenoirST allows for providing the type or unit of the attribute (if no type or unit is specified the string type is assumed):

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div  ]
   with: [ :style |
      style width: (CssAttributeReference
         toAttributeNamed: 'height'
         ofType: CssLengthUnits pixel) ];
   build

evaluates to:

div
{
   width: attr(height px);
}

Additionally, it is possible to provide a value to use when the attribute is absent:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div before ]
   with: [ :style |
      style content: (CssAttributeReference
      toStringAttributeNamed: 'title'
      withFallback: 'Missing title')
   ];
   build

evaluates to:

div::before
{
   content: attr(title string, "Missing title");
}

2.3.4. Gradients

A gradient is an image that smoothly fades from one color to another. Gradients are commonly used for subtle shading in background images, buttons, and many other places. The gradient notations described in this section allow an author to specify such an image in a terse syntax. This notation is supported using CssLinearGradient and CssRadialGradient abstractions.

To represent a simple linear gradient from a color to another, send the fading: message to CssLinearGradient with the two colors in an array as a parameter:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [ :selector | selector div ]
   with: [ :style | style background: (CssLinearGradient
      fading: { CssSVGColors yellow. CssSVGColors blue }) ]

The above code evaluates to:

div
{
   background: linear-gradient(yellow, blue);
}

By default, a gradient's direction is from top to bottom. To specify a different direction, the author can use the to:fading: message instead:

CssLinearGradient
   to: CssConstants right
   fading: { CssSVGColors yellow. CssSVGColors blue }

The above code will result in a gradient with yellow on the left side and blue on the right side. The equivalent CSS is:

linear-gradient(to right, yellow, blue);

To specify a diagonal direction, an array must be passed as the to: argument:

CssLinearGradient
   to: { CssConstants top. CssConstants right }
   fading: { CssSVGColors yellow. CssSVGColors blue }

The above code will result in a gradient with blue in the top right corner and yellow in the bottom left one. The equivalent CSS is:

linear-gradient(to top right, yellow, blue);

Directions can also be specified as an angle by sending the rotated:fading: message:

CssLinearGradient
   rotated: 45 deg
   fading: { CssSVGColors yellow. CssSVGColors blue }

The above code maps to:

linear-gradient(45deg, yellow, blue);

Gradients can be fine-tuned by manipulating so-called color stops:

CssLinearGradient
   to: CssConstants right
   fading: {
      CssSVGColors yellow.
      CssColorStop for: CssSVGColors blue at: 30 percent }

The above code maps to:

linear-gradient(to right, yellow, blue 30%);

This results in a linear gradient from left to right with yellow at the left side and plain blue from 30% (of the horizontal line) to the right side. More than two colors can be passed as argument to fading:. This can be used to create rainbows:

CssLinearGradient
   to: CssConstants right
   fading: {
      CssSVGColors red.
      CssSVGColors orange.
      CssSVGColors yellow.
      CssSVGColors green.
      CssSVGColors blue.
      CssSVGColors indigo.
      CssSVGColors violet.
   }

This maps to:

linear-gradient(to right, red, orange, yellow, green, blue, indigo, violet);

To create radial gradients, the author must send messages to CssRadialGradient. For example,

CssRadialGradient fading: { CssSVGColors yellow. CssSVGColors green }

maps to:

radial-gradient(yellow,green)

This results in a radial gradient with yellow at the center and green all around. Coordinates can be passed to both the first and second parameters of the elliptical:at:fading: message:

(CssRadialGradient
   elliptical: {20 px. 30 px}
   at: { 20 px. 30 px}
   fading: { CssSVGColors red. CssSVGColors yellow. CssSVGColors green })

This maps to:

   background: radial-gradient(20px 30px ellipse at 20px 30px, red, yellow, green);

To make the gradient repeatable, just send to it the message beRepeating. For Example:

(CssRadialGradient fading: { CssSVGColors yellow. CssSVGColors green }) beRepeating

renders as:

repeating-radial-gradient(yellow, green);

2.3.5. Box Shadows

Box Shadows are supported with CssBoxShadow abstraction. This abstraction simplifies the use of the box-shadow property.

CssBoxShadow
   horizontalOffset: 64 px
   verticalOffset: 64 px
   blurRadius: 12 px
   spreadDistance: 40 px
   color: (CssSVGColors black newWithAlpha: 0.4)

evaluates to:

64px 64px 12px 40px rgba(0,0,0,0.4)

Several shadows can be combined:

(CssBoxShadow horizontalOffset: 64 px verticalOffset: 64 px blurRadius: 12 px  spreadDistance: 40 px color: (CssSVGColors black newWithAlpha: 0.4)) ,
(CssBoxShadow horizontalOffset: 12 px verticalOffset: 11 px blurRadius: 0 px  spreadDistance: 8 px color: (CssSVGColors black newWithAlpha: 0.4)) beInset

Evaluates to:

64px 64px 12px 40px rgba(0,0,0,0.4), inset 12px 11px 0px 8px rgba(0,0,0,0.4)

3.4.1. Language Pseudo-Class:

The :lang(C) pseudo-class can be used by sending the message lang::

CascadingStyleSheetBuilder new
   declareRuleSetFor: [:selector | (selector lang: 'es') > selector div ]
   with: [:style | style quotes: { '"«"'. '"»"' }  ];
   build

evaluates to:

:lang(es) > div
{
    quotes: "«" "»";
}

3.4.2. Negation Pseudo-Class:

The negation pseudo-class, :not(X), is a functional notation taking a simple selector (excluding the negation pseudo-class itself) as an argument. It represents an element that is not represented by its argument. For more information take a look at the CSS spec.

This selector is supported sending the message not:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [:selector | selector button not: (selector havingAttribute: 'DISABLED') ]
   with: [:style | style color: CssSVGColors blue ];
   build

button:not([DISABLED])
{
   color: blue;
}

3.4.3. Structural Pseudo-Classes

These selectors allow selection based on extra information that lies in the document tree but cannot be represented by other simpler selectors nor combinators.

The :root pseudo-class represents an element that is the root of the document. To build this kind of selector just send the message root to another selector:

CascadingStyleSheetBuilder new
   declareRuleSetFor: [:selector | selector root ]
   with: [:style | style color: CssSVGColors grey ];
   build

evaluates to:

:root
{
   color: grey;
}

The :nth-child(an+b) pseudo-class notation represents an element that has an+b-1 siblings before it in the document tree, for any positive integer or zero value of n, and has a parent element. For values of a and b greater than zero, this effectively divides the element's children into groups of a elements (the last group taking the remainder), and selecting the bth element of each group. The a and b values must be integers (positive, negative, or zero). The index of the first child of an element is 1.

In addition to this, :nth-child() can take a number, odd and even as arguments. The value odd is equivalent to 2n+1, whereas even is equivalent to 2n.

CascadingStyleSheetBuilder new
   declareRuleSetFor: [:selector | selector childAt: 3 n + 1 ]
   with: [:style | style color: CssSVGColors blue ];
   declareRuleSetFor: [:selector | selector childAt: 5 ]
   with: [:style | style color: CssSVGColors blue ];
   declareRuleSetFor: [:selector | selector childAt: CssConstants even]
   with: [:style | style color: CssSVGColors blue ];
   build

evaluates to:

:nth-child(3n+1)
{
   color: blue;
}

:nth-child(5)
{
   color: blue;
}

:nth-child(even)
{
   color: blue;
}

All structural pseudo-classes can be generated using the following messages: