Directory
The Directory server control lets you customize the behavior of the taxonomya content-level categorization system that uses one-to-many relationships (such as Ronald Reagan is to Actor, Governor, and President) to create a scalable organization of content. A taxonomy lets your site visitors navigate content independent of the folder structure. feature. You place this control on a Web form to display a taxonomy. See also: Organizing Content with Taxonomies.
NOTE: To display a taxonomy on a PageBuilder page, use the taxonomy summary widget.
To minimize taxonomy’s impact on the performance of your production server, follow these guidelines.
- Use the default page size (50). If you need to customize page size, use Ektron’s Developer Reference Sample SiteAPI, but do not increase it above 800.
- For large databases, do not increase the value of the
TaxonomyDepth
property above 1. Changing this value dramatically slows down your production server’s performance. However, you can increase depth on your staging server for testing purposes.
Inserting the Directory server control onto a page
Prerequisite
You must have installed the server controls. See Installing server controls into Visual Studio Toolbox.
- In Visual Studio, choose View > Toolbox.
- Click the Ektron server control tab to display the server controls.
- Drag the Directory server control and drop it into the desired location on the page.
NOTE: You also can place the cursor on the page where you want the server control, then double click the server control that you want.
<CMS:Directory ID="Directory1" runat="server" />
- Click on
Directory
in the code to display and modify the control’s properties using the Properties window of Visual Studio. The page is updated as you modify the property values.
Directory properties
The following are Ektron-specific server controla server control uses API language to interact with the CMS and Framework UI to display the output. A server control can be dragged and dropped onto a Web form and then modified. properties. For information about native .NET properties such as font, height, width and border style, use Visual Studio® help.
- AddItemFolderID (Long)
Define the Ektron folder ID where content is stored when an item is added to the taxonomy via the Add Asset link or the Add Content link. To enable adding content items via the Directory server control, you must use an EkML file with the
[$AddAsset]
and[$AddArticle]
variables. See also: taxonomy.ekml. - CacheInterval (Double)
The number of seconds that a server controla server control uses API language to interact with the CMS and Framework UI to display the output. A server control can be dragged and dropped onto a Web form and then modified.’s data is cached. The default is 0 (zero). For example, if you want to cache the data for 5 minutes, set to 300. See also: Caching with server controls.
NOTE: If the
EnablePaging
property is set to True, theCacheInterval
property is disabled. - DisplayXslt (String)
If desired, enter a relative or absolute path to an Xslt that determines the display of the page.
WARNING! Files stored in the
siteroot\Workarea
folder are overwritten (or deleted) when you upgrade Ektron. To avoid problems, copy the default file to a folder outside thesiteroot\workarea
folder then edit it. If there is no default file, create the file outside thesiteroot\workarea
folder. Next, in this property, enter the path to that file relative to the site root folder.WARNING!
If you enter a valid EkML file at the MarkupLanguage property, the Displayxslt property value is ignored. - DoInitFill (Boolean)
By default, Fill occurs during the Page_Init event. Set to false if you want to postpone the fill-action until later. In this case, Fill is automatically called during the Page Render event. You might do this if you need to set or change a property on the control in code-behind and have it render with your changes shown.
- DynamicParameter (String)
Gets or sets the QueryString parameter to read a content ID dynamically.
- EnableAjax (Boolean)
Set to true to enable Ajax searches. When enabled, the
MaxResults
property determines the maximum number of results per page.- True. Enable Ajax Search (default value)
- False. Original HTML Search
- EnablePaging (Boolean)
This property, in conjunction with the MaxNumber property, lets site visitors view an unlimited number of items while controlling the amount of screen space. The MaxNumber property limits the number of items displayed. If you set this property to True, and the number of items exceeds MaxNumber, navigation aids appear below the last item, allowing the visitor to go to the next screen. See example below.
So, for example, if a taxonomy has 9 items and
MaxResults
is set to 3, the screen displays only the first 3 items. When the site visitor clicks [Next], he sees items 4, 5 and 6, and so on.IMPORTANT: If the
EnablePaging
property is set to True, theCacheInterval
property is disabled. - EnableSearch (Boolean)
Set to True if you want a search box (shown below) to appear above this taxonomy display. A site visitor can use the search to find content within a taxonomy/category that includes terms of interest. To suppress the search box, set to False.
- GetAnalyticsData (Boolean)
Set this property to True if you want the following information for each content in the list. Returns Content View Count, Content Rating, Content Rating Average. Create your own XSLT styles to display this data.
IMPORTANT: This property provides reliable data only when the Business Analytics Feature is on. See Running Ektron Business Analytics.
- Hide (Boolean)
Hides or displays the output of the control in design time and run time.
- True. Hide the control output.
- False. Display the control output.
- IncludeIcons (Boolean)
Choose whether to display icons next to the taxonomy’s links.
This property only works when ecmSummary or ecmTeaser are used in the
DisplayXslt
property. When the[$ImageIcon]
variable is used in an EkML file and that file is assigned to theMarkupLanguage
property, this property acts as True.- True. Show icons
- False. Hide icons
- Language (Integer)
Set a language for viewing content; shows results in design-time (in Visual Studio) and at run-time (in a browser).
- LinkTarget (ItemLinkTargets)
Determines the type of window that appears when you click a link in the server control.
- _Self (default). Opens in same window.
- _Top. Opens in parent window.
- _Blank. Opens in new window.
- _Parent. Opens in the parent frame.
- MarkupLanguage (String)
Enter the template markup file (
.ekml
) that controls the display of this server control. To use the default .ekml file, leave this field blank.The default file follows this pattern:\siteroot\Workarea\template\this object\objectname.ekml
. For example,\siteroot\Workarea\template\collection\collection.ekml.
To customize the default .ekml file, copy it to a folder outside thesiteroot\workarea
folder and edit it. Next, in this property, enter the path to that file relative to the site root folder.See also: Ektron Markup LanguageSee also: taxonomy.ekml
NOTE: If you enter a valid EkML file at the MarkupLanguage property, the Displayxslt property value is ignored. If the EkML file contains the
[$ImageIcon]
variable, theIncludeIcons
property acts as True. - MaxResults (Integer)
Enter the maximum number of items to appear in the initial display of this server control. If you set this value to zero (0), the maximum is 50. To let site visitors view more than the maximum but limit the amount of space being occupied, enter the maximum number of results per page here. Then, set the
EnablePaging
property to True. If you do and more than the number ofMaxResults
are available, navigation aids appear below the last item to help the site visitor view additional items. See following example below. - OrderItemsBy
Specify the sort order of results. Choices are:
- taxonomy_item_display_order. The order of taxonomy items as set in the Workarea.
- content_title. The content is listed in alphabetical order by title.
- date_created. Content is listed in the order by which it was created.
- last_edit_date. Content is listed in order, by its last edit date.
- content_rating_average. Business Analytics Content Rating
- content_view_count. Business Analytics Content Views
Use the the
SortDirection
propertyYou can to specify the direction of the items with theSortDirection
property. - PreserveUrlParameters (Boolean)
Set to
true
if this control needs to preserve the URL parameters on the page. For example, if a server control displays a list of content items, the URL parameter passes to the control the template names andid
values that the template expects. Set tofalse
if the server control does not need to pass the URL parameters to the server control. The default value isfalse
. - Recursive (Boolean)
Set to True to include child folders of the parent folder.
- ShowAllChecked (Boolean)
When set to
true
, a check box appears in the Show All check box.Also, set this property to
true
if you want categories to which no items are assigned to appear. If set tofalse
, only categories to which items are assigned show up in the display. - ShowCount (Boolean)
Indicates if the number of taxonomy items appears next to each category when displayed in the website. (See example below.) Default value is false.
- ShowRoot (Boolean)
- False. Top represents the first node of the taxonomy path.
- True. The name of the taxonomy path's first node appears instead of Top.
- SortDirection (String)
Select the direction of the
ItemSortOrder
property. Choose Ascending or Descending. - TaxonomyCols (Integer)
Enter the number of columns in which this taxonomy/category will appear on the page.
- TaxonomyDepth (Integer)
Enter the number of taxonomy levels to retrieve below each taxonomy/category if you are accessing a taxonomy’s XML using code-behind. For example, if the taxonomy is Clients > Industries > Education > Colleges, and you set Taxonomy Depth to 2, only Clients > Industries are available in code-behind.
Exception: If you set this value to 1, the control retrieves taxonomy levels to a depth of 2. For example, if the taxonomy is Businesses > Restaurants > Fast Food > Pizza, and you set Taxonomy Depth to 1, Business and Restaurants are available in code-behind.
This setting has no effect on the display generated by the Directory server control, which always displays one level below the current. To retrieve all categories for a taxonomy recursively, enter -1. The default value is 1.
IMPORTANT: For a live site, leave this value at 1. Increasing this value can slow down your live Web server. However, for testing on a staging server, you can increase the depth.
- TaxonomyId (Long)
Enter the ID number of the taxonomy or category to appear in this server control. If you don’t know the number, click the button and navigate to the taxonomy or category.
- TaxonomyItemCols (Integer)
Enter the number of columns in which this taxonomy/category items (articles) will appear on the page.
- WrapTag (String)
Lets a developer specify a server control’s tag.
- Span (default). Designate an inline portion of an HTML document as a span element.
- Div. Apply attributes to a block of code.
- Custom. Lets you use a custom tag.