7.3 KiB
CMS preview
Overview
Deprecated: The following documentation regarding JavaScript layouts and Entwine applies to legacy code only. If you're developing new functionality in React powered sections please refer to ReactJS in SilverStripe.
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 necessary 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.
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").
(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 setting adding 'mysite/javascript/MyLeftAndMain.Preview.js'
to the LeftAndMain.extra_requirements_javascript
configuration value
SilverStripe\Admin\LeftAndMain:
extra_requirements_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 LeftAndMain.Preview.js
in the silverstripe/admin
module.
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
presence 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;
```
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.