Styling Homepages and Dashboards Using CSS Variables

Instead of modifying the styles that are described in the previous topics, you can use CSS variables to style homepages, sections, and tiles.

The following table lists the various levels where CSS variables can be defined.

Level

Identified as Tag or Class/Selector

Description

Top of document

:root OR HTML tag

Top level of the HTML document (the HTML tag). Overall palette and theme definitions and functional CSS variables are defined at this level.

Homepage container

.pt_homepage

Overall homepage container of all homepages. Typically when styling you also want to avoid styling in personalization mode which would be done by this CSS selector - .pt_homepage:not(.persmode). Many overall CSS variables are set here including the homepage background and texture.

Dashboard container

.pt_apphomepage

Same level as homepage container, but it is for dashboard specific styling.

Individual homepage

.psc_hpmodel-A

There are a number of other style classes which are assigned at the individual homepage level (including portal-, node-, and tab- style classes). However, you typically apply the psc_hpmodel-A style at the overall homepage level (per expected usage). Defaults are set here for overall section and tile sizing or layout using CSS variables. You should note that the visible homepage will be the homepage that does not have the psc_invisible style associated at the same level as psc_hpmodel-A.

Container of all sections

.psc_hp-sections

This is the container section for all homepages.

Individual section

.psc_hpsection

Each section has this style class assigned along with the section name or ID as defined by the administrator.

Section tile collection container

  • .psc_hpsection

  • .nuitilegrid .ps_grid-body

Within the section is a DIV grid which has a grid body. This grid body is defined as a CSS grid where the individual tiles are contained and laid out. You can define CSS variables here to control tile sizing and layout for a specific section.

Individual tile container

.nuitile

Within the collection of tiles, you'll find the tiles. Tiles have two different levels: the overall wrapper used to layout the tiles in the collection and actionable tile area. The outer container is where tile styles are applied as well as the tile sizing styling based on the tile definition.

Individual tile actionable area

.nuilp

Within the tile container (.nuitile) is the actionable area (if the main hot spot is enabled, which is the default). It is here where focus is actually set when dealing with tiles. From this level and down will be the internal layout of the tiles. For this model many tiles will be laid out in a CSS Grid form.

The following CSS variables can be used in custom style sheets for a homepage, section, or tile to set values used within the psc_hpmodel-A styling. However, this is not an exhaustive list of CSS variables. This table lists the significant set of CSS variables.

CSS Variable

Applicable Level

Description

--pt-tile-max-width

  • Section

  • Tile

When set for elastic, simple list, and simple tiles, it specifies the maximum width the tiles can grow. Since this is typically applied to a collection of tiles, the section level is the usual place to specify this variable.

Example:

--pt-tile-max-width: calc(var(--pt-tile-spacing) * 2 + var(--pt-tile-image-size) + 35ch); /* tile padding plus image width plus 35 characters max */

--pt-tile-font-weight

  • Section

  • Tile

Undefined CSS variable by default, used to indicate the font-weight for tiles rendered as links. Typically used for special links rather than for an entire collection of links. Internally, the default for tiles rendered as link is font weight of 100 (or normal) due to fallback value since this CSS variable is not defined anywhere.

--pt-section-background

  • Homepage

  • Section

Sets the background for the section (all sections if set at the homepage; if those sections do not specify a color) when set at the section level. Use this variable if you want a complex background on not a simple color from the color palette (for example an image with a background color).

Example:--pt-section-background: var(--pt-theme-neutral-texture) repeat var(--pt-theme-neutral-10);

--pt-section-text-color

  • Homepage

  • Section

Sets the header and general text color for a section (or sections if set at the homepage level). Since this model typically does not involve collapsible section headers, there should be no need for a separate hover color.

--pt-section-link-text-color

  • Homepage

  • Section

Color to be used for links found in the section (or sections when defined at homepage level). Typically defaults to the same color as the section text color. Can be reset at the tile level by using psc_tile-simple-link for a special link text color.

--pt-section-border-color

  • Homepage

  • Section

Special decorative border color that appears below the section image. By default, there is not a border used around each section but a shadow around a section with this model. This variable must be used in conjunction with the --pt-section-border-style variable, which by default is set to None. Default value for this variable is the section text color. If the section is a transparent section, the default border color will also be transparent instead of the section text color.

--pt-section-border-style

  • Homepage

  • Section

Sets the border style for the section. Default value is None.

--pt-section-border-radius

  • Homepage

  • Section

Size of the border radius applied to a section.

--pt-section-shadow

  • Homepage

  • Section

Complete specification for the shadow of a section.

--pt-tile-separator-color

  • Homepage

  • Section

Special color used to separate tiles (typically used for sections that display tiles as a list).

--pt-hpsection-image-url

Section

While this property is typically populated through the section image check box on the non-collapsible section in the homepage definition, this variable can also be used within custom style sheets to provide dynamic control over a section image. For example, you can use this variable when the section background changes and you need to change the image for color contrast.

--pt-homepage-bottom-spacing

Homepage

