The ListSummary is a versatile control in the Ektron Framework tool belt. It serves a very basic function, but through the use of a wide variety of properties, it can be stretched to provide a list of links in almost every way imaginable. Table 8-1 contains these properties.

As is clear from Table 8-1, the methods for modifying the ListSummary Server Control are quite varied. Let's explore how some of those properties react when you use the ListSummary on a page:

Figure 8.2. FIGURE 8-2

Figure 8.3. FIGURE 8-3

There are also a few ways to change the way the ListSummary Server Control looks. By default, if you don't set the DisplayXslt property, the server control will use the ecmNavigation template. There are, however, three other predefined options for display. You can set the DisplayXslt property to None–Databind, which does not display anything, but populates the EkItems property so the results can be worked with programmatically.

You can also set the DisplayXslt property to ecmTeaser or to ecmUnorderedList. These are prebuilt documents that cannot be modified, but can help you avoid having to author new XSLT's by covering common use cases. Figure 8-4 shows what the display looks like when set to ecmTeaser.

Figure 8.4. FIGURE 8-4

If you want to change the display layer to something that the standard options won't allow for, you can use a custom XSLT in those situations. To do so, follow these steps:

Figure 8.5. FIGURE 8-5

As you can see in Figure 8-5, paging is still functional, and the ListSummary respects the sorting options you have specified. This makes it simple to update the display because you don't have to reinvent the wheel by adding custom paging or internal sorting. It also means that under-the-hood performance will be as fast as possible, since the transform is taking place on as small a portion of the data as possible. The XML supplied for the transform only contains the information that is currently being displayed to the end user, rather than the full result set.

While XSL transforms are a powerful way of translating the display layer, Ektron is aware that not all developers are completely comfortable with writing XSL transforms. To solve this issue, Ektron has introduced EKML, short for Ektron Markup Language, which can handle basic transformations through simple looping and string replacement of tokens. This language was introduced by Ektron to allow developers to avoid complex XSLT's in simple use cases.

The way EKML hooks into the ListSummary Server Control is very similar to the procedure for XSLT documents. You create an EKML document, and set the MarkupLanguage property to the location of the file. The ListSummary then caches the file and transforms the output according to the structure defined in the markup document. The structure of the file is mostly HTML, with some tags that define where special processing needs to be done, such as loops. Table 8-2 contains the list of special tags used in EKML.

The EKML tags define the basic structure of the EKML document. In addition to the tags there are a whole series of tokens that are replaced with the appropriate values for the objects being displayed. These tokens are outlined in Table 8-3.

Now that you know the allowed tokens, you can create an EKML document that outputs the same HTML as the XSLT you created earlier. Take the code from Listing 8-3 and save it in ~XmlFiles as UnorderedListSummary.ekml.

<ekmarkup>
  <ekoutput>
    <ul>
      <ekrepeat>
        <li>
          [$HyperLink]
        </li>
      </ekrepeat>
    </ul>
  </ekoutput>
</ekmarkup>

Now you simply need to point the ListSummary Server Control at the new file by setting the MarkupLanguage to point to the new file. This is outlined in the following snippet.

<CMS:ListSummary
  ID="uxListSummary"
  FolderID="72"
  Recursive="true"
  MaxResults="5"
  EnablePaging="true"
  OrderBy="Title"
  OrderByDirection="Ascending"
  MarkupLanguage="XmlFilesUnorderedListSummary.ekml"
  runat="server" />

The output of this update is shown in Figure 8-6. As is visible in the output, the HyperLink token is actually replaced by a DMS menu style link. There is a bit more intelligence in the token then there is following the same process with an XSLT. Using EKML can be a great way to simplify your development efforts while creating rich and complex displays.

Figure 8.6. FIGURE 8-6

Creating a system calendar follows the same process as creating a standard folder in the Workarea. The difference is what is displayed in the Content pane after creating it. To create a system calendar:

As you can see, the new event has been added to the event list, along with the details of when the event occurs and what type the event is. This event has the type Original, which means that it is the base definition of the event. The other types are "Variance - Extra Occurrence" and "Variance - Cancelled Occurrence." Extra Occurrence means that it is a member of a recurring series whose details have been changed for that day. A cancellation means that the event that should have occurred on that day, due to a recurrence rule, has been cancelled.

Figure 8.10. FIGURE 8-10

The event is also shown with a DMS Menu instance, which allows content authors to perform immediate actions on the content such as deleting it or moving it through an approval chain. Click the title of the event on the list now to be taken to the detail view of the event. The detail view is also shown in Figure 8-11.

The event detail view does not allow you to edit the event itself, but does allow you to manage the summary, metadata, alias, content scheduling, templates, and taxonomy associations.

