Version 4 supported

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 CMS. This is enabled by default in the Pages section for SiteTree models, but as outlined below can be enabled in other sections and for other models as well.

Within the preview panel, 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 form. LeftAndMain will automatically take care of generating it as long as the *_SilverStripeNavigator template is found - first segment has to match the current LeftAndMain-derived class (e.g. LeftAndMain_SilverStripeNavigator).

PHP

For a DataObject to be previewed using the preview panel there are a few prerequisites:

  • The class must implement the CMSPreviewable interface
  • At least one preview state must be enabled for the class
  • There must be some valid URL to use inside the preview panel

CMSPreviewable

The CMSPreviewable interface has three methods: PreviewLink, CMSEditLink, and getMimeType.

PreviewLink

The PreviewLink method is what determines the URL used inside the preview panel. If your DataObject is intended to always belong to a page, you might want to preview the item in the context of where it sits on the page using an anchor. You can also provide some route specific for previewing this object, for example an action on the ModelAdmin that is used to manage the object.

CMSEditLink

This method exists so that when a user clicks on a link in the preview panel, the CMS edit form for the page the link leads to can be loaded. Unless your DataObject is acting like a page this will likely not apply, but as this method is mandatory and public we may as well set it up correctly.

If your object belongs to a custom ModelAdmin, the edit URL for the object is predictable enough to construct and return from this method as you'll see below. The format for that situation is always the same, with increasing complexity if you're nesting GridFields. For the below examples it is assumed you aren't using nested GridFields.

If your object belongs to a page, you can safely get away with returning null or an empty string, as it won't be used. You can choose to return a valid edit link, but because of the complexity of the way these links are generated it would be difficult to do so in a general, reusable way.

getMimeType

In ~90% of cases will be 'text/html', but note it is also possible to display (for example) an inline PDF document in the preview panel.

Preview states

The preview state(s) you apply to your DataObject will depend primarily on whether it uses the Versioned extension or not.

Versioned DataObjects

If your class does use the Versioned extension, there are two different states available to you. It is generally recommended that you enable both, so that content authors can toggle between viewing the draft and the published content.

To enable the draft preview state, use the $show_stage_link configuration variable.

private static $show_stage_link = true;

To enable the published preview state, use the $show_live_link configuration variable.

private static $show_live_link = true;

Unversioned DataObjects

If you are not using the Versioned extension for your class, there is only one preview state you can use. This state will always be active once you enable it.

To enable the unversioned preview state, use the $show_unversioned_preview_link configuration variable.

private static $show_unversioned_preview_link = true;

Enabling preview for DataObjects in a ModelAdmin

For this example we will take the Product and MyAdmin classes from the ModelAdmin documentation.

The DataObject implementation

As mentioned above, your Product class must implement the CMSPreviewable interface. It also needs at least one preview state enabled. This example assumes we aren't using the Versioned extension.

use SilverStripe\ORM\CMSPreviewable;
use SilverStripe\ORM\DataObject;

class Product extends DataObject implements CMSPreviewable
{
    private static $show_unversioned_preview_link = true;

    // ...

    public function PreviewLink($action = null)
    {
        return null;
    }

    public function CMSEditLink()
    {
        return null;
    }

    public function getMimeType()
    {
        return 'text/html';
    }
}

We will need to add a new action to the ModelAdmin to provide the actual preview itself. For now, assume that action will be called cmsPreview. We can very easily craft a valid URL using the Link method on the MyAdmin class.

Note that if you had set up this model to act like a page, you could simply return $this->Link($action). In that case the new action would not need to be added to your ModelAdmin.

Note: The if (!$this->isInDB()) check below is important! Without this, the preview panel will redirect you to a 404 page when creating a new object.
public function PreviewLink($action = null)
{
    if (!$this->isInDB()) {
        return null;
    }
    $admin = MyAdmin::singleton();
    return Controller::join_links(
        $admin->Link(str_replace('\\', '-', $this->ClassName)),
        'cmsPreview',
        $this->ID
    );
}

The CMSEditLink is also very easy to build, because the edit link used by ModelAdmins is predictable.

public function CMSEditLink()
{
    $admin = MyAdmin::singleton();
    $sanitisedClassname = str_replace('\\', '-', $this->ClassName);
    return Controller::join_links(
        $admin->Link($sanitisedClassname),
        'EditForm/field/',
        $sanitisedClassname,
        'item',
        $this->ID
    );
}

Let's assume when you display this object on the front end you're just looping through a list of items and indirectly calling forTemplate using the $Me template variable. This method will be used by the cmsPreview action in the MyAdmin class to tell the CMS what to display in the preview panel.

The forTemplate method will probably look something like this:

public function forTemplate()
{
    // If the template for this DataObject is not an "Include" template, use the appropriate type here e.g. "Layout".
    return $this->renderWith(['type' => 'Includes', self::class]);
}

The ModelAdmin implementation

We need to add the cmsPreview action to the MyAdmin class, which will output the content which should be displayed in the preview panel.

Because this is a public method called on a ModelAdmin, which will often be executed in a back-end context using admin themes, it pays to ensure we're loading the front-end themes whilst rendering out the preview content.

use SilverStripe\Admin\ModelAdmin;
use SilverStripe\View\SSViewer;