Use to customize the lower spacing of the homepage. Normally, it is the same as the section spacing. It is used by the style psc_homepage-no-bottom-spacing to remove the gap for footer support.

--pt-homepage-text-color

Homepage

This variable is used to set the default text color for a homepage in general. This is important for transparent sections so that the text color can have a contrasting color with the homepage background. This variable is not defined in any delivered stylesheet but is available for use by application developers and customers to set the overall default text for the homepage for transparent sections.

--pt-tile-image-filter

  • Section

  • Tile

By default this variable is not defined (that is, set to None). This variable allows changes in a tile's primary image through CSS filter property. Useful for transparent tiles to attempt to manipulate images to support proper contrast against changes to the background without changing images (if possible).

Example: --pt-tile-image-filter: contrast(3) invert(1);

--pt-custom-homepage-background

Homepage

By default, this variable is not defined (that is, set to transparent). When set at the homepage level, this variable allows applications to have different homepage backgrounds for different pages.

Example: --pt-custom-homepage-background: var(--pt-theme-neutral-texture) repeat var(--pt-theme-neutral-10);

The following table lists the CSS variables that are specific to tiles. While these may be set at the tile level, you should note that the width or height of a tile affects the layout of a section.

CSS Variable

Applicable Level

Description

--pt-tile-width

  • :root

  • Homepage

  • Section

Defines the BASE width for a tile. It is the smallest unit for the layout using CSS grid.

--pt-tile-height

  • :root

  • Homepage

  • Section

Defines the BASE height for a tile. It is the smallest unit for the layout using CSS grid.

--pt-tile-spacing

  • :root

  • Homepage

  • Section

Internal padding for a tile.

--pt-tile-gap

  • :root

  • Homepage

  • Section

Spacing between tiles

--pt-tile-width-#--pt-tile-height-#

  • :root

  • Homepage

  • Section

Where "#" is the dimension specified in the Tile CREF definition (or via the Tile API), specifies the width/height values of a given tile per the specified configuration. With this model, the width (unless it is a list, elastic, or simple tile) is FIXED but the height value is more of a minimum allowing the content to grow.

The following table lists the CSS variables for styling homepages and sections.

The default CSS grid for homepage is a 12 column layout with the outer two columns used for a gutter or margin. At the homepage level, the element style psc_hp-sections contains the section layout, which can be modified through custom style sheets at the same level. The section specific layout can be overridden at the individual section level.

CSS Variable

Applicable Level

Description

--pt-section-grid-column-count

Defined a section container level of psc_hp-sections element.

Determines the number of columns (including gutters) to be used in lay out sections on a homepage. The default number of columns is 12.

--pt-section-template-columns

Defined a section container level of psc_hp-sections element.

Specifies the actual layout of columns as far as sizing into which sections will be placed. The default is --pt-section-template-columns: var(--pt-section-gutter) repeat(calc(var(--pt-section-grid-column-count) - 2), minmax(0, 1fr)) var(--pt-section-gutter);

--pt-section-gutter

Defined a section container level of psc_hp-sections element.

Column sizing for the side gutters for layout of the homepage. The default is 0px (meaning that the actual margin is implemented through the gap for sections) so the gutter found on the sides of the homepage will be the size of a section gap.

--pt-section-spacing

Defined a section container level of psc_hp-sections element.

Specifies the spacing between sections (and the gutter). The default value is 32px.

--pt-section-min-spacing

Defined a section container level of psc_hp-sections element.

Specifies the minimum spacing for responsiveness. The default is 5cqi.

cqi units are container units as a percentage of inline sizing (width).

--pt-section-grid-gap

Defined a section container level of psc_hp-sections element.

Specifies the actual gap between sections (which is responsive). The default is as follows: --pt-section-grid-gap: min(var(--pt-section-spacing,32px),var(--pt-section-min-spacing,5cqi));

--pt-section-padding

Section

Specifies the padding between the content and the bounding box container. The default is 32px. You can specify different paddings for each size using standard padding syntax. This variable is useful for full width tiles that need to have the contents moved to align better with the non-full width sections.

Example: --pt-section-padding: calc(2 * var(--pt-section-interior-spacing)) calc(4 * var(--pt-section-interior-spacing) + var(--pt-section-gutter));

--pt-section-action-button-adjust

Section

Specifies the additional offset for the horizontal alignment of the section action button in addition to the default section padding. It is useful when the section is a full width section and the interior has been moved using the --pt-section-padding. Example: --pt-section-action-button-adjust: calc(3 * var(--pt-section-interior-spacing) + var(--pt-section-gutter));

--pt-section-row-start

Section

Specifies the grid row starting position for a section. The default is Auto.

--pt-section-row-end

Section

Specifies the grid row ending position for a section. The default is Auto.

--pt-section-column-start

Section

Specifies the grid column starting position for a section. The default is 2 (leaving the first column for a gutter).

--pt-section-column-end

Section

Specifies the grid column ending position for a section. The default is -2 (spans all columns to the next to the last column so as to leave a gutter).