User and Group Calendars

User and group calendars are similar to system calendars in that they store events in the same way. The difference is the location that these events are stored internally. When a user or community group is created in the Ektron Framework, the system automatically adds a hidden folder for that user or group. One of the properties available during the creation process is whether to create a calendar for the new object — if checked, then a calendar folder is added underneath the private folder.

The upside to group and user calendars is that they maintain proper permissions automatically for groups and users. The downside is that there is no content interface for the events or calendars in the Workarea the way there is for System Calendars.

Figure 8.11. FIGURE 8-11

Let's create a user calendar now.

1. Start by going to Settings

   

2. Clicking the edit button brings up the edit user properties interface, with a tab labeled Custom, shown in Figure 8-12.

   

   Figure 8.12. FIGURE 8-12

3. On the Custom tab, there are two settings that are related to the calendar:

   • Create User Calendar: Checking this box and saving creates the user calendar and makes it available for use as a data source. It is not possible to roll back the creation of a user calendar or a group calendar, as this can lead to loss of data. It is an option on the user profile for performance reasons — if your users do not create calendars, this can make the system more responsive by reducing the number of folders in the system.

   • Time Zone property: This list is generated from the Windows time zone list. When a user selects a time zone, all calendar events from that time forward are calculated from the version stored (based on GMT) to the user's time zone. This allows users across the globe to all see the event in their appropriate time zones. It is a required field, but if it has not been entered, for example for a user who was created programmatically, the system displays the events in the server time zone.

4. Community groups have a similar method of creating user calendars, but the interface is slightly different. Go to Settings

   
   

   Figure 8.13. FIGURE 8-13

The WebCalendar Server Control is the primary interface for Ektron calendars. The control uses the Telerik Scheduler component internally for rendering, but supports a variety of overrides. Using the server control with its default settings is straightforward. You'll create these examples on a new Web form. Create the Web form in the root of your site and call it Calendars.aspx, shown in Listing 8-4, and drag the WebCalendar Server Control from the toolbox into the form of the new page.

<%@ Page Language="C#" AutoEventWireup="true"
  CodeFile="calendars.aspx.cs" Inherits="calendars" %>
<%@ Register Assembly="Ektron.Cms.Controls"
  Namespace="Ektron.Cms.Controls" TagPrefix="CMS" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Calendars</title>
</head>
<body>
    <form id="form1" runat="server">
      <CMS:WebCalendar ID="uxWebCalendar" runat="server">
      </CMS:WebCalendar>
    </form>
</body>
</html>

The WebCalendar Server Control has a few key properties that are used as attributes on the control, but data sources are encoded as inner XML. Table 8-4 shows the properties.

In addition to the properties listed in Table 8-4, there are internally encoded properties to define the data sources for the calendar. The following code snippet shows a few examples of how this can be achieved.

<CMS:WebCalendar ID="uxWebCalendar" runat="server">
  <DataSource>
    <CMS:CalendarDataSource
      backColor="AutoSelect"
      defaultId="111"
      queryParam="calendarId"
      sourceType="SystemCalendar" />
    <CMS:CalendarDataSource
      backColor="Blue"
      defaultId="222"
      queryParam="groupCalendarId"
      sourceType="GroupCalendar" />
    <CMS:CalendarDataSource
      backColor="DarkRed"
      defaultId="333"
      queryParam="userCalendarId"
      sourceType="UserCalendar" />
  </DataSource>
</CMS:WebCalendar>

The WebCalendar in the previous snippet has three sources defined. Each source then has several properties. Table 8-5 outlines the properties for CalendarDataSource.

In addition to these baseline data source properties, the CalendarDataSource tag also supports an inner encoded list of taxonomy IDs to use as a filter against the particular source. For instance, a developer can specify that the calendar should only show events from category ID 23 or 24 that are in system calendar 432 using the following code snippet.

<CMS:WebCalendar ID="uxWebCalendar" runat="server">
  <DataSource>
    <CMS:CalendarDataSource
        backColor="AutoSelect"
        defaultId="432"
        sourceType="SystemCalendar">
      <CMS:CategoryID categoryId="23" />
      <CMS:CategoryID categoryId="24" />
    </CMS:CalendarDataSource>
  </DataSource>
</CMS:WebCalendar>

All of these settings can be configured through codebehind, allowing for items like a taxonomy tree filter to be applied to the WebCalendar. The properties are stored as generic lists, making it straightforward to manage the sources. The following example achieves the same effect as the previous snippet.

