EPiServer 7 CMS Development (2014)

I. UNDERSTANDING EPISERVER CMS

Chapter 3. Using EPiServer

In the previous chapter we discussed how to install EPiServer on a development computer and how to set up a sample site using EPiServer’s Deployment Center. In this chapter we’ll explore the CMS from a users (editors) perspective. After all, as a developer we need to understand the platform we’re using prior to actually developing for it. It is also important to recognize that while we may spend most of our time in an EPiServer project developing functionality for public visitors enabling and helping editors to work efficiently is key to the success of the site.

Logging in to Online Center

Spend a couple of minutes browsing around on the sample site that you created following the previous chapter. Once you feel you have an overall feel for the site navigate to the start page and then add “/episerver” to the URL in your browsers navigation field and hit enter. This will take you to EPiServer’s Online Center and it’s dashboard, but prior to seeing that you’ll have to log in. Given that your Windows user is a local administrator you can log in using your Windows user name and password.

EPiServer’s login dialog.

Given that you managed to log in successfully you should now be seeing EPiServer’s Online Center and it’s “Home” view, the “Dashboard”.

EPiServer’s Online Center and its dashboard.

Online Center is a UI framework used for navigating between different EPiServer products and components with a customizable dashboard as its starting point. At the top it features a toolbar with a menu on the left side and some links and tools on the right. The menu lets users navigate between parts of Online Center (Dashboard and Add-ons) as well as different EPiServer products and third party modules that have plugged themselves in to the navigation.

The tools in the right side of the toolbar features links to EPiServer, the startpage of the site and user documentation. There we also find a link in the form of the currently logged in users user name. Using that the user can either log out or manage personal settings such as password and what language EPiServer’s UI should be shown in. Finally, the right part of the toolbar also features a search box (opened by clicking on the magnifying glass icon) by which it’s possible to search within the various products that have plugged themselves into the search functionality. One such example is the CMS that adds search providers for pages etc.

Edit mode

To navigate into a part of the CMS click the CMS link in Online Center’s top navigation. This opens up four sub navigation items - Edit, Admin, Reports and Visitor Groups.

The CMS menu option clicked to expand its sub-navigation options.

We’ll come back to some of those later but we’ll start by looking at the heart of the CMS, it’s editorial interface. So, click on the first menu item, named Edit. Once in edit mode we’re presented with the site’s start page below a toolbar at the top of the page.

EPiServer CMS’ edit mode.

Online Center’s top navigation is still present but has been minimized. To bring it back again, should we for instance want to log out or go back to the dashboard we can summon it using the little arrow at the top center of the page.

What we’re looking at now is EPiServer CMS’ edit interface, often referred to as “edit mode”. The edit interface is a client side application (often referred to as a single page app) written in JavaScript using the Dojo framework. What this means is that the edit interface “lives” in our browser and unless we leave edit mode or hit the refresh button in our browser the whole page is never reloaded, allowing the application to maintain state in each client computers memory, similar to for instance Google’s GMail.

As you can see, upon entering edit mode the interface appears to be comprised of two parts - a top toolbar and an IFrame showing a page on the site. The site as shown in the IFrame is the actual site, albeit with a couple of minor modifications during the rendering of a page. This means that you are free to browse around on the site using its links, such as those in the site’s top navigation. When you do the content shown in the IFrame changes but the browser is still in edit mode.

EPiServer CMS’ edit mode after clicking on the “Alloy Plan” link in the site’s top navigation.

When navigating around on the site in edit mode in the IFrame other edit mode components may detect that you are doing so and update their own state. One such visible example is the breadcrumbs and page name components in the top toolbar.

In the top toolbar there are two buttons, one in the top left corner and one in the top right corner, which can be used to open two panels. These panels are referred to as the “navigation pane” and the “assets pane”.

The buttons for opening the navigation and asset panes

Clicking either of the buttons opens the button’s respective pane, positioning either to the left or the right, on top of the IFrame or the toolbar.

The navigation pane opened.

Once a pane has been opened it’s automatically closed when you click anywhere outside the page. Each pane has a thumbtack icon at the top. Clicking the icon locks the pane in place so that it’s not closed when clicking outside it. Pinning the pane also has another effect. Instead of the pane hiding parts of the top toolbar and IFrame those components contract to clear up space for the pane(s).

Both panes pinned.

