Registering custom pipes in Sitefinity

August 16, 2011 Digital Experience, Sitefinity

Introduction

Prior to Sitefinity 4.2 it was not possible or at least not easy to change or extend the publishing system of Sitefinity. That's why we reworked the publishing system with the idea one to be able to extend it or change it easily. The main idea is to add information to a factory about how pipe are constructed and this information to be modified when someone wants to. The factory which stores that information is named PublishingSystemFactory and has static methods for adding, getting and removing components used for creating pipes.

Here are a few words about these components:

PipeSettings - this class holds all information for creating a pipe. It is persistent and it is used to restore a pipe saved in the database.

Mappings - this class contains information how data is transformed when moving through the pipe. The mappings are part of the PipeSettings and are persistent.

Definitions - this is a collection of items describing the type members used by the mappings. They are used in the UI for changing the default mappings and they are not persistent.

Template - this is another thing used in the UI. It describes which pipes will be displayed in the Create and Edit screens for search indexes and feeds. They are not persistent.

Note: By using the methods of the PublishingSystemFactory you cannot change the settings and mappings of existent publishing points (feeds), because they are persistent.

Using the methods of PublishingSystemFactory

All built-in Sitefinity pipes use the PublishingSystemFactory for getting their components. This means that one can change the default components of the built-in pipes and thus change the way they work. One even can replace a built-in pipe by calling the necessary methods:

PublishingSystemFactory.UnregisterPipe(PageInboundPipe.PipeName);

and

PublishingSystemFactory.RegisterPipe(PageInboundPipe.PipeName, typeof(MyPageInboundPipe));
So registering and configuring pipes is done through code. There are several steps that have to be completed before a pipe is successfully registered to Sitefinity.

The first is to choose where to place your code. One possible place is where you initialize your module. But if you change the settings of the built-in pipes you have to be sure that this is done after SearchModule and PublishingModule are initialized. The best moment to register a custom pipe is after all modules including PublishingModule are initialized. This moment is Bootstrapper.Initialized event and in its event handler we can write our code for registering the custom pipe.

The first thing we do is to register the custom pipe as a type with the following code:

PublishingSystemFactory.RegisterPipe("MyCustomPipeName", typeof(MyCustomPipe));

After that we register the pipe settings, the mappings, the definitions and eventually we add the pipe to the search template depending on whether we want the pipe to be used by a search index. Registering the pipe settings and the mappings is mandatory, while the definitions may be implemented to be returned directly by the pipe and adding the pipe to a template may be skipped.

Most of the methods in PublishingSystemFactory has the following signature:

void RegisterXXX(string pipeName, XXX xxx); // Registers the XXX component
bool XXXRegistered(string pipeName); // Checks if the XXX component is registered
void UnregisterXXX(string pipeName); // Unregister the XXX component
void UnregisterAllXXX(); // Unregister all XXX components
XXX GetXXX(string pipeName); // Gets a XXX component

and possibly

XXX CreateXXX(string pipeName, PublishingManager manager); // Gets a persistent ready component
 

Registering the pipe settings

First get default pipe settings:

PipeSettings pipeSettings = PublishingSystemFactory.CreateDefaultContentInboundPipeSettings("MyCustomPipeName");

or create pipe settings like this:

PipeSettings pipeSettings = new PipeSettings();
pipeSettings.IsActive = true;
pipeSettings.IsInbound = false;
pipeSettings.InvocationMode = PipeInvokationMode.Push;

and then register them:

PublishingSystemFactory.RegisterPipeSettings("MyCustomPipeName", pipeSettings);

We can call a built-in method (e.g. CreateDefaultContentInboundPipeSettings) to get pipe settings but one can write his/her own. Passing the name of your custom pipe is mandatory because this name is set to the PipeName property of the PipeSettings. To get the registered pipe settings of a pipe one calls

