Categories widget

You use the Categories widget to display categories on your page. You use categories to filter content by clicking different categories from the list displayed on the webpage.

For details about categories, see Use categories.

Configure the Categories widget

After you place the Categories widget on a page, open the widget designer by clicking the Edit button in the upper-right corner of the widget. 

1. Under Which categories to display? select one of the following:

   • All categories
     All categories are displayed in the list.

   • Top level categories only
     All top level categories are displayed in the list.

   • All categories under paritcular category
     All direct children of a specifically selected category are displayed in the list.
     To select a category, click the Select button.

   • Selected categories...
     A custom selection of categories is displayed. To select one or more categories you want to display, click the Select button.

   • Only categories used by content type...
     A custom selection of categories is displayed. Only categories assigned to the content type items selected are displayed in the list.

2. In the Settings tab you modify the widget behavior:

   • Show item count
     The number of items, to which the category is assigned is displayed.

   • Show empty categories
     Categories that are not assigned to any item are displayed.

   • Sort categories
     By default, the categories are sorted by category title (A-Z). You can select a different sorting criterion:

     • By Title (A-Z)
     • By Title (Z-A)
     • As set manually
       This option is available only when you selected specific categories using Selected categories… option. If you select As set manually, categories are displayed in the selected order.
     • As set in Advanced mode
       To sort the list of categories by property that is not defined in the sort dropdown menu, you must add a new sorting expression in the designer’s Advanced mode. For example, to sort categories using the Description property of categories, navigate to Advanced » Model and, for SortExpression, add Description ASC. As a result, in the sort dropdown menu, the As set in Advanced mode option is selected by default.

   • Template
     Select the template you want to use to list categories on the webpage.

     • CategoriesList
       The widget displays categories in a vertical list.

       NOTE: This template does not preserve the hierarchy of the categories. Categories are displayed as a flat list even if some categories are children of a category. If you want to show the categories as a tree, see Add hierarchical tree view.

3. CSS classes
   Expand More options section to specify CSS class names and apply additional CSS classes to the categories widget.

Display custom classification

PREREQUISITES: You must create custom classifications first. For more information, see Create custom classifications.

To display a custom hierarchical classification, you use the Categories widget. Complere the following:

1. Place the Categories widget on your page and click the Edit button in the upper-right corner of the widget.
2. Go to Advanced » Model.
3. In the TaxonomyId property field, set the ID of the classification you want to display.
4. In the TaxonomyProviderName property field, enter the provider name of the classification you want to display.
5. In the FieldName property field, enter the name of the content type field that contains the classification.
6. Click Save.

Advanced settings

In Advanced settings, you specify individual properties of the widget - the TemplateName. This property gets the template you chose in the Template dropdown menu.

Model settings

Model settings display all properties directly bound to the Categories widget model. Access these properties by clicking the Model button in Advanced settings.

• BaseUrl
  Gets the URL name of the page whose content you want to filter using categories.
  This page can be either the same page on which the Categories widget is placed, or it can also be another page. For example, you can display the categories on one page of your website, but if the user clicks a category, the system opens another page and filters its content.

  NOTE: You must enter the URL name in the following format ~/. For example, if the title of the page is About us, the automatically generated URL name is about-us (in case you have not changed it). InBaseUrl input field you must enter ~/about-us.

• ContentId
  Use this property if you want to only show categories that are assigned to a specific content item. To do this, specify the content item ID. For example, if you want to only show categories that are assigned to a news item News 1, specify its ID in the ContentId property. In the Only tags used by content type... option select News.

• ContentProviderName
  If you have more than one provider added to the selected content type, you can use a provider different provider than the default one. To do this, specify the name of this provider.

  NOTE: If you leave this property value empty, the default provider is used.

• ContentTypeName
  Gets the content type you chose in the Only categories used by content type... option:

  • Telerik.Sitefinity.News.Model.NewsItem
  • Telerik.Sitefinity.Blogs.Model.BlogPost
  • Telerik.Sitefinity.Libraries.Model.Image
  • Telerik.Sitefinity.Libraries.Model.Document
  • Telerik.Sitefinity.Libraries.Model.Video
  • Telerik.Sitefinity.Lists.Model.ListItem

• CssClass
  Gets and sets an additional CSS class.

• DynamicContentTypeName
  If you selected a dynamic content type in Only tags used by content type... option, the content type name will be populated in this property.

• FieldName
  Gets the name of the property that contains the taxonomy.

• FlattenHieararchy
  The default value is True. If you set the value to False, the model returns the categories as a tree rather than a flat list. To display this hierarchy, see Add hierarchical tree view.

• SerializedSelectedTaxaIds
  In case you selected specific categories, the IDs of the selected categories are serialized and populated in this property. For example: ["3f47d0b8-2d22-6e58-888c-ff0000bfc4e0"]

• ShowEmptyTaxa
  Defines whether categories that are not assigned to any item are displayed.

• ShowItemCount
  Defines whether the count of all items to which the category is assigned is displayed.

• SortExpression
  Adds additional sorting expression for the categories. The default value is Title ASC.

• TaxaToDisplay
  Gets the value you selected in the Which categories to display? option:

  • All
    This is the default option.
  • TopLevel
  • UnderParticularTaxon
  • Selected
  • UsedByContentType

• TaxonomyId
  Specifies the taxonomy ID, by which taxons are displayed. By default, the selected taxonomy is Categories.

• TaxonomyProviderName
  If you have more than one provider added to the selected taxonomy, you can use a provider different than the default one. To do this, specify the name of this taxonomy provider.

  NOTE: If you leave this property value empty, the default provider is used.

• UrlKeyPrefix
  Gets or sets the URL key prefix, which is used when building and evaluating URLs together with the ContentView controls.

• UrlEvaluationMode
  Use this property to specify the URL evaluation mode filter - the URL segments or query string. The supported options are:

  • UrlPath
    This is the default option. The URL has the following structure:
    http://[sitefinity]/page/-in-tags/tags/site1-tag1
  • QueryString 
    Generates the URL in the following format:
    http://[sitefinity]/page?taxonomy=tags&propertyName=tags&taxon=site1-tag1

• TaxaCountLimit
  Use this property to specify the maximum number of taxa to be displayed.