Both of the panes hold UI components known as gadgets. The navigation pane is pre-configured with four gadgets, Pages, Sites Tasks and Recent. The first three are grouped together in a group called Navigation. The assets pane is pre-configured with two gadgets, Blocks and files, grouped in a group called Assets.

Each user of the CMS can customize the panes to their liking, adding and rearranging gadgets. Apart from the pre-configured ones the CMS ships with a number of other gadgets and third party developers can create new ones that users can add to one of the panes.

The page tree

The Pages gadget, or the “page tree” as it’s commonly referred to among EPiServer developers and users, is an essential component in the CMS. Apart from uploaded files and, for some sites, custom made functionality the pages shown in the page tree is the pages visible on the site. The way the pages are arranged in the tree forms the site’s hierarchy that is used when building navigation components, listings and URLs for individual pages.

The pages gadget when viewing the startpage.

Knowing your way around the page tree is essential for both editors and developers. Therefore, let’s take a look at it in greater detail.

As you can see the gadget displays a tree. Each node in the tree is a page, an entity that is stored in the database and that holds content and other information such as access rights. Most of the pages are visible on the site and hold content entered by editors, but there are exceptions. At the very top of the tree there’s the root page, named “Root”. This is a special page in the CMS and there must always be exactly one such page. Apart from it being shown at the top of the tree its special status is also shown by its special icon, a grey box with three vertical lines.

The root page in the page tree.

Directly below the Root page there’s another special page named Start. This is shown with a different icon, a house.

The startpage in the page tree.

The house icon indicates that this page is a startpage, or root page, for a site. An EPiServer application with a single codebase can have multiple sites, meaning that there will be multiple pages with a house icon. This is common for “enterprise installations” where for instance each brand within the same corporate group has its own site with its own individual content but the same set of templates for displaying it.

As opposed to the Root page the Start page is a public page shown to public visitors. In fact, this is the page that visitors will see when they enter the root URL for the site, such as http://www.domain.com/.

In the screen shot above the Start page is shown with olive green background. This is a visual indication that the Start page is the currently viewed page. If you navigate to another page on the site the Start page will no longer have that background color in the tree and instead the currently viewed page will.

Also in the screen shot above, a small icon is shown to the right of the Start page. Clicking the icon opens up a context menu. This menu is in fact available for any pages in the page tree by hovering with the mouse pointer over it, but for the currently viewed page it is always shown.

The context menu for the Start page.

Using the context menu various actions based on the selected page are a available. For instance, for the Start page the context menu can be used to create a new page below the Start page or to copy the Start page. Also, had another page already been copied the Paste action would also have been available.

For other pages the context menu can also be used to Cut the page or for moving it to the Trash. However, since the startpage is the root for the site removing it would stop the site from working and doing so is not possible.

Below the Start page there are seven child pages. All but the last one of these, the one named Search, has a plus icon to the left of its name. The plus icon indicates that the page has children, other pages located below it in the tree. Clicking the plus icon expands the tree node, showing the page’s children.

The page tree after clicking the plus icon for the “Alloy Track” page.

Two of the pages below the Start page, “How to buy” and “Campaigns”, have brown boxes as icons. This indicates that these pages are so called container pages. Container pages are pages of a type for which there is no renderer (template).

Two container pages.

These pages are just like all of the other pages in the sense that they are nodes in the tree and that they can hold content, but the CMS does not know how to render them. Such pages are typically used for grouping other pages, such as by year in an article archive, or for holding data that is displayed on other pages. Indeed, expanding one of the container pages on the Alloy sample site reveals that there are ordinary, publicly visible pages below it.

A container page with regular pages below it.

At the very bottom of the Pages gadget there are three icons. The leftmost one, with a plus sign, initiates the process of creating a new page below the page that is currently selected in the page tree. To the right of that icon there’s an icon with three vertical lines, just like the context menu. Indeed, clicking this icon opens up the context menu for the currently selected page in the page tree.

Bottom icons in the Pages gadget.

Finally, in the bottom right of the gadget there’s a cog wheel icon. Clicking this opens up a menu through which one can view the Trash and configure the page tree to show pages that are in a different language.

In addition to viewing the site’s page hierarchy and performing the actions we’ve covered so far the page tree can also be used to navigate on the site. Simply click on a page and it will be selected in the page tree and displayed in the IFrame.

The Pages gadget can also be used to rearrange pages in the page tree. We’ve already seen that pages can be copied or cut from their current location and pasted below another page using the page tree. However, the page tree also supports moving and sorting pages through drag-n-drop.