Ektron.Cms.Controls.CalendarDataSource Source;
Source = new Ektron.Cms.Controls.CalendarDataSource();
Source.backColor = Ektron.Cms.Controls.EventColor.AutoSelect;
Source.defaultId = 432;
Source.sourceType = Ektron.Cms.Controls.SourceType.SystemCalendar;

Source.CategoryIDs.Add(new Ektron.Cms.Controls.CategoryID(23));
Source.CategoryIDs.Add(new Ektron.Cms.Controls.CategoryID(24));

uxWebCalendar.DataSource.Add(new Ektron.Cms.Controls.CalendarDataSource());
uxWebCalendar.Fill();

These steps allow you to display calendars on your site with a minimum of fuss, while achieving a rich interface for your users and administrators. Deeper customizations can also be performed on the WebCalendar — three main areas that people frequently want to customize on the WebCalendar are the event rendering, the event editing form, and the styling on the calendar.

When referring to the event rendering of the WebCalendar, we are talking about the information displayed for each event in the day, week, or month view. An example of the bubble is shown in Figure 8-14. This bubble is created through the instantiation of a user control that is normally in the Workarea at ~/Workarea/WebCalendar/DefaultTemplate/Display.ascx. To override this display, copy the user control from the Workarea to another location on your site, and update the property DisplayTemplatePath on the WebCalendar to reflect the new location. The user control can then be modified to display anything you want.

Figure 8.14. FIGURE 8-14

As mentioned earlier, another common need is to modify the event editing form. This is also a user control in the Workarea that is instantiated on demand. In this case, the user control is stored at ~/Workarea/WebCalendar/DefaultTemplate/AdvancedForm.ascx. There is no property that allows this to be overridden to another location, but as the control is exposed, modifications can be made directly to the control to support alternate functionality.

A final common set of modifications made to the WebCalendar is to customize the CSS included by the control. The property CssFile allows you to point the WebCalendar somewhere other than the default location for the CSS. The unmodified file is stored in ~/Workarea/WebCalendar/View/WebCalendar.css. To modify it, copy it somewhere else in the site, and update the CssFile property to point at the new location. Inside the file, the style rules are broken into three main sections. The file starts with the styles defined for the advanced form, followed by the base layout styles for the WebCalendar view. That is then followed by a theme section, which defines the look and feel including colors and images.

Events stored in Ektron calendars are stored as a subtype of content. What this means is that all the features that standard HTML content supports are also supported by WebCalendar events, including taxonomy, metadata, search, permissions, and workflow.

Additionally, since the events are stored in what is effectively a folder, they can be displayed by most controls as standard content. For example, it is possible to use a ListSummary Server Control to display a list of events from a calendar. As an example, the following code snippet will output the result shown in Figure 8-15.

<form id="form1" runat="server">
  <CMS:ListSummary runat="server" ID="uxListSummary" FolderID="124" />
</form>

Figure 8.15. FIGURE 8-15

The tradeoff with this approach comes from how the events are stored under-the-hood. As mentioned earlier, the events are stored similarly to the iCalendar standard. What this means is that the rules for recurrence are stored as part of a master event, and that additional occurrences or cancellations of recurrences are stored as variances in secondary content. The outcome of this type of storage is that if you have an event that recurs every week, it only shows up once as a single piece of content. If you then cancel a single occurrence of the event, the cancellation shows up as a second piece of content. If you were then to modify a different occurrence and save it, you end up with four total pieces of content. One of the additional items is the cancellation for that day, and the other is the additional variance for that day.

For some uses this is fine, as you can write a custom XSLT against the XML to display what you need from the event details, but in other cases you will be actually looking for a list of upcoming events, which is covered later in this section.

In the same way the ListSummary Server Control can display a list of events from a calendar, you can use the Content Block Server Control to display a detail view of an individual event. The Ektron Framework internally uses an XSLT to transform the stored data for the event into a standardized display layer. You can then combine this display layer with other standard Ektron controls, such as the MessageBoard Server Control, to create a rich interface for people to interact with these events. This section covers how to display the event on a Content Block Server Control, as well as how to modify the display of the event by changing the XSLT.

In the Smart Form section of Chapter 6, you read how Smart Form designs are stored in packages. A package contains five major elements, from the schema to the input form. The key part of the package that is used to display the data in a content block, however, is the default XSLT.

Events in the Ektron Framework are based at their core on a Smart Form, which means the behavior is almost exactly the same as any other Smart Form.

This includes the way the data is rendered through the Content Block Server Control. The hidden Smart Form package contains a default XSLT that has the smarts to render the event definition in an appropriate manner, depending on the language and time zone of the user. When an event ID is specified for a Content Block Server Control, it automatically renders the event using that predefined XSLT. In this section, you render the event you created earlier using a content block. Once you've investigated how the system behaves by default, you'll learn how to create a custom XSLT for rendering the data, while maintaining the intelligence supplied in the original.

