Is this really the version you are looking for? Kentico 8 documentation is no longer updated. Use the switch in the header to choose your Kentico version.

CMSViewer

The CMSViewer control displays a list of document data.

  • Uses XSLT transformations to define the output format.
  • Provides a built-in data source for loading Kentico documents. You do not need to write code for retrieving and binding the data.

Web part equivalent (portal engine): XSLT viewer

Getting started

The following tutorial shows how to use the CMSViewer control to display a single news article (CMS.News document):

  1. Create a new Web form in your web project.
  2. Drag the CMSViewer control from the toolbox onto the form.
  3. Set the following properties for the control:

    • ClassNames: CMS.News

    • Path: /News/New-Consulting-Services

    • TransformationName: cms.news.default_xslt

    <cms:CMSViewer ID="CMSViewer1" runat="server" ClassNames="CMS.News" Path="/News/New-Consulting-Services" TransformationName="cms.news.default_xslt" />
  4. Save the web form.

  5. Right-click the web form in the Solution explorer and select View in Browser.

The resulting page displays the content of the specified News article:

 

Configuration

You can set the following properties for the CMSViewer control:

CMSViewer properties

Description

Sample value

HideControlForZeroRows

Indicates whether the control should be hidden when no data is loaded. The default value is False.

 

SelectedItemTransformationName
______________________________

Name of the XSLT transformation applied to the selected item.

Enter the transformation name in format <document type code name>.<transformation name>.

 

TransformationName

Name of the XSLT transformation applied to standard items.

Enter the transformation name in format <document type code name>.<transformation name>.

"cms.news.default_xslt"

ZeroRowsText

Text shown when the control is hidden by the HideControlForZeroRows property.

 

Document filtering properties

Description

Sample value

CheckPermissions

Indicates if the control checks the permissions of the user viewing the page. If the value is false (default value) no permissions are checked.

If true, the control only loads documents for which the user viewing the page has read permissions.

 

ClassNames
______________________________

Specifies which document types the control loads and displays. Identify document types through their code names, separated by semicolons (;).

You can use the * wildcard as a substitute for any number of characters. For example Product.* includes the document types Product.Camera, Product.CellPhone, Product.Computer etc.

If the property is left empty, the control retrieves all document types by default. In the case of menu and navigation controls, only page (CMS.MenuItem) documents are loaded by default.

Note: If the control loads all document types (empty value), only the common data columns from the View_CMS_Tree_Joined view are available in the retrieved data. The specific fields of individual document types are not included. You need to keep this in mind when writing the code of transformations, WHERE conditions, ORDER BY expressions etc.

"cms.news"
"cms.news;cms.article"

CombineWithDefaultCulture

Indicates whether the control loads documents from the website's default culture version if the required documents are not available in the user's selected culture.

Only applies if you do not set the TreeProvider property manually.

 

CultureCode

Specifies the culture code of the documents that the control loads. If not specified, the control automatically uses the preferred culture of the user viewing the page.

"en-us"

DataSource

Allows you to manually assign a DataSet or DataTable containing the documents that the control displays. You do not need to set this property for standard scenarios.

 

FilterOutDuplicates

Indicates if the control filters out duplicated (linked) documents from the data.

 

MaxRelativeLevel

Specifies the maximum number of content tree sub-levels from which the control displays documents. This number is relative, i.e. counted from the location of the page where the control is placed, not from the root of the website.

Enter -1 to load all child documents.

 

Path

Path of the documents that the control loads.

See: Writing document path expressions

 

SelectOnlyPublished

If enabled, the control only loads published documents.

 

TreeProvider

Gets or sets the TreeProvider object used by the control to access document data. If you do not assign a TreeProvider object, the control automatically creates a new instance.

 

Document relationship properties

Description

Sample value

RelationshipWithNodeGUID
______________________________

If set, the control only loads documents that are related to the document with the specified NodeGUID. You can find the Node GUID of documents on the Properties -> General tab in the Pages application.

Enter "11111111-1111-1111-1111-111111111111" to dynamically load documents related to the current document.

"36f8c4bc-f702-4736-8a25-a82295668794"

RelatedNodeIsOnTheLeftSide

Determines whether the document specified through the RelationshipWithNodeGUID property is on the left or right side of the relationship.

  • If true, the control displays documents on the right side of the relationship.
  • If false, the control displays documents on the left side of the relationship.

 

RelationshipName

Specifies the type of the document relationship. Enter the code name of the relationship.

"isrelatedto"

CMS Base control properties

Description

Sample value

CacheDependencies
______________________________

List of the cache keys on which the control's cached data depends. When the specified cache items change, the control clears its cache.

Each item (dependency) must be on one line.

If you leave this property empty, the control uses default dependencies.

See also: Setting cache dependencies, Configuring caching

cms.user|all

CacheItemName

Sets the name of the cache key used to store the control's content. If you leave the value empty, the system generates a default name containing variables, such as the control ID, the selected culture and the name of the user who loaded the page.

The system cache is shared by all pages in your application, so cache item names representing different data must be unique globally. If you have multiple controls that load the same data, you can share the cache keys between the controls (optimizes loading of content and avoids redundant data in the cache).

If the content displayed by the control depends on variables, such as URL parameters, you can set a custom name dynamically in the page's code behind.

See also: Caching the data of page components, Configuring caching

"CMSRepeaterNews" +
Request.QueryString["id"].ToString()

CacheMinutes

Sets the number of minutes for which the control caches content retrieved from the database.

  • 0 indicates that control does not cache content
  • -1 indicates that the control uses the site-level content caching settings

Allows you to set up caching of content so that the control doesn't have to retrieve content from the database on each request.

The caching mechanism uses absolute expiration time. This means that cache items expire after a specified time period even if the page containing the control wasn't requested.

See also: Caching the data of page components, Configuring caching

 

FilterControl

Gets or sets the filter control used to limit the data read by the control.

 

FilterName

Gets or sets the code name of the filter control used to limit the data read by this control.

 

OrderBy

Gets or sets the ORDER BY clause of the SQL query that the control uses to load data.

"NewsReleaseDate DESC"

SelectedColumns

Database table columns that the control loads for documents, separated by commas ( , ). If null or empty, the control loads all available columns.

 

SiteName

Specifies the code name of the Kentico website for which the control loads data.

 

StopProcessing

If true, the control stops all processing — does not load or display any data or other HTML output.

 

TopN

Specifies the maximum number of database records that the control loads.

 

WhereCondition

Gets or sets the WHERE clause of the SQL query that the control uses to loads data.

"ProductPrice > 100"

Appearance and styling

The appearance and design of the content displayed by the CMSViewer control is entirely driven by the XSLT transformation specified in the TransformationName property.