Let’s give sorting a try. Grab one of the pages below the startpage and drag it under some other page, for instance drag “Alloy Plan” below “Alloy Meet”.

Reordering pages in the page tree.

Doing this doesn’t move the page in the page tree as all we’ve done is changing the sort order. However, the new sort order is reflected in the page tree.

The page tree after sorting Alloy Plan after Alloy Meet.

Also, notice that once you navigate to another page, or reload in your browser, the top menu reflects the change.

The top menu after sorting Alloy Plan after Alloy Meet, reflecting the new sort order in the page tree.

The fact that the top menu reflects the sort order in the page tree isn’t hard coded in the CMS but rather a design decision that was made when the Alloy templates was built. It is however a very common practice for EPiServer sites.

Editing content

In the previous section we saw how to view and modify the page structure on the site using the Pages gadget. Let’s now take a look at how to modify the content on individual pages. To do so we’ll take a look at the Alloy Plan page.

The Alloy Plan page in edit mode

Notice the blue boxes around certain elements on the page? Those indicate that the value shown there is a property on the page that can be edited. In order to edit one of them simply click on it.

Editing the page’s heading by clicking on it.

After clicking on an editable area, or rather a page’s property, and modifying its value simply click anywhere outside it to stop editing it. Given that we’ve made any modification to it the new value is shown on the page.

After modifying the page’s heading.

There are a couple of things to note in the top toolbar in the screen shot above. In the middle of the toolbar a message says “Autosaved <time>” and below it there’s an undo link. This indicates that the modification to the page has been saved to the server and the undo link, naturally, can be used to the undo the change.

In the right side of the toolbar a blue arrow with the text “Changes to be published” pointing to a button with the text “Publish?” is shown. From this we can conclude that while we have modified the page and the change has been saved on the server the change(s) hasn’t been published yet. Instead a new version, a draft, has been created and it’s up to us to decide if and when we want this new version to be published and thereby visible to public visitors.

In order to publish the new version of the page click the “Publish?” button to open up a toolbox. The toolbox contains buttons for various actions relating to the page’s publication status, such as scheduling it for publish and reverting to the currently published version. Using another option, the large green button, we can publish the new version directly.

After publishing the page a dialog is shown confirming that the new version has indeed been successfully published.

The new version is now published and the changes made are visible to public visitors on the site.

Clicking on the other areas with blue borders yields the same result as the page’s heading, making them editable. However, the result is different in the sense that they are edited in different ways, depending on their type and/or instructions from the developers of the site.

Editing the preamble which is a regular string configured to be edited using a textarea.

Editing the main content of the page using a WYSIWYG editor (TinyMCE) in which editors can use HTML elements.

Editing an image.

Forms Editing mode

Editing content, or rather the value of page properties, on the page by clicking on it is referred to as On Page Editing. Therefore, the mode in which we’ve edited the page so far is called On Page Edit mode, or OPE mode for short. OPE mode makes it easy for editors to edit pages. Simply identify the part of the page that you want to modify and click on it. During editing the editor is offered a real-time, or near real-time, preview.

However, not all data associated with a web page is rendered in the browser, making it impossible to edit this way. Other data may be rendered in the browser but not suitable for editing with a live preview. Also, some pages may not have a renderer (container pages). Such properties, as well as those editable in OPE mode, can be edited in Forms Editing mode.

To access Forms Editing click the button below the button that toggles the Assets pane and left of the Options button in the top toolbar.

The button for toggling Forms Editing.

Forms editing mode is vertically divided into two parts. The top part holds a number of built in, important properties, some meta data and a number of tools for making operations related to the page. The bottom part lists all other properties of the page divided into groups using tabs.

Forms Editing mode.

Content areas

As we’ve already seen examples of, different properties on a page are edited in different ways. This is natural as they contain different types of data. For instance, a string property is edited using a textbox or a textarea while an image URL property is edited using a file picker.

While there are several other types of properties that are editable in their own ways there’s one type of property that is both so important, and which is edited in such a special way, that it deserves some special attention - content areas. A content area is essentially a list of references to pages and other types of content (discussed in the following section). When a content area property is rendered in a template each item in the list is displayed using a partial template, a template for when a page or other type of content is rendered as part of another page. That is, given that such a template exists.

Let’s look at an example. On the Alloy Plan page there are two content areas. One of them is found in the right hand column.

The content area in the right column highlighted.

Currently there are two items in the content area. To add a third we can open up the Pages gadget, grab a page and drop it onto the content area.