To render an event into a Content Block Server Control, you need to know the event's ID:

Figure 8.17. FIGURE 8-17

While, the output is a bit bland, the markup is clean enough, so the display layer can be formatted using CSS to match the site it is being displayed on. But if you want to use different words for some of the output, or change the order, or even skip some elements, a copy of the XSLT used in the package is also provided in ~/Workarea/WebCalendar/XSL/default.xslt. This file can be copied elsewhere into your site, modified at will, and then used to override the default package XSLT for Web events.

To point your content block at the custom XSLT, use the DisplayXSLT property on the Content Block Server Control. For example, on your site you copied the default XSLT to the XMLfiles directory, so you could update your content block code to look like the following snippet. Once you have rewired it to use your custom XSLT, you can modify the webevent.xslt file until you are satisfied with the format or language.

<form id="form1" runat="server">
  <CMS:ContentBlock
    runat="server"
    DisplayXslt="~/XmlFiles/webevent.xslt"
    ID="uxContentBlock"
    DefaultContentID="252" />
</form>

The XSLT file itself is fairly complex, and this section doesn't go into it in depth, but there are a few decisions that were made in the development of the WebCalendar system that may not be apparent immediately. The main item to note is the custom extension functions that are used in the XSLT — specifically ekext:convertUTCtoLocal and ekext:formatDateTime. By using the Saxon processor packaged with the Ektron Framework to perform an XSLT2 conversion rather than an XSLT1 conversion, Ektron could have avoided the need for these custom extensions, as date logic is included with the XSLT2 specification. However, the decision to use custom extensions was made for two reasons: The localization included with the Saxon processor does not include data for all regions, meaning that in some cases the localization of dates would fail. Additionally, by moving the functions into the core Ektron stack, the XSLT became substantially simpler.

The WebCalendar infrastructure also has a rich API for retrieving and modifying events. The majority of this API can be accessed through the Ektron.Cms.Framework.Calendar.WebEvent class, but there are a few additional functions available only through the Ektron.Cms.Content.Calendar .WebEventManager class. Many of these functions are self-explanatory. For example there are functions to Add, Delete, Update, and CancelOccurence. But the key function covered right now is the GetEventOccurenceList function.

Whereas the ListSummary Server Control was useful in showing a list of events from the perspective of content — one item per event definition, regardless of recurrences — the GetEventOccurenceList is used to expand the recurrence rules into a full set of event occurrences, and then correlate them with cancellations and additional occurrences. What this means is that when you call GetEventOccurenceList you get output that matches exactly what you see on the WebCalendar display for a given time period.

The output of this function is not added into a mode of display on the WebCalendar Server Control because it is very straightforward to use one of the standard ASP.NET controls to display the output. A common method of displaying the event list is to use the ASP.NET Repeater Server Control.

Let's walk through an example now of setting up the retrieval and display.

Now when you visit Calendar.aspx in your browser, you should get output like that shown in Figure 8-18.

Figure 8.18. FIGURE 8-18

For posterity's sake, Listing 8-5 lists the complete code (both declarative and codebehind) for the Calendar.aspx and Calendar.aspx.cs files.

<%@ Page Language="C#" AutoEventWireup="true"
  CodeFile="calendars.aspx.cs" Inherits="calendars" %>
<%@ Register Assembly="Ektron.Cms.Controls"
  Namespace="Ektron.Cms.Controls" TagPrefix="CMS" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title>Calendars</title>
</head>
<body>
<form id="form1" runat="server">
  <asp:Repeater ID="uxRepeater" runat="server">
    <ItemTemplate>
      Event Name: <%# (Container.DataItem as
        Ektron.Cms.Common.Calendar.WebEventData).DisplayTitle%>
      <br />
      Event Start: <%# (Container.DataItem as
        Ektron.Cms.Common.Calendar.WebEventData).EventStart.toString()%>
      <br />
      Event Location: <%# Container.DataItem as
        Ektron.Cms.Common.Calendar.WebEventData).Location")%>
      <br /><br />
    </ItemTemplate>
  </asp:Repeater>
</form>
</body>
</html>

using System;
using System.Collections.Generic;
using System.Linq;
using System.Web;
using System.Web.UI;
using System.Web.UI.WebControls;

