Configure content providers

A content provider serves external data as IContent objects (for example, PageData instances) when registered with Optimizely Content Management System (CMS). A CMS site supports multiple registered content provider instances, each with its own configuration data such as capabilities settings.

Register a content provider with CMS through ContentOptions.Providers or the EPiServer.Core.IContentProviderManager API interface, accessed through the IOC container.

📘

Note

A custom content provider cannot deliver the start page, root page, and waste basket (recycle bin, trash).

Register a content provider

Configure content providers during registration. Add attributes for the content provider type, which pass into the provider instance at initialization.

services.Configure<ContentOptions>(o => o.AddProvider<XmlContentProvider>("xml", config => {
    config[ContentProviderParameter.EntryPoint] = _configuration.GetValue<string>(ContentProviderParameter.EntryPoint);
    config[ContentProviderParameter.Capabilities] = ContentProviderParameter.FullProviderCapability;
    config["someConfigKey"] = "someConfigValue";
}));

The provider type and name are required. Built-in optional configuration values include entryPoint, capabilities, iconPath, and wastebasketName. Specific content providers define additional configuration values as needed.

• entryPoint – Specifies the existing CMS page that serves as the root for content from this provider instance. The entryPoint page must have no existing children in CMS. Without an entry point, the provider does not display in the page tree.
• iconPath – Displays a custom icon in the page tree for each page served by the provider. Set a relative path to \Images\ExplorerTree\PageTree\ in the themes folder. For example, placing _custom.gif in App_Themes\Default\Images\ExplorerTree\PageTree requires an iconPath value of _custom.gif.
• wastebasketName – The name of the content provider's Recycle Bin. Defaults to the registered provider name.

Capabilities

Capabilities define the operations a content provider supports. Specify multiple capabilities with a comma-separated list when registering the provider.

• Create – Creates content. Requires implementing the Save method.
• Edit – Edits existing content. Requires implementing the Save method.
• Delete – Removes existing content. Requires implementing the Delete and DeleteChildren methods.
• Copy – Replicates content internally within the content provider. Cross-provider copy requires the Create capability. Requires implementing the Copy method.
• Move – Moves content internally within the content provider. Cross-provider moves require the Create and Delete capabilities. Requires implementing the Move method.

  📘

  Note

  Moving content between content providers requires the user permission: Move between page providers.

• MultiLanguage – Supports multiple language versions. Requires implementing DeleteLanguageBranch and handling multiple languages in the Save method. The provider must also respect the ILanguageSelector passed when serving content.
• Search – Searches within content properties served by the provider. Requires implementing FindPagesWithCriteria when the class implements IPageCriteriaQueryService and inherits ContentProvider.
• Security – Checks access for content delivered by the provider through the ISecurable interface on IContent instances. Without this capability, providers with an entryPoint perform access checks on the entry point page, and content inherits its access control list (ACL). Without Security and without an entryPoint, no access check occurs.
• Wastebasket – Moves content served by the provider to the wastebasket. Requires implementing MoveToWastebasket. Providers that support Delete but not Wastebasket delete content directly without moving it to a wastebasket.

Use ContentProvider for implementation

Each class registered as a content provider must inherit the EPiServer.Core.ContentProvider base class in EPiServer.dll assembly.

Use the EPiServer.Construction.IContentFactory class to create IContent instances.

📘

Note

• ContentReference properties can point to content from an external provider or external content source. Editors load and update content normally.
• ContentArea and ContentAreaItem properties can reference content from a provider (like commerce) but cannot reference content from external sources. Attempts to save such references are gracefully handled (ignored or validated) without breaking the page or block.

Search one or more content provider instances

Make a content provider searchable by registering it with the Search capability. The registered class must implement FindPagesWithCriteria when it implements IPageCriteriaQueryService and inherits ContentProvider.

The following example calls FindPagesWithCriteria to search specific content providers. Add a PropertyCriteria to PropertyCriteriaCollection for each provider. Name the property EPI:MultipleSearch and set the value to the content provider name.

PropertyCriteriaCollection crits = new PropertyCriteriaCollection();
PropertyCriteria crit = new PropertyCriteria();
crit.Name = "EPI:MultipleSearch";
crit.Value = "CustomKey";
crits.Add(crit);
ServiceLocator.Current.GetInstance<IPageCriteriaQueryService>().FindPagesWithCriteria(customPageRef, crits);

Search all custom content providers

Search all custom content providers by defining one PropertyCriteria named EPI:MultipleSearch with the value *.

PropertyCriteriaCollection crits = new PropertyCriteriaCollection();
PropertyCriteria crit = new PropertyCriteria();
crit.Name = "EPI:MultipleSearch";
crit.Value = "*";
crits.Add(crit);
ServiceLocator.Current.GetInstance<IPageCriteriaQueryService>().FindPagesWithCriteria(customPageRef, crits);

Search the default content provider

Without a PropertyCriteria named EPI:MultipleSearch, search runs against the default content provider, which serves content from the CMS database.

📘

Note

Only the default content provider has a full-text search implemented. Optimizely does not index (and therefore does not search) content served by custom content providers.