Retrieving Data From Dynamic Modules Using the Module Builder API

Last week, Gabe introduced us to the Module Builder, Sitefinity's latest feature available now since version 4.4. Gabe demonstrated the intuitive way the Module Builder can extend Sitefinity by creating a simple Showcases module (similar to our own Sitefinity Showcase).

In this post, we'll take a closer look at how you can use the Module Builder API, as well as the new Code Reference (which generates code samples for every dynamic module you create) to create a simple custom control that uses the dynamic module data.

Telerik Controls: RadRotator

One of the many advantages of Sitefinity is that it includes access to the full suite of Telerik RadControls, including the one we'll be using: RadRotator. Using this and other controls from the suite allows you to quickly add useful and powerful widgets to your Sitefinity website.

Widgets: Custom User Controls

As I've mentioned previously, Widgets in Sitefinity are simply ASP.NET User Controls, so we begin by adding a new control to our project, and add the rotator, adding a few properties to match our needs.

<telerik:RadRotator ID="ContentSlider" runat="server" Width="880" Height="300" ItemWidth="250" PauseOnMouseOver="true" FrameDuration="5000" RotatorType="Buttons">
</telerik:RadRotator>

Codebehind: Retrieving and Binding Data

All we need to do for this control is retrieve a list of items from the dynamic Showcases module. This requires creating an instance of the DynamicModuleManager with the Showcases type and calling the GetDataItems method. This is demonstrated in the code sample below.

Because we only want to retrieve featured items, we also need to add a Where method with our filter. Notice that, because the module is dynamic, we have to pass in a string to filter against the dynamic fields of the module.

However, because all content items (even dynamic ones) inherit from content, they also inherit several of the basic properties, such as Status. This allows us to add an additional, strongly-typed Where method to only retrieve published items.

Finally, once we have the desired items, we simply bind them to the Rotator. We do this all on the Load method of the control, as shown in the complete code snippet below.

public partial class Slider : System.Web.UI.UserControl
{
    protected void Page_Load(object sender, EventArgs e)
    {
        var dynamicModuleManager = DynamicModuleManager.GetManager();
        Type showcaseType = TypeResolutionService.ResolveType("Telerik.Sitefinity.DynamicTypes.Model.Showcases.Showcase");

        // This is how we get the collection of ContentPage items
        var showcases = dynamicModuleManager.GetDataItems(showcaseType).Where("Featured == true").Where(s => s.Status == Telerik.Sitefinity.GenericContent.Model.ContentLifecycleStatus.Live);

        ContentSlider.DataSource = showcases;
        ContentSlider.DataBind();
    }
}

Binding to Fields

Databinding is easy for simple fields, such as those that are of data type ShortText. You simply need to use the <% Eval() %> syntax using the field name.

However, many field types have more complex data types. For example, Media fields use an array of items of type ContentLink. This is the type used by our Screenshot field.

In order to render the actual Screenshot value (in this case an image), we need to retrieve the image associated by the ContentLink. We do this by first creating a helper method in the code behind that extracts the image from a dynamic item when it is bound to the repater.

protected string GetImageUrl(object item)
{
    var retval = string.Empty;

    // ensure correct item type
    var showcase = item as DynamicContent;
    if (showcase == null) return retval;

    // retrieve the Screenshot value and extract the first (and only) item
    var contentLinks = (ContentLink[])showcase.GetValue("Screenshot");
    ContentLink imageContentLink = contentLinks.FirstOrDefault();

    // retrieve the image using the extracted items Id
    LibrariesManager libraryManager = LibrariesManager.GetManager();
    var image = libraryManager.GetImage(imageContentLink.ChildItemId);
    if (image == null) return retval;

    // return the image url to the template
    retval = image.Url;
    return retval;
}

Notice we use Object so that we don't have to cast the item on the front end (and also to avoid exceptions if there is a null or invalid item).

Now all we need to do is call this item from our template, passing in the entire data item as the argument. Here is the completed RadRotator with the data template.

<telerik:RadRotator ID="ContentSlider" runat="server" Width="880" Height="300" ItemWidth="250" PauseOnMouseOver="true" FrameDuration="5000" RotatorType="Buttons">
    <ItemTemplate>
        <div style="text-align: center">
            <a href="/showcases/<%# Eval("Urlname") %>">
                <img src="<%# GetImageUrl(Container.DataItem)  %>" alt="" class="thumb wp-post-image" width="205" height="155" />
            </a>
        
            <h4><%# Eval("Company")%></h4>
            <div><a href="<%# Eval("SiteUrl")%>"><%# Eval("SiteUrl") %></a></div>
        </div>
    </ItemTemplate>
</telerik:RadRotator>

Now we just build the project, add the control to the toolbox, drop it on a page and we're done:

Wrapping Up

With only a few lines of code and the slick RadRotator, we were able to create a simple but useful slider for our dynamic module. Be sure to check out the Code Reference (generated for every dynamic module you create) for more code samples that you can use in your custom controls.

Next time, we'll see how you can use the API to create a widget that can create new content items. Until then, grab the sample Showcases project from Gabe's Module Builder Webinar notes and be sure to share your feedback with us.