GetPipeSettings(string pipeName)
(Note that this method returns a copy of the registered settings, so modifying them will not affect the original ones). If you want to get pipe settings that will be persisted one should call
CreatePipeSettings(string pipeName, PublishingManager manager)
This method also adds the registered mappings for this pipe to the pipe settings. To add or to update pipe settings use
RegisterPipeSettings(string pipeName, PipeSettings settings)
There are a few more methods for checking if pipe settings are registered for a pipe, and for removing the pipe settings for one particular pipe of for all pipes.

Unfortunately there is no possibility to create a class that inherits one of the built-in classes for PipeSettings. The problem lies in a limitation in Sitefinity/OpenAccess for mapping inheriting classes. That is why we added a new persisted property to PipeSettings class. The property is of type IDictionary<string, string> and is named AdditionalData. A developer can use this property to add his/her specific data.

Changing the default pipe settings of the built-in pipes

The PublishingSystemFactory can be used to change the default components of the pipes. For example by default the MaxItems property of the pipe settings (this property defines how many items a pipe will provide) used by the ContentInboundPipe is 25. If a developer wants to change this number he/she can use this code:

var pipeSettings = PublishingSystemFactory.GetPipeSettings(ContentInboundPipe.PipeName);
pipeSettings.MaxItems = 50;
PublishingSystemFactory.RegisterPipeSettings(ContentInboundPipe.PipeName, pipeSettings);
 

Registering the pipe mappings

Get default pipe mappings:

List<Mapping> mappingsList = PublishingSystemFactory.GetDefaultInboundMappingForContent();

or create pipe mappings like this:

List<Mapping> mappingsList = new System.Collections.Generic.List<Mapping>();
var contentMapping =
    new Mapping()
    {
        DestinationPropertyName = "Content",
        IsRequired = true,
        SourcePropertyNames = new[] { "Title" }
    };
mappingsList.Add(contentMapping);
var linkMapping =
    new Mapping()
    {
        DestinationPropertyName = "Link",
        IsRequired = true,
        SourcePropertyNames = new[] { "Link" }
    };
linkMapping.Translations.Add(new PipeMappingTranslation()
    {
        TranslatorName = UrlShortenerTranslator.TranslatorName
    }
);
mappingsList.Add(linkMapping);
and register them:

PublishingSystemFactory.RegisterPipeMappings("MyCustomPipeName", true, mappingsList);

Again we can use one of the built-in methods to get a list of mappings but one can implement his/her own. There is an extra parameter when calling RegisterPipeMappings method. This parameter specifies whether the pipe is inbound or outbound (correspondingly we pass true or false). This is necessary because one pipe can be used for both purposes - to pass data to a publishing point or to take data from a publishing point. In these two cases the pipe may need different mappings. To get the registered mappings for one pipe one should use

GetPipeMappings(string pipeName, bool isInbound)
If you want to get pipe mappings that will be persisted then you should call
CreateMappingSettings(string pipeName, bool isInbound, PublishingManager manager)

Registering the pipe definitions

Get default pipe definitions:

IDefinitionField[] definitions = PublishingSystemFactory.CreateDefaultRSSPipeDefinitions();

or create pipe definitions like this:

IDefinitionField[] definitions = new IDefinitionField[]
{
    new SimpleDefinitionField(PublishingConstants.FieldContent, Res.Get<PublishingMessages>().RssContent),
    new SimpleDefinitionField(PublishingConstants.FieldLink, Res.Get<PublishingMessages>().RssLink)
};
and register them:
PublishingSystemFactory.RegisterPipeDefinitions("MyCustomPipeName", definitions);

We can use one of the built-in methods to get an array of definitions but one can implement his/her own. To get the registered definitions for one pipe one should use

GetPipeDefinitions(string pipeName)
Instead of registering pipe definitions and later use them in your pipe you can directly place them in your pipe:
public IDefinitionField[] Definition
{
    get
    {
        if (this.definitionFields == null)
        {
            this.definitionFields = new SimpleDefinitionField[]
            {
                new SimpleDefinitionField(PublishingConstants.FieldContent, Res.Get<PublishingMessages>().RssContent),
                new SimpleDefinitionField(PublishingConstants.FieldLink, Res.Get<PublishingMessages>().RssLink)
            };
        }
        return this.definitionFields;
    }
}

instead of:

