The Change the look wizard is the entry point to the SharePoint theming experience. The design gallery is the first page in the Change the look wizard and shows a thumbnail view of available designs. Users select a design for their site and then continue to the next page where they can customize the design. Users can then preview the site before applying the design to their site. The master page preview file is used to generate the thumbnail and preview images. If a master page does not have a corresponding preview file, it cannot be used in the theming experience.

Master page preview files (.preview files) are specially formatted files that have sections for default color palette, default font scheme, tokenized CSS, and tokenized HTML. The master page preview file must use the same name (excluding the extension) as the corresponding master page. For example, if you have a master page named article.master, the corresponding master page preview file is named article.preview. Master pages and master page previews are stored in the Master Page Gallery.

Default color palette is the .spcolor file in the Theme Gallery (http://SiteColltionName/_catalogs/theme/15/) that you want to use as the default. The default color palette corresponds to the colors that are used in the master page in its default state. That is, before a user has selected a color palette in the Change the look wizard.

Default font scheme is the .spfont file in the Theme Gallery (http://SiteCollectionName/_catalogs/theme/15/) that you want to use as the default. The default font scheme corresponds to the fonts that are used in the master page in its default state. That is, before a user has selected a font scheme in the Change the look wizard.

CSS is the section that contains cascading style sheets (CSS). All CSS classes must be prefixed with [ID]. The following example shows a portion of the CSS section in a master page preview file.

HTML is the HTML section that defines the HTML structure of the preview.

Note

All dimension values should be specified as relative units in the master page preview file. For example, dimension values can be specified as a percent or as an em measurement. For more information about em measurements, see section 5.1.1. Font-relative lengths: the 'em', 'ex', 'ch', 'rem' units in the W3C CSS Values and Units Module Level 3 Working Draft.

Tokens are used throughout the master page preview file. Tokens are string values that will be replaced with text, color values, or font values in the generated preview. The following sections describe the available tokens and how they are used.

Miscellaneous tokens

The miscellaneous tokens are replaced with specified height and width values in the preview.

Table 2. Miscellaneous tokens

Token Name

Description

[T_HEIGHT]

The height of the preview.

[T_WIDTH]

The width of the preview.

[T_IMAGE]

The URL of an optional background image.

[T_IMGHEIGHT]

The height of the image, if needed.

[T_IMGWIDTH]

The width of the image, if needed.

Color tokens

Color tokens are replaced with color values in the preview image. Table 3 describes two formats for color tokens. Replace ColorSlot with the annotation name of the color slot. The color tokens must be uppercase (for example, [T_THEME_COLOR_PAGEBACKGROUND]). To see the list of available color tokens, see the Color slot mapping section in Color palettes and fonts in SharePoint 2013.

Table 3. Color tokens

Token Name

Description

[T_THEME_COLOR_ColorSlot]

Use this format if you want the color value of the color slot.

[T_THEME_COLOR_ColorSlot_AA]

Use this format if you want the 8-digit hexadecimal value of the color slot. This format is useful for filter values to enable opacity and gradients in Internet Explorer.

Text content tokens

The tokens listed in Table 4 are used in the HTML section of the master page preview file. The tokens are replaced with sample text in the preview image in the design gallery. The sample text is shown in the same language as the rest of the site.

Table 4. Text content tokens

Token Name

Description

[BRANDSTRING]

The brand text that appears on the page. In the preinstalled themes, it appears on the top-left corner "Brand".

[SUITELINK1]

[SUITELINK2]

[SUITELINK3]

The suite links that appear in the suite bar. See "First Item", "Second Item", "Third Item" in Figure 1.

To create a master page preview file, use an existing master page preview as a starting point.

To create a master page preview

Make a copy of a master page preview. SharePoint 2013 includes oslo.preview and seattle.preview.

Rename the copy of the master page preview to match its corresponding master page. For example, if your master page is named article.master, rename the master page preview article.preview.

Use an HTML editor to edit the master page preview file. Update the file to reflect the layout and appearance of your master page.

Tip

Dimension values are specified as percentages in the master page preview file. The following example shows one method for converting an absolute measurement (pixels) into a relative measurement (percentage). Assume you have a browser size of 1024x768. If the master page has an element height of 32 pixels and the parent element is the body of the page, you calculate the percentage by dividing the element height by the browser height. The relative measurement is 4%(32/768).

Upload the master page preview file to the Master Page Gallery.

Use the Change the look wizard to test the master page preview with your site content.