Collection

Inserting the Collection server control onto a page

Prerequisite

You must have installed the server controls. See Installing server controls into Visual Studio Toolbox.

1. In Visual Studio, choose View > Toolbox.
2. Click the Ektron server control tab to display the server controls.
3. Drag the Collection 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:Collection ID="Collection1" runat="server" />

4. Click on Collection 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.
   —Image—

   

Collection 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.

• AddText (String)

  Override the control’s default text for the Add Content menu item. For example, If you have a News website, you could change Add Content to Add News Item.

  

• 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, the CacheInterval property is disabled.

• ContentParameter (String)

  Checks the QueryString for this value and replaces the collection with a content block when specified. Leave blank to always display the Collection.

• DefaultCollectionID (Long)

  The ID of a collection that appears where you insert this server control if no other collection is identified, or is not available. If you don’t know the ID number of the collection, use the CMS Explorer to browse to it.See also: Browsing your Ektron site using CMS Explorer

• DisplayXslt (String)

  Determines how the information on the page appears.

  • None. Databind only
  • ecmNavigation. Lists the title of every content block in the collectiona list of Ektron content links for display on a Web page.
  • ecmTeaser. Lists the title of every content block in the collection plus the content summarya short description that supplements a content item's title on a Web page. Content authors compose a summary when creating or editing content. Server controls and widgets can display a content title and summary to attract readers to the full story. Summaries can include images and text formatting.

    See also: ecmTeaser Display example.

  • Path to Custom Xslt. 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 the siteroot\workarea folder then edit it. If there is no default file, create the file outside the siteroot\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)

  To make this collection dynamic, select coll_id. When you do, this server control uses the collection passed as a URL parameter.

• 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 the following example.

  

  For example, if a collection has 9 items and the MaxResults property is set to 4, the screen displays only the first 4 items. When the site visitor clicks [Next], he sees items 5, 6, 7 and 8, and so on.

  NOTE: If the EnablePaging property is set to True, the CacheInterval property is disabled.

• 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.

• GetHtml (Boolean)

  Set to True if you want to retrieve and display content (html body) for all content blocks in the collection. For example, to display content inside a Web server control such as a GridView.

• 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 collection list’s links.

  IMPORTANT: This property only works if ecmSummary or ecmTeaser is used in the DisplayXslt property. If the [$ImageIcon] variable is used in an EkML file and that file is assigned to the MarkupLanguage property, this property acts as True.

  

• 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 the siteroot\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 Language

  See also: collection.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, the IncludeIcons property acts as True.

• MaxResults (Integer)

  Enter the maximum number of items to appear in the initial display of this server control. To set no maximum, enter zero (0). To let site visitors view more than the maximum but limit the amount of space, enter the maximum number of results per page here. Then, set the EnablePaging property to True. If you do and more than the number of MaxResults are available, navigation aids help the site visitor view additional items. See example below.

  

• Random (Boolean)

  Set to True if you want to randomly display one collection item. The item changes each time a site visitor views the page.

  NOTE: If you use a custom XSLT or EkML file, the type of content displayed can be manipulated. For example, if you use an EkML file that has the [$Html] variable in it, the actual content appears instead of a link. See also: Ektron Markup Language and [$Html].

• SelTaxonomyID (Integer)

  Set the ID 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. with which content is associated if a logged-in site visitor uses the Silver Access Point’s Add HTML Content option to add content to a Collection server control.

• SuppressWrapperTags (Boolean)

  This property is set to false because Ajax uses <div> tags to rewrite the region around the tag. You cannot change the value to true.

• 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.

ecmNavigation Display Example

The following figure shows a collectiona list of Ektron content links for display on a Web page. being used as a navigation menu.

ecmNavigation XSL code

The following XSL code creates the ecmNavigation Display. You can use this code as the basis to design your own XSLT.

WARNING! If you create a custom file, do not store it in the Workarea folder. If you do, the file will be overwritten when you upgrade.

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
  <table border="0" cellspacing="0" cellpadding="0" width="100%">
   <xsl:for-each select="Collection/Content">
   <tr>
      <td>
         <a>
            <xsl:attribute name="href">
                <xsl:value-of select="QuickLink"/>
            </xsl:attribute>
                <xsl:value-of select="Title"/>
         </a>
     </td>
   </tr>
   </xsl:for-each>
  </table>
</xsl:template>
</xsl:stylesheet>

ecmTeaser Display example

The following example shows a collectiona list of Ektron content links for display on a Web page. using the ecmTeaser display style.

—Image—

ecmTeaser XSL code

The following XSL code creates the ecmTeaser Display. You can use this code as the basis to design your own XSLT.

WARNING! If you create a custom file, it is strongly recommended to not store the file in the Workarea folder. If you do, the file will be overwritten when you upgrade.

<?xml version="1.0" encoding="ISO-8859-1"?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
<xsl:template match="/">
  <table border="0" cellspacing="0" cellpadding="0" width="100%">
    <xsl:for-each select="Collection/Content">
      <tr>
        <td>
          <a>
            <xsl:attribute name="href">
              <xsl:value-of select="QuickLink"/>
              </xsl:attribute>
             <xsl:value-of select="Title"/>
          </a>&#160;
        </td>
      </tr>
      <tr>
         <td>
            <xsl:value-of select="Teaser" />
         </td>
      </tr>
      <tr>
          <td>&#160;</td>
      </tr>
    </xsl:for-each>
  </table>
</xsl:template></xsl:stylesheet>

Using the Collection server control Programmatically example

The following is an example of using code-behind, and a drag and drop Collection server control to display random content from a collection.

1. Drag and drop a Collection server control on your Web form.
2. Set the properties in the properties window.

   NOTE: In this example, the Random and GetHtml properties must be set to True.

   —Image—

   

3. Add the following code to the code-behind.

   Dim str As String
   str = "<h1>Hello There</h1><br>"
   str &= Collection1.EkItems(0).Html
   Collection1.Text = str

4. Build and browse your Web form.
   —Image—

   

Retrieving the XML Structure of a Collection

Retrieving the XML structure of a collectiona list of Ektron content links for display on a Web page. allows for greater control over developing XSLs. The following is an example of how to do that.

1. Open a new Web form.
2. Drag and drop a Collection server control onto it.
3. Set the DefaultCollectionID property.
4. Drag and drop a textbox on the Web form.
5. Set the TextMode property to MultiLine.

   NOTE: Set the text box width to at least 400px.

6. On the code-behind page, add the following line.

   Textbox1.Text = Collection1.XmlDoc.InnerXml

7. Build the project.
8. View the Web form in a browser.
9. The XML structure of the collection appears in the textbox.

For an additional example, see the Collection XML page on the Developer samples page. It is located at:

• In a browser:

  http://sitroot/CMS400Developer/Developer/Collection/CollectionXML.aspx

• In the source code:

  siteroot/CMS400Developer/Developer/Collection/CollectionXML.aspx 
    and CollectionXML.aspx.vb