public IDefinitionField[] Definition
{
    get
    {
        if (this.definition == null)
        {
            this.definition = PublishingSystemFactory.GetPipeDefinitions(this.Name);
        }
        return this.definition;
    }
}
 

Registering the pipe templates

This is quite easy:

var pipeSettings = PublishingSystemFactory.GetPipeSettings("MyCustomPipeName");
PublishingSystemFactory.RegisterTemplatePipe("SearchItemTemplate", pipeSettings);
This code will add your inbound pipe as an option when creating a search index. Currently there are two templates: "SearchItemTemplate" and "PublishingItemTemplate" and only the former has a useful application outside Sitefinity.

 

To sum up all the code samples above here I'll give you the code used for registering the ProductInboundPipe inside our Publishing module. I want to point that this code is just for reference what your code should look like at the end. If you are looking for a working sample please look at this post http://www.sitefinity.com/blogs/teodorgeorgiev/posts/11-08-18/publishing_system_brief_walkthrough.aspx

//Subscribe for the Initialized event
public override void Initialize(ModuleSettings settings)
{
    /* ... */
    Bootstrapper.Initialized -= Bootstrapper_Initialized;
    Bootstrapper.Initialized += Bootstrapper_Initialized;
}
 
protected void Bootstrapper_Initialized(object sender, Telerik.Sitefinity.Data.ExecutedEventArgs e)
{
    //Check if all modules are initialized
    if (e.CommandName == "Bootstrapped")
    {
        this.RegisterProductPipe();
    }
}
 
private void RegisterProductPipe()
{
    //Check if the module is initialized and active
    var catalogModule = SystemManager.GetApplicationModule(CatalogModule.moduleName);
    if (catalogModule == null || catalogModule is InactiveModule)
        return;
 
    //Check if the pipe is already registered
    if (PublishingSystemFactory.PipeSettingsRegistered(ProductInboundPipe.PipeName))
        return;
 
    //Register the type of the pipe
    PublishingSystemFactory.RegisterPipe(ProductInboundPipe.PipeName, typeof(ProductInboundPipe));
 
    //Get the default mappings and register them
    var mappingsList = ProductInboundPipe.GetDefaultInboundMappingForProduct();
    PublishingSystemFactory.RegisterPipeMappings(ProductInboundPipe.PipeName, true, mappingsList);
 
    //Get the default pipe settings and regiser them
    var pipeSettings = (SitefinityContentPipeSettings)PublishingSystemFactory.CreateDefaultContentInboundPipeSettings(ProductInboundPipe.PipeName);
    pipeSettings.ContentTypeName = typeof(Telerik.Sitefinity.Ecommerce.Catalog.Model.Product).FullName;
    PublishingSystemFactory.RegisterPipeSettings(ProductInboundPipe.PipeName, pipeSettings);
 
    //Get the previously registered settings and register them for the template used by the search index UI
    var contentPipeSettings = (SitefinityContentPipeSettings)PublishingSystemFactory.GetPipeSettings(ProductInboundPipe.PipeName);
    contentPipeSettings.ContentTypeName = typeof(Telerik.Sitefinity.Ecommerce.Catalog.Model.Product).FullName;
    contentPipeSettings.MaxItems = 0;
    PublishingSystemFactory.RegisterTemplatePipe("SearchItemTemplate", contentPipeSettings, ps => ps.PipeName == ProductInboundPipe.PipeName);
 
    //Get the default definitions and register them
    var contentPipeProductsDefinitions = ProductInboundPipe.CreateDefaultProductPipeDefinitions();
    PublishingSystemFactory.RegisterContentPipeDefinitions(ProductInboundPipe.PipeName, typeof(Telerik.Sitefinity.Ecommerce.Catalog.Model.Product).FullName, contentPipeProductsDefinitions);
}
 

Summary

In this post I tried to give you all the basic information to set up your custom pipe for using is Sitefinity. It may seem a lot of effort to do this but actually it's not so hard if you follow the samples above and especially the last one. If you have any questions or a remarks please write them down.

API Code samples Guides Publishing System Sitefinity 4.2

The Progress Team