class MyAdmin extends ModelAdmin 
{
    private static $managed_models = [
        Product::class,
    ];

    private static $url_segment = 'products';

    private static $menu_title = 'Products';

    private static $allowed_actions = [
        'cmsPreview',
    ];

    private static $url_handlers = [
        '$ModelClass/cmsPreview/$ID' => 'cmsPreview',
    ];

    public function cmsPreview()
    {
        $id = $this->urlParams['ID'];
        $obj = $this->modelClass::get_by_id($id);
        if (!$obj || !$obj->exists()) {
            return $this->httpError(404);
        }

        // Include use of a front-end theme temporarily.
        $oldThemes = SSViewer::get_themes();
        SSViewer::set_themes(SSViewer::config()->get('themes'));
        $preview = $obj->forTemplate();

        // Make sure to set back to backend themes.
        SSViewer::set_themes($oldThemes);

        return $preview;
    }
}

Enabling preview for DataObjects which belong to a page

If the DataObject you want to preview belongs to a specific page, for example through a has_one or has_many relation, you will most likely want to preview it in the context of the page it belongs to.

The Page implementation

For this example we will assume the Product class is Versioned.

As discussed above, the CMSEditLink method is used to load the correct edit form in the CMS when you click on a link within the preview panel. This uses the x-page-id and x-cms-edit-link meta tags in the head of the page (assuming your page template calls $MetaTags in the <head> element). When a page loads, these meta tags are checked and the appropriate form is loaded.

When rendering a full page in the preview panel to preview a DataObject on that page, the meta tags for that page are present. When a content author toggles between the draft and published preview states, those meta tags are checked and the page's edit form would be loaded instead of the DataObject's form. To avoid this unexpected behaviour, you can include an extra GET parameter in the value returned by PreviewLink. Then in the MetaTags method, when the extra parameter is detected, omit the relevant meta tags.

Note that this is not necessary for unversioned DataObjects as they only have one preview state.

use SilverStripe\Control\Controller;
use SilverStripe\View\Parsers\HTML4Value;

class ProductPage extends Page
{
    //...

    private static $has_many = [
        'Products' => Product::class,
    ];

    public function MetaTags($includeTitle = true)
    {
        $tags = parent::MetaTags($includeTitle);
        if (!Controller::has_curr()) {
            return;
        }
        // If the 'DataObjectPreview' GET parameter is present, remove 'x-page-id' and 'x-cms-edit-link' meta tags.
        // This ensures that toggling between draft/published states doesn't revert the CMS to the page's edit form.
        $controller = Controller::curr();
        $request = $controller->getRequest();
        if ($request->getVar('DataObjectPreview') !== null) {
            $html = HTML4Value::create($tags);
            $xpath = "//meta[@name='x-page-id' or @name='x-cms-edit-link']";
            $removeTags = $html->query($xpath);
            $body = $html->getBody();
            foreach ($removeTags as $tag) {
                $body->removeChild($tag);
            }
            $tags = $html->getContent();
        }
        return $tags;
    }
}

The DataObject Implementation

Make sure the Versioned Product class implements CMSPreviewable and enables the draft and published preview states.

use SilverStripe\ORM\CMSPreviewable;
use SilverStripe\ORM\DataObject;
use SilverStripe\Versioned\Versioned;

class Product extends DataObject implements CMSPreviewable
{
    private static $show_stage_link = true;
    private static $show_live_link = true;

    private static $extensions = [
        Versioned::class,
    ];

    private static $has_one = [
        'ProductPage' => ProductPage::class,
    ];

    // ...

    public function PreviewLink($action = null)
    {
        return null;
    }

    public function CMSEditLink()
    {
        return null;
    }

    public function getMimeType()
    {
        return 'text/html';
    }

}

Implement a method which gives you a unique repeatable anchor for each distinct Product object.

/**
 * Used to generate the id for the product element in the template.
 */
public function getAnchor()
{
    return 'product-' . $this->getUniqueKey();
}

For the PreviewLink, append the DataObjectPreview GET parameter to the page's frontend URL.

public function PreviewLink($action = null)
{
    if (!$this->isInDB()) {
        return null;
    }
    // Let the page know it's being previewed from a DataObject edit form (see Page::MetaTags())
    $action = $action . '?DataObjectPreview=' . mt_rand();
    // Scroll the preview straight to where the object sits on the page.
    if ($page = $this->ProductPage()) {
        $link = $page->Link($action) . '#' . $this->getAnchor();
        return $link;
    }
    return null;
}

The CMSEditLink doesn't matter so much for this implementation. It is required by the CMSPreviewable interface so some implementation must be provided, but you can safely return null or an empty string with no repercussions in this situation.

The Page template

In your page template, make sure the anchor is used where you render the objects. This allows the preview panel to be scrolled automatically to where the object being edited sits on the page.

<%-- ... --%>
<% loop $Products %>
  <div id="$Anchor">
    <%-- ... --%>
  </div>
<% end_loop %>

Javascript

Configuration and Defaults

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

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 app/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 'app/javascript/MyLeftAndMain.Preview.js' to the LeftAndMain.extra_requirements_javascript configuration value

SilverStripe\Admin\LeftAndMain:
  extra_requirements_javascript:
    - app/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:

$('.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:

$('.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:

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

You can find out current size by calling:

$('.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:

$('.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:

$('.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