silverstripe-framework/docs/en/reference/preview.md

CMS preview

Overview

With the addition of side-by-side editing, the preview has the ability to appear within the CMS window when editing content in the Pages section of the CMS. The site is rendered into an iframe. It will update itself whenever the content is saved, and relevant pages will be loaded for editing when the user navigates around in the preview.

The root element for preview is .cms-preview which maintains the internal states neccessary for rendering within the entwine properties. It provides function calls for transitioning between these states and has the ability to update the appearance of the option selectors.

In terms of backend support, it relies on SilverStripeNavigator to be rendered into the .cms-edit-form. LeftAndMain will automatically take care of generating it as long as the *_SilverStripeNavigator template is found - first segment has to match current LeftAndMain-derived class (e.g. LeftAndMain_SilverStripeNavigator).

We use ss.preview entwine namespace for all preview-related entwines.

Caveat: `SilverStripeNavigator` and `CMSPreviewable` interface currently only support SiteTree objects that are _Versioned_. They are not general enough for using on any other DataObject. That pretty much limits the extendability of the feature.

Configuration and Defaults

Like most of the CMS, the preview UI is powered by jQuery entwine. This means its defaults are configured through JavaScript, by setting entwine properties. In order to achieve this, create a new file mysite/javascript/MyLeftAndMain.Preview.js.

In the following example we configure three aspects:

• Set the default mode from "split view" to a full "edit view"
• Make a wider mobile preview
• Increase minimum space required by preview before auto-hiding

Note how the configuration happens in different entwine namespaces ("ss.preview" and "ss"), as well as applies to different selectors (".cms-preview" and ".cms-container").

:::js
(function($) {
	$.entwine('ss.preview', function($){
		$('.cms-preview').entwine({
			DefaultMode: 'content',
			getSizes: function() {
				var sizes = this._super();
				sizes.mobile.width = '400px';
				return sizes;
			}
		});
	});
	$.entwine('ss', function($){
		$('.cms-container').entwine({
			getLayoutOptions: function() {
				var opts = this._super();
				opts.minPreviewWidth = 600;
				return opts;
			}
		});
	});
});
}(jQuery));

Load the file in the CMS via an addition to mysite/_config.php:

:::php
LeftAndMain::require_javascript('mysite/javascript/MyLeftAndMain.Preview.js');

In order to find out which configuration values are available, the source code is your best reference at the moment - have a look in framework/admin/javascript/LeftAndMain.Preview.js. To understand how layouts are handled in the CMS UI, have a look at the CMS Architecture guide.

Enabling preview

The frontend decides on the preview being enabled or disabled based on the presnce of the .cms-previewable class. If this class is not found the preview will remain hidden, and the layout will stay in the content mode.

If the class is found, frontend looks for the SilverStripeNavigator structure and moves it to the .cms-preview-control panel at the bottom of the preview. This structure supplies preview options such as state selector.

If the navigator is not found, the preview appears in the GUI, but is shown as "blocked" - i.e. displaying the "preview unavailable" overlay.

The preview can be affected by calling enablePreview and disablePreview. You can check if the preview is active by inspecting the IsPreviewEnabled entwine property.

Preview states

States are the site stages: live, stage etc. Preview states are picked up from the SilverStripeNavigator. You can invoke the state change by calling:

```js
$('.cms-preview').entwine('.ss.preview').changeState('StageLink');
```

Note the state names come from SilverStripeNavigatorItems class names - thus the Link in their names. This call will also redraw the state selector to fit with the internal state. See AllowedStates in .cms-preview entwine for the list of supported states.

You can get the current state by calling:

```js
$('.cms-preview').entwine('.ss.preview').getCurrentStateName();
```

Preview sizes

This selector defines how the preview iframe is rendered, and try to emulate different device sizes. The options are hardcoded. The option names map directly to CSS classes applied to the .cms-preview and are as follows:

• auto: responsive layout
• desktop
• tablet
• mobile

You can switch between different types of display sizes programmatically, which has the benefit of redrawing the related selector and maintaining a consistent internal state:

```js
$('.cms-preview').entwine('.ss.preview').changeSize('auto');
```

You can find out current size by calling:

```js
$('.cms-preview').entwine('.ss.preview').getCurrentSizeName();
```

Preview modes

Preview modes map to the modes supported by the threeColumnCompressor layout algorithm, see layout reference for more details. You can change modes by calling:

```js
$('.cms-preview').entwine('.ss.preview').changeMode('preview');
```

Currently active mode is stored on the .cms-container along with related internal states of the layout. You can reach it by calling:

```js
$('.cms-container').entwine('.ss').getLayoutOptions().mode;
```

Caveat: the `.preview-mode-selector` appears twice, once in the preview and second time in the CMS actions area as `#preview-mode-dropdown-in-cms`. This is done because the user should still have access to the mode selector even if preview is not visible. Currently CMS Actions are a separate area to the preview option selectors, even if they try to appear as one horizontal bar.

Preview API

Namespace ss.preview, selector .cms-preview:

• getCurrentStateName: get the name of the current state (e.g. LiveLink or StageLink).
• getCurrentSizeName: get the name of the current device size.
• getIsPreviewEnabled: check if the preview is enabled.
• changeState: one of the AllowedStates.
• changeSize: one of auto, desktop, tablet, mobile.
• changeMode: maps to threeColumnLayout modes - split, preview, content.
• enablePreview: activate the preview and switch to the split mode. Try to load the relevant URL from the content.
• disablePreview: deactivate the preview and switch to the content mode. Preview will re-enable itself when new previewable content is loaded.

Related

• Reference: Layout