Dragging the About Us page from the page tree into the content area.

The page after adding the About Us page to the right column content area.

As shown in the screenshots above, after adding a page to a content area a part of the page’s content is displayed in the content area. What is displayed, if anything, is determined by the partial template, or partial renderer, for the page’s type. On the Alloy sample site there are partial renderers for all types of pages.

As we’ll see later when we look at development it’s possible to have generic renderers that can display many types of content as long as they inherit from the same base class. It’s also possible to have several renderers for the same type and have the system select renderer based on various criteria.

In addition to adding content to a content area, such a property can also be edited by modifying the sorting of the contained items and by removing a contained item. Hovering over an item in a content area brings up an icon that can be used to open a context menu. Using this menu the item can be removed from, or moved up or down within, the content area. Using the context menu it’s also possible to navigate to editing mode for that specific content.

The context menu for an item in a content area.

In addition to using the context menu it’s also possible to move items within the content area, and also between different content areas on the same page, by using drag-n-drop.

Clicking on a content area opens up a list of the contents in the area in a flyout. This type of editing can be very convenient if there are a lot of content in the area, such as on a news site’s frontpage.

Flyout shown when clicking on a content area.

The simple list exemplified in the screenshot above is also how content areas are represented in forms editing mode.

Blocks

As we’ve just seen pages can be used not only as full blown, individual pages. They can also be used as parts of other pages. Sometimes that’s all you really need. For instance, let’s say we want a list of upcoming events on a site’s startpage. The list is just a simple bulleted list with links to some external site. Or, it may be that we want to create a widget that lists products currently on sale, which we use on various pages on the site.

In such cases we could create pages and add them to content areas. However, a page would be overkill as we don’t need something that can be rendered on it’s own as a full page. We just need a “widget” of some sort that can only be used on other pages. That in it self doesn’t necessarily mean that there’s any harm in using a page for such content. However, if we’re using pages for such use cases it also means that there are public URLs for the content on it’s own and that it resides in the page tree, next to all the “real” pages, which may confuse editors.

To address this problem EPiServer 7 features a concept called blocks. Blocks, or rather “shared blocks” are similar to pages but a block is specifically intended to only be used as part of a page, or another block. A shared block is technically on the same level as a page. It’s an entity with a unique ID that is saved and retrieved from EPiServer’s database on its own. It is however not on the same level as pages in terms of usage as a shared block is never intended to be viewed on its own.

Blocks used as a property

Above we’re discussing “shared blocks”. There’s another way to use block types referred to as “block used as a property”. As it turns out a block, or rather an instance of a block type, can also be used as “static” instance where the block is merely a part of a host page (or other type of content). That is, a block type can both be used to create stand alone instances that are saved to the database and as property types, just like strings or integers.

Here we focus on shared blocks but we’ll look at both types of usage later in the book.

Like pages shared blocks are saved to the CMS’ database. They don’t however show in the page tree. Instead there’s a separate gadget for organizing blocks. The Blocks gadget located in the Assets pane.

The Assets pane opened, showing the Blocks gadget.

The Blocks gadget displays a list of block folders. Each block folder can contain blocks as well as other folders. Clicking on a folder selects it and reveals a list of the blocks in the folder. As with the Pages gadget with page the Blocks gadgets supports drag-n-drop of blocks into content areas, creating new blocks, moving blocks (between folders) etc.

The Campaigns block folder expanded and the Alloy Meet folder selected.

Double clicking on a block, or by using a context menu, in the gadget opens up the block for editing in the IFrame. Remember that it was recently mentioned that a block isn’t intended to be viewed on its own? That causes a problem when editing it. How should the CMS display it for on-page-editing when there is no full scale renderer like there is for pages, only partial renderers used when displaying the block as part of a page.

While it’s not supposed to be viewed on its own it is still an own entity and can be edited on its own. To address this the CMS lets site developers create preview renderers. Web Forms pages or MVC controllers that are used to display the block on a full page to editors when viewing it in edit mode.

Such a block preview renderer can, and should, allow editors to preview the block looking the same way as it would if it was used on a page. However, that can be challenging for developers as it may very well be that the block is rendered or styled differently on different types of pages or depending on in what content area it is used. In order to give editors a realistic preview developers may therefore have to render the block multiple times. As an example, on the Alloy sample site a block is rendered up to four times showing how it looks depending on width.

Editing one of the blocks on the Alloy site.

The content tree