public partial class calendars : System.Web.UI.Page
{
    protected void Page_Load(object sender, EventArgs e)
    {
      List<Ektron.Cms.Common.Calendar.WebEventData> eventList;

      Ektron.Cms.Content.Calendar.WebEventManager webEventApi;

webEventApi = new Ektron.Cms.Content.Calendar.WebEventManager();
      eventList = webEventApi.GetEventOccurrenceList(
        88, DateTime.Now, DateTime.Now.AddMonths(1));

      uxRepeater.DataSource = eventList;
      uxRepeater.DataBind();
    }
}

One final frequently asked question about the feature set that WebCalendars provides is how to export events from the Ektron Framework and import them into another application such as Outlook, and vice versa. The Ektron Framework does not support importing iCal or vCal files from other sources, but it generates them in order to move events from the framework to another software platform.

In fact, the default interface for the WebCalendar Server Control includes a link to download the .ICS file for each event. By hovering over the event link, the event bubble appears on the calendar, including a download link, as seen in Figure 8-19.

Figure 8.19. FIGURE 8-19

The download link in the bubble points to the file ~/Workarea/WebCalendar/View/IcalGenerator .ashx and includes the query string parameter eventid. This file generates feeds for entire calendars as well, by specifying the calid query string parameter instead. This ability allows for programs to have live feeds of calendars if they support it.

The feed generated supports version 2 of the iCal standard, which allows it to also specify the originating time zone information for the event. This means that whenever users worldwide add the event to their calendars, the event appears in their local time zones, and respects the translation effects of moving across potentially two daylight savings boundaries in the case of a recurring event.

Adding assets to the framework is an action performed in the Workarea.

Figure 8.21. FIGURE 8-21

Figure 8.22. FIGURE 8-22

Click the file now to bring up the properties. In this interface, you can see that working with your assets is exactly the same as working with normal HTML content, with all the same capabilities.

Editing the settings on the uploaded Flash video also works the same way as normal content. Simply click the edit icon on the toolbar, and you will be shown all the options available for the current type of content. The edit screen is shown in Figure 8-23.

Figure 8.23. FIGURE 8-23

The main difference from normal content is that the Content tab shows a series of options that affect how the Flash object is shown on the site. The options differ based on whether the object is a SWF or other type of media. These options are outlined in Table 8-6.

In addition to the options on this screen, there is a preview of the object, as well as an upload interface. Remember that to update the object with a new version, it must have the same name; otherwise it is uploaded as a different object in the DMS.

These settings are applied whenever the item is displayed through a Content Block Server Control, and are implemented through setting the correct parameters on the object tag that is written to the page. Flash objects can override certain of these settings, but in general they can help you to achieve the exact look and feel you desire for your site.

Working with objects in the DMS is very straightforward. All the logic to print the correct HTML to the page is contained in the Content Block Server Control, which means all you need to display them is that same control. Let's test it out by creating a new page in the root of the site called Video.aspx. Drag a Content Block Server Control onto the page so it looks like the code in Listing 8-6.

<%@ Page Language="C#" AutoEventWireup="true"
  CodeFile="Video.aspx.cs" Inherits="Video" %>

<%@ Register Assembly="Ektron.Cms.Controls"
  Namespace="Ektron.Cms.Controls" TagPrefix="CMS" %>

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
<head runat="server">
    <title></title>
</head>
<body>
    <form id="form1" runat="server">
    <div>
      <CMS:ContentBlock
        ID="ContentBlock1"
        runat="server"
        DefaultContentID="86" />
    </div>
    </form>
</body>
</html>

Return to the Workarea and make sure your file has been published and then view the properties to find out the content ID of the video. Replace the number 86 with the appropriate value for your object. When you save the file and view it in the browser, you will see your video playing with your options.

The Ektron Framework works very well for certain situations, such as rich applications, or raw SWF files containing video. However, it isn't the end-all be-all when it comes to video. For instance, FLV videos, which require a Flash video player to be displayed, will not work with just a Content Block Server Control to display them. There is, however a Flash Widget that can be used with PageBuilder to display FLVs.

Ability to display is not the only consideration when making a choice about how to deliver your content. Also keep in mind that video is one of the most bandwidth-intensive functions you can perform with a site. Additionally, because of the way ASP.NET is structured, it is not very good at keeping connections open for long periods of time, which is something that downloading large files, like video, requires. There is also the question of the ability to stream files — ASP.NET can be configured to do stream files, but it does require some hacking around in the system to get streaming working.

Ektron is aware of these considerations. One solution supplied by Ektron is the BrightCove Widget, which integrates with the third-party vendor to allow you to create a collection of videos that can be displayed on your site with solid analytics and a clean player.

Another common solution is to use a free service like YouTube to manage your videos, and then embed the player onto your page. All of these options allow you to easily share videos with potential clients and site visitors.