Editing user interface

This topic explains the architecture and different components of the editing user interface in Episerver. The user interface is pluggable allowing you to plug-in your own gadgets to the panes to extend editing possibilities.

• How it works
• Architecture
• Server communication
• Editable blocks
• Editing data attributes
• Architecture diagram

How it works

The UI framework has a server-side part that is based on ASP.NET MVC and a client-side part that uses the JavaScript library Dojo. The UI also has context-awareness where it is possible to have a component automatically reload when the context is changed, or to display customized content for that item. You also can load Web Forms pages and user controls into components of the user interface to port existing plug-ins built with ASP.NET user interface.

You can edit content in the user interface in the following ways:

• On page editing. Opens an editor directly on the page to edit simple property types such as short strings, integers and decimal numbers.
• Forms editing. Edit all properties in a form-based editing view. Here you are able to edit properties that are not visible on the page.

This means that the editor can make changes using different modes without losing context.

Autosaving

Changes are automatically saved to the client state and sent to the server to be persisted. To reduce the burden on the server, synchronization between client and server occurs after a few seconds delay. When a user edits a property or content block, the client creates and stores an undo step in a history that lets the user undo and redo changes. The undo and redo steps are available while the user remains editing the page and are lost when the user leaves the page. Any editing changes are sent to the server and are saved even if the user leaves the page or closes the browser.

Architecture

Editing components are organized into two layers.

• UI layer. Most of the Episerver scripts and css files are loaded and most of the user interface and interaction takes place on this layer.
• Content page layer. This layer is inside an iframe and should have very few differences compared to the page that is shown to visitors of the site. This layer contains HTML5 data-attributes that are injected in edit view to identify editable blocks. Also, a custom stylesheet is injected into the content pages when editing is enabled, but no other scripts or markup are injected. When the content page layer is loaded, the UI layer scans the content of the page to find editable nodes and adds event handlers to them that trigger loading of the correct editor.

You can enable editing for a specific area by adding the following attribute to the HTML tag: data-epi-property-name="PageName":

<h1 data-epi-property-name="PageName"><%= CurrentPage.PageName %></h1>

Clicking on a node in the following example loads whichever editor is configured for the Pagename property.

A property can appear several times on a page, so you can edit it in multiple places. By editing a property in one place, it updates any other place where the property is used. You can prevent a property from being edited by disabling it, (but the property updates its content if it is edited elsewhere).

Configuration of editors is done separately and does not have to be added to the HTML even if there are a few other data-attributes that you can use to override default behavior.

When an editor is triggered for a property, an editor factory class creates the editor based on the data attributes and metadata for the property. Episerver Framework extracts metadata from the following sources to create an editor.

• Extracting metadata attributes from the model class
• Global editor descriptors that can set up rules for a common language runtime type.
• Custom metadata providers that supplies the metadata.

Note: For a description of the Episerver object editing system, see Object Editing.

You can create page properties from typed model classes and in the administrative user interface. The PageData class assembles metadata using a custom metadata provider that sends the metadata to the client using a RESTful service and is a hierarchical representation of the page and its properties. The following example shows how a property might be described:

• modelType is the name of the CLR type including its namespace.
• uiType is the default client side editor widget.
• customEditorSettings might have information about a non-standard editor type like an inline editor.
• settings is a settings object that will be passed to the constructor of the editor widget.

{
    "name":"PageName",
    "modelType":"EPiServer.Core.PropertyString",
    "uiType":"dijit.form.ValidationTextBox",
    "uiPackage":null,
    "customEditorSettings":{"uiWrapperType":"inline","uiType":"epi.cms.widget.ValidationTextBox"},
    "layoutType":null,
    "defaultValue":null,
    "displayName":"Name",
    "groupName":null,
    "displayOrder":-81,
    "settings":{"label":"Name","required":true,"missingMessage":"The Name field is required.","invalidMessage":"The
    field Name must be a string with a maximum length of 255.","regEx":"^.{0,255}$","maxLength":255},
    "additionalValues":{},
    "properties":[],
    "groups":null,'
    "selections":null
}

Server communication

The page editing component does the following tasks:

• Creates editable blocks for each node in the page with data attributes.
• Stores page data in the page model.
• Syncs changes using the page model server sync class.

The editable blocks are responsible for editing property data and use a render manager to render property on the page (on either the client side or server side). Server-side rendering uses a queue so that properties are not rendered at the same time. Changing one property can mean that several properties on the page need to be rendered again with different settings.

Editable blocks

Clicking on an editable block creates the editor and an editor wrapper for the block. The editor factory decides which wrapper and editor to use depending on the data attributes for editing and metadata for the property. You can connect to an event in editor factory to change the values at runtime.

Data attributes have higher precedence than the metadata. You can choose to use an editor for a property on a page which is not the standard editor for that property. For inline editing, you must use an editor designed for it; in other cases, the editor is a widget.

You can set the values for data-epi-property-editorsettings and data-epi-property-rendersettings through the EditorSettings or RenderSettings properties on either Property web control or on Property data control when using web forms. In MVC, you can pass the values in as anonymous object to PropertyFor helper method. You should pass in the render settings using parameter additionalViewData while you can pass in the editor settings using parameter editorSettings.

Editing data attributes

Architecture diagram