We’ve seen the Pages gadget allowing editors to find, create and organize page and the Blocks gadget allowing editors to do the same with blocks and blocks folders. Clearly pages, blocks and block folders are separated from each other in terms of how editors work with them. However, under the hood of the edit UI they are actually stored in a single tree structure. The separation of the different types of content is only done at the UI level where each gadget acts as a filtered view of the same tree containing different types of content - the content tree.

Creating new content

Both the Pages gadget and the Blocks gadget offers multiple ways of creating new content, either pages or blocks. There’s also a convenient shortcuts in the top toolbar in edit mode.

Shortcuts for creating new content in the top toolbar.

No matter which way the editors chooses to create new content he or she will be presented with a dialog where a name for the new content must be entered and a content type, either a page type or a block type, must be selected. Given a name has been entered clicking on a content type creates a new page or block of that type.

Dialog when creating new pages.

After entering a name and selecting a content type the content is created, but not yet published. It is shown in edit mode allowing editors to edit its properties and, optionally, publish it.

Sometimes there may be an extra step to the workflow above. If the content type has one or more properties that are required the editor will need to populate them between selecting a content type and the content being created.

Extra dialog when creating a page of a type that has a required property.

A new page on the Alloy site.

Files

Located next to the Blocks gadget in the Assets pane the edit interface features the Files gadget. Using the Files gadget editors can upload and arrange files.

The Files gadget opened in the Assets pane.

The Files gadget works similar to Windows Explorer, allowing files to be grouped in folders. In the upper left part of the gadget a number of starting points are listed. Think of these like disk drives or file shares in Windows. Each starting point is actually a Virtual Path Provider and can have different characteristics such as physical location and support for versioning of files.

All of the starting points except the one named Page Files are optional and can be removed, or the list can be extended with more starting points, using configuration files. What is shown in the screenshot above is merely the standard out-of-the-box configuration.

Page Files is special. Unlike the other starting points the content of the Page Files folder varies depending on the currently selected page, allowing editors to associate files with specific pages.

Unlike the other gadgets we’ve seen so far the Files gadget uses a context menu for files and folders activated using right clicking with the mouse. Using the context menu, or by selecting a file and using the icons at the top of the gadget, files can be deleted, renamed and moved.

The right click context menu for a file.

For images it’s also possible to edit them in the CMS using a simple image editor. Using the image editors editors can resize and crop images as well as making simple modifications to them.

EPiServer’s built in image editor.

Apart from the actual file, editors can associate meta data with it in the form of a file summary, reachable through the right click menu. What fields are available in the file summary is configurable in the form of an XForm in the configuration file FileSummary.config.

File summary dialog for a file on the Alloy site.

Once a file has been uploaded and is visible in the Files gadget it’s publicly available on the website (unless restricted by access rights) and can be linked to by editors. Such links can either be in the form of specific properties where editors can add a single URL, in properties that are lists of links or as links in XHTML properties edited using a WYSIWYG editor.

Admin mode

We’ve now looked at some of the core functionality for working with content in the CMS’ edit mode. Another part that we need to be aware of when working with EPiServer sites is its admin mode. To navigate to admin mode use Online Centers top navigation and select “Admin” instead of “Edit” under the CMS tab.

EPiServer CMS’ admin mode.

While edit mode focuses on editing and managing content admin mode allows for control of other aspects of the site. In admin mode administrators (users with sufficient access rights) can:

· Manage users and groups.

· Set access rights in a more powerful way than what is possible in edit mode.

· Schedule and manually execute jobs.

· Import and export data (pages, blocks, files etc) between different EPiServer sites.

· Manage content types and their properties

· Manage various configuration settings

We’ll look more at admin mode during the development focused parts of the book where we’ll be setting up a site, creating content types and create a custom scheduled job.

There’s more

This chapter provided a brief introduction to what EPiServer CMS is from a users perspective. Knowing how the CMS works is essential in order to understand how to develop EPiServer websites. Yet, covering every single aspect of the CMS would not be suitable for a book about development. Therefore this chapter introduced the most important concepts and features. We’ll dive into more details as we cover various development concepts. Still, studying up on the ins and outs of the CMS is a good idea for an aspiring EPiServer development ninja.

There are several ways to learn more about how to use the CMS ranging from exploring it on your own to classroom based editor training provided by EPiServer. There’s also user manuals in several languages located at: http://world.episerver.com/Documentation/Items/Manuals/EPiServer-CMS/Editor-Manuals---EPiServer-7-CMS-print/.