Ektron’s server controls let you insert many standard methods and properties within the Visual Studio environment. This means that you can see the effect of your changes in real time—you do not have to modify a page then compile a sample project to see the results.

You can insert server controls using drag and drop or programmatically. You can also use databinding to retrieve and display data from Ektron.

Additional information and examples for Ektron server controls are available online after you install the following sample site.

http://localhost/samplesite/Default.aspx

Replace localhost with the webroot where you installed the sample site.

IMPORTANT: For improved security,you should rename or remove the Web services file when you move it to your production server. After installation, this file is named ServerControlWS.asmx in the /siteroot/Workarea/ folder in your Web root.

ServerControlWS.asmx is the Web service that lets server controls communicate with Ektron. The path is coded in the web.config file as follows. Edit this line if you change the location or name of the ServerControlWS.asmx file.

<!-- Web Service URL for Server Controls design time -->
<add key="WSPath" 
  value="http://localhost/siteroot/Workarea/ServerControlWS.asmx" />

Installing Server Controls into Visual Studio

This section describes how to install server controls (except for Search Server controls, which are found at Adding Search Server Controls to Visual Studio).

NOTE: You must copy the dlls to a local drive before installing them. You cannot install them from a network drive.

1. Display the Visual Studio 2010 toolbox (View > Toolbox).
2. Right click the mouse within the Toolbox and click Add Tab.
3. Type Ektron Server Controls then press Enter.
   —Image—

   

4. Click the Ektron Server Controls tab to open it.
5. Right click the mouse in the empty area and click Choose Items. The Customize Toolbox dialog appears.
   —Image—

   

6. Click Browse... on the .NET Framework Components tab and find the directory that stores Ektron‘s dll files (siteroot/bin).
7. Select siteroot/bin/Ektron.Cms.Controls.dll file and click Open. This file provides access to Ektron’s server controls.

   NOTE: Using the bin folder in your site provides better speed when loading Web pages. However, if you use the bin folder located in C:\Program Files\CMS400vxx\bin, you do not have to worry about deleting the .dll file if you change or delete your site. The file is identical in both places.

8. Click OK on the Choose Toolbox Items dialog box. The controls are added to the Ektron Server Controls tab of the Visual Studio Toolbox.
9. To install the UI server controls also, repeat steps 6 through 9 selecting siteroot/bin/Ektron.Cms.Framework.UI.Controls.EktronUI.dll. The controls appear on the Toolbox tab.
   —Image—

   

For easier viewing once the server controls are installed, you can right click on them and select Sort Items Alphabetically. You can only see the server controls when an ASPX template is selected.

Removing Server Controls from the Visual Studio Toobox

1. Display the Visual Studio toolbox (View > Toolbox).
2. Right click the mouse within the Toolbox.
3. Click Choose Items....
4. Click Namespace or Assembly Name to sort the server controls by manufacturer.
5. Uncheck boxes next to the server controls you want to remove.
6. Click OK.

   NOTE: If you want to delete all of the server controls from the Ektron Server Control tab, right click on the tab and choose Delete Tab.

Opening a Sample Project in Visual Studio

1. Using Visual Studio, choose Open > Project/Solution and browse to and double click Ektron‘s solution file, localhost/siteroot/projectname.sln. For example, for the OnTrek sample site, the file is OnTrek.sln. The sample site project opens.
2. To work on a template page, open the Solution Explorer and click the page you want.
   —Image—

   

   When you select a page, its properties appear in the Properties Window, and the page appears in the center of the screen. A control’s properties include several standard .NET properties along with Ektron-specific ones. The Ektron properties are labeled as illustrated below.

   —Image—

   

Creating a New Template in Visual Studio

1. Choose Website > Add New Item....
2. On the Add New Item screen, click Web Form and assign a name.
   —Image—

   

3. Add controls to determine the page content.

After you open the solution file in Visual Studio and add the required files, build the project. After the project is built, a browser opens and it appears as a Web page. You can also view a Web page while working on it by right clicking on the Web form and clicking View in Browser.

Browsing Your Ektron Site Using CMS Explorer

CMS Explorer lets you browse your website to identify Ektron objects such as folders, calendars, blogs, and content blocks. You access the CMS Explorer from the Properties window. For example, if you insert a ListSummary server control, its FolderID property identifies the folder whose contents are displayed.

1. If you are not sure of the folder path, click the ellipsis (...) button next to the property field. A login screen appears.

   NOTE: You cannot be logged into the CMS Explorer and the Workarea at the same time. If you log into the CMS Explorer while logged into the Workarea, an error message appears. If you log into the Workarea while logged into the CMS Explorer, you will need to re-login to the CMS Explorer when you return to using it.

   

2. Enter your Ektron username and password. The CMS Explorer window appears so you can browse your Ektron website.
   —Image—

   

3. Navigate through the folders, select an object, then click Select. The selected object is pasted to the server control property.

   NOTE: Although you see the object in the selected language in Visual Studio, the language is not stored. For example, if you select a German content block whose ID=2, Ektron only stores content block ID=2. When a visitor to your site browses to that page, the content block does not appear in the selected language. Instead, it is determined by a cookie or the user’s language selection.

Inserting a Server Control Using Drag and Drop

Because Visual Studio is a visual environment, you can watch the page layout change as you add or move a control and adjust its properties. Use the CMS Explorer whenever you need to identify an Ektron object (such as content block or collectionA list of Ektron content links for display on a Web page.).

1. Display the Visual Studio toolbox (View > Toolbox).
2. Click the Ektron Server Control tab. Ektron’s server controls appear.
   —Image—

   

3. Drag a server control and drop it into the desired location on the page.
4. Modify the control’s properties using the Properties window of Visual Studio.
   —Image—

   

Modifying a Server Control after Drag and Drop

You can manipulate a server control after dragging and dropping it on a Web form by using the code-behind. The following example shows using a drag and drop ListSummary 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. then modifying it programmatically.

1. Drag and drop a ListSummary on your Web form and set your properties.
   —Image—

   

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

   Dim myString As String
   Dim i
   For i = LBound(ListSummary1.EkItems)To UBound(ListSummary1.EkItems) 
     myString &= "<a href=""" & ListSummary1.EkItems(i).QuickLink & """>" 
     & ListSummary1.EkItems(i).DateCreated & "</a><br>"
   ListSummary1.Text = myString
   Next 

   ListSummary1 is the ID of the object. It is used to get access to its properties.

3. Create a string that contains the output (myString).

   Dim myString As String

4. Set the object’s Text property to that string.

   myString &= "<a href=""" & ListSummary1.EkItems(i).QuickLink & """>" 
     & ListSummary1.EkItems(i).DateCreated & "</a><br>"

5. Wrap it in a loop so it loops through each of the items.

   Dim i
   For i = LBound(ListSummary1.EkItems) To UBound(ListSummary1.EkItems)
   Next

   This example outputs the date created for each content block in a ListSummary.

   

Inserting a Server Control Programmatically

You may want to insert server controls programmatically for the following reasons:

• You want the control to be loaded into memory only under certain conditions. In this case, insert the logic that only displays the control if the condition exists.
• You want to display only certain properties of an object, such as the title of last edited date of a content block.

To insert an Ektron server control programmatically:

1. Declare the Namespace at the top of the code-behind Visual Basic file.

   NOTE: You do not need to declare a namespace. However if you do not, you must fully qualify objects that you create. For any customization of Ektron, classes or controls that inherit from Ektron classes, you should create your own namespace within 'Ektron.Cms.Custom'. For example, if your company is 'AcmeExampleTech, Inc.' you should create all of your custom classes within the namespace 'Ektron.Cms.Custom.AcmeExampleTech'.

   —Image—

   

2. Create an instance of the new control by declaring a control as an object in the code-behind; in this example, a collectionA list of Ektron content links for display on a Web page. named MyColl.

   Ektron.Cms.Controls.Collection MyColl = 
     new Ektron.Cms.Controls.Collection();

   You can declare any server control as an object by using the server control name. See Working with Ektron Server Controls. Another example would be: Dim MyMdl as New MetaDataList.

3. Set the properties that you want to display on the page. For example:

   Dim MyColl as New Collection
   MyColl.DefaultCollectionID = 4
   MyColl.Page = Page
   

   For descriptions of the properties and how to use them, see Accessing Server Control Properties in Code-behind Programmatically.

   With C#, use this syntax.

   >
   Ektron.Cms.Controls.Collection MyColl = 
     new Ektron.Cms.Controls.Collection();
   MyColl.DefaultCollectionID = 4;
   MyColl.ID = “Collection1”;
   MyColl.Page = Page;
   

   These lines tell the page to display CollectionID 1 unless otherwise specified.

   IMPORTANT: When using code-behind to add a server control to your Web form, you must set the Page object for the server control to Page. For example, Mycoll.Page = Page
   This line needs to appear between Dim new server control line and the Fill() line. This line is not added when dragging and dropping a server control on a Web form. See Also: Referencing a Parent Page.

   If you do not know an object’s ID number, you can switch to Design mode, drag and drop the object, then use the CMS Explorer to find the ID number. (See Browsing Your Ektron Site Using CMS Explorer.) If you do this, remember to delete the dropped object when you are done. You can also obtain the ID number via the Workarea. This line sets the Random property to true.
   

   Dim MyColl as New Collection
   MyColl.ID = “Collection1”
   MyColl.DefaultCollectionID = 4
   MyColl.Page = Page
   MyColl.Random = True

4. Call the Fill method to fill an object’s properties on the page because there is no render event when using objects as components not as controls.

   >
   Dim MyColl as New Collection
   MyColl.ID = “Collection1"
   MyColl.DefaultCollectionID = 4
   MyColl.Page = Page
   MyColl.Random = True
   MyColl.Fill()

5. Use the property to determine what appears on the Web page. For example, to display the first item in a collection, use this syntax.

   NOTE: Before adding this line you need to drag and drop a label on your Web form.

   >
   Dim MyColl as New Collection
   MyColl.ID = “Collection1”
   MyColl.DefaultCollectionID = 4
   MyColl.Page = Page
   MyColl.Random = True
   MyColl.Fill()
   Label1.Text = myColl.EkItems(0).Title 

   To display all items in a collection, use this syntax.

   Dim myColl As New Ektron.Cms.Controls.Collection
   Dim ekitem As New Ektron.Cms.Common.ContentBase
   MyColl.DefaultCollectionID = 2
   MyColl.ID = “Collection1”
   MyColl.Page = Page
   MyColl.Fill()
   Label1.Text = "<ul>"
   For Each ekitem In myColl.EkItems
   Label1.Text &= "<li><a href=""" & ekitem.QuickLink & """>" 
     & ekitem.Title & "</a>"
   Next
   Label1.Text &= "</ul>"

   This example displays the quick link for every content block in the collection, formatted as a bulleted list. You can use similar code to display a List Summary or search results. The following explains the new (red) code above.

   • label1.Text = "<ul>" displays the opening tag for the bulleted list
   • For Each ekitem In myColl.EkItems creates a loop for all content blocks in the collection
   • label1.Text &= "<li><a href=" & ekitem.QuickLink & ">" & ekitem.Title & "</a></li>" for each content block in the collection, displays its quicklink and title
   • Next loops through all content blocks in the collection
   • label1.Text &= "</ul>" closes the bulleted list

Accessing Server Control Properties in Code-behind Programmatically

Every 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. has properties associated with it that you can access only programmatically. This section explains what they are, how to access them, and how to use them.

You can use Visual Studio’s intellisense feature to display a control’s properties. The intellisense box appears as soon as you insert the period (.) after the object, as illustrated below.

The intellisense box displays all properties that can be applied.

The property’s tooltip text indicates its type. In the previous example, note that the DefaultCollectionID’s type is integer.

To learn about native Visual Studio properties, see the Visual Studio documentation. For more information about accessing Ektron object properties, see Customizing a Server Control in the code-behind.

dim MyCB as New ContentBlock
MyCB.DefaultContentID = 30
MyCB.ID = “ContentBlock1”
MyCB.Page = Page
MyCB.Fill()
label1.text = MyCB.EkItem.dateCreated

dim MyCB as new Ektron.Cms.Controls.ContentBlock
MyCB.DefaultContentID = 30
MyCB.ID = “ContentBlock1”
MyCB.Page = Page
MyCB.Fill()
label1.text = MyCB.EkItem.dateCreated

Accessing Items in an Array

To access and manipulate content blocks returned by an object, use the common class Ektron.Cms.Common.ContentBase. For example, Search, Collection and ListSummary have EkItems (an array of ContentBase), while ContentBlock has a single EkItem. This example creates a bulleted list of every item in the collection.

dim MyC as new Ektron.Cms.Controls.Collection
MyC.DefaultCollectionID = 1
MyC.ID = “Collection1”
MyC.Page = Page
MyC.Fill()
dim item as Ektron.Cms.Common.ContentBase
MyC.Text = "<ul>"
for each item in MyC.EkItems
MyC.Text &= "<li>" & item.Title & "</li>"
next
MyC.Text &= "</ul>"
Response.Write(MyC.Text())

NOTE: For information on using ekitems with eCommerce server controls, see Using the Cart Server Control.

Referencing a Parent Page

Server controls require a reference to their parent page (for example, using the DynamicParameter property on a content block to check for a query string). You must provide access to the page object if you declared your control in the code-behind. To do this, set the control's Page property to the Web page you're working on, as shown in the following example.

Ektron.Cms.Controls.Search MySearch = new Ektron.Cms.Controls.Search();
MySearch.Page = Page;
MySearch.Fill();

This relationship only is required when inserting a control in the code-behind. When dragging and dropping, even if you make changes in code-behind, the relationship is automatically generated.

Best Practice 

You should include the Page property reference when using server controls as components in the code-behind.

Customizing a Server Control

Visual Studio separates coding and logic from presentation. Web page formatting is handled by a page’s HTML, while the logic is handled by the code-behind, which is stored in the corresponding .vb file. For example, if the ASP.NET page is mypage.aspx, the code-behind file is mypage.aspx.vb.

NOTE: If you do not see the code-behind files, click Show All Files on the Visual Studio Solution Explorer toolbar (circled in the following figure).

Within the Visual Basic file, you can use Visual Basic to insert code to manipulate the events that occur on the page.

<cms:Search id="Search1" runat="server" ButtonText="Search" 
  Display="Vertical">
</cms:Search>		
<cms:ContentBlock 
  id="ctrlMainContentBlock" 
  runat="server" 
  DefaultContentID="1" 
  DynamicParameter="id” 
  OverrideXslt="Default">
</cms:ContentBlock>

Private Sub Page_Load(ByVal sender As System.Object, ByVal e As 
  System.EventArgs) Handles MyBase.Load		

Dim MyObj As New Ektron.Cms.Controls.ContentBlock			

Dim MyObj As New Ektron.Cms.Controls.ContentBlock		
MyObj.DefaultContentID = 24	

Literal1.Text = ContentBlock1.EkItem.Title

[C#]
If( !IsCallback )
  {
    Literal1.Text = ContentBlock1.EkItem.Title
  }
			
[VB]
If
  ( Not IsCallback )
  Literal1.Text = ContentBlock1.EkItem.Title
End If

Data Binding with Server Controls

With data binding, you can bind Ektron server controls to a GridView Control, DataList Control, or Repeater Control. This gives more flexibility when you use data from the Ektron server controls. Benefits of data binding include ease of data manipulation and the ability to format data.

WARNING! When HTML is bound to a column, you need to add HtmlEncode = False to it. Otherwise, the HTML appears as code. For example, <p>Ektron Inc., an innovator in Web content management software, today announced...</p>.

The following are data bindable Ektron server controls.

• Collection
• ContentList
• IndexSearch
• ListSummary
• MetaDataList
• RssAggregator

The following example shows code-behind that uses a GridView to display a Collection:

NOTE: For the example code to work properly, you need to drag and drop a GridView server control on a Web form.

Dim myCol As New Ektron.Cms.Controls.Collection
  MyCol.ID = “Collection1”‘‘‘Create an ID for the Collection
 myCol.DefaultCollectionID = 4
  myCol.Page = Page   
 myCol.Fill()  
GridView1.DataSource = myCol
GridView1.DataBind()

Steps to data binding using drag and drop server controls are as follows:

1. Create a new Web form.
2. Drag and drop a data bindable server control on the Web form. For example, a Collection server control.
   —Image—

   

3. In properties, choose a DefaultCollectionID for the server control and make sure DisplayXslt is set to None- DataBind Only.
   —Image—

   

4. Drag and drop a GridView on the Web form.
   —Image—

   

5. In the GridView Tasks, choose the DataSourceID.
   —Image—

   

6. In code-behind, add the following line of code to the Page add field.gif unit event:

   Collection1.Fill()

7. Select the columns to be databound by clicking Add New Column in GridView Tasks.
8. Complete the Add Field window.
   —Image—

   

   • Choose a field type—BoundField
   • Header text—The title name for each column.
   • Data field—The data to bind to each column. Choose one of the following:
     • ID—the content block ID
     • Title—the content block title
     • Teaser—the content summary
     • Html—the html content
     • StartDate—the content’s start date
     • DateModified—the content’s last modified date
     • EndDate—the content’s end date
     • LastEditorFname—the last editor’s first name
     • LastEditorLname—the last editor’s last name
     • QuickLink—the content’s quicklink
     • HyperLink—the content’s hyperlink
     • DisplayStartDate—the string representation of the start date
     • FolderID—the folder ID where the content is located
     • ContentStatus—the content’s status
     • Language—the content’s default language
     • DisplayDateModified—string representation of the content’s last modified date
     • DisplayEndDate—string representation of the content’s end date
     • EndDateAction—an action tied to end date. For example, Refresh_Report
     • Comment—the content’s comments
9. Click OK.
10. Repeat steps 6, 7 and 8 for each column you want to add.
    —Image—

    

11. If you want to add all of the columns automatically, in the GridView Task menu click Edit Columns. Otherwise, skip to step thirteen.
    —Image—

    

12. Click the Auto-generate fields checkbox.
    —Image—

    

13. Click OK.
14. From the Build menu, click Build Page.
15. In design view, right click the form and select View in Browser.
    —Image—

    

For more information on GridView, DataList, Repeater and DetailsView, see the help inside Visual Studio.

Caching with Server Controls

High-performance, scalable Web applications store items in memory after the first time they are requested. The items include data objects, pages, and parts of a page. Caching saves and later reuses page output or application data across HTTP requests. You can store items on the Web server or other software in the request stream, such as the proxy server or browser. Caching saves time and resources because the server does not have to recreate information, particularly things that demand significant processor time or other resources. The following image contrasts data flow in non-cached and cached environments.

Displaying Custom XML in Ektron’s Server Controls

Several Ektron server controls have a CustomXml property to add custom XML to a control’s generated XML before it is processed by its XSLTExtensible Stylesheet Language Transformations. Use the CustomXml property in code-behind with these server controls:

• Cart
• Checkout
• CurrencySelect
• MyAccount
• OrderList
• Product
• ProductList
• ProductSearch
• Recommendation

The following examples shows a C# usage of the CustomXml property in code-behind.

protected void Page_Load(object sender, EventArgs e)
	{
	product1.CustomXml = 
         "<banner>Save $$$ While Christmas Shopping!</banner>
	<specials><special><link>ProductDemo.aspx?id=1013</link>
	<text>A great gift for Dad!</text></special><special>
	<link>ProductDemo.aspx?id=1015</link><text>
	A great gift for Mom!</text></special></specials>";
	}

The following example shows the XML sent to the XSLT file.

<root>
  <customXml>
    <banner>Save $$$ While Christmas Shopping!</banner>
	<specials>	 
	   <special>
		<link>ProductDemo.aspx?id=1013</link>
		<text>A great gift for Dad!</text>
	   </special>		
	   <special>
		<link>ProductDemo.aspx?id=1015</link>
		<text>A great gift for Mom!</text>
	   </special>
	</specials>
   </customXml>
</root>		

Learning About Visual Studio

This section provides background information about Microsoft’s Visual Studio. For more information, use the help feature installed with Visual Studio and Microsoft’s developer Center (Microsoft Visual Studio).

NOTE: The following definitions are from Visual Studio Help.

• Grid Layout—Absolute positioning attributes are inserted into elements that are added, and updated in elements that are moved. Elements can be dragged across the Design view surface. The positioning grid and Snap to Grid are available.
• Flow Layout—Elements are added without absolute positioning attributes. Web browsers arrange elements in the order that they occur on the page, from top to bottom. You cannot drag elements across the Design view surface or use the positioning grid.

Grid layout is the default, which means that all controls drawn to the Web form in the designer window have absolute positioning. Here is an example.

<body MS_POSITIONING="GridLayout">
<form id="Form1" method="post" runat="server">
  <asp:Button id="Button1" style="Z-INDEX: 101; 
    LEFT: 160px; POSITION: absolute; 
    TOP: 80px" runat="server" Text="Button">
  </asp:Button>
  <asp:Button id="Button2" style="Z-INDEX: 102; 
    LEFT: 480px; POSITION: absolute; 
    TOP: 88px" runat="server" Text="Button">
  </asp:Button>
  <asp:GridView id="GridView1" style="Z-INDEX: 103;
    LEFT: 208px; POSITION: absolute; 
    TOP: 152px" runat="server">
  </asp:GridView>
</form>
</body>

In Grid layout, you can position your controls like a WYSIWYG editor with no knowledge of HTML. However, because absolute positioning is not rendered consistently by all browsers, the page layout can be flexible based on the size of other controls on the page, and the Web browser window.

When other controls are dynamically populated, such as a GridView, controls that appear beneath it in the Web form would be obscured if they were positioned absolutely at design time. In addition, when utilizing globalization of pages with different languages, the size of text areas can vary and cause obstructions.

Using Ektron’s Developer SDK

The Developer Software Distribution Kit (SDKSoftware Distribution Kit) for Ektron contains the following components to help you extend and customize your site.

• Developer APIApplication Programming Interface, which includes:
  • Server Control API: An interface for calling the methods and properties of the Ektron server controls. For additional information on the server controls, see Introduction to Server Controls and the Developer API Documentation.
  • Web Services API: Exposes a method’s functionality for use with SOAP over HTTP. For additional information on the Web Services, see Web Services and the Developer API Documentation.
  • .NET Assembly API: Similar to the Business API provided in previous version, the .NET Assembly API provides an interface for calling the methods and properties that are exposed in Ektron. See Also: the Developer API Documentation.
• Developer API Documentation

  The API Documentation contains a detailed description of the functions included in each of the APIs. To access the Developer’s API documentation in Visual Studio, choose Help > Contents. Next, choose Ektron API Documentation from the list of contents. You can also filter the documentation so you see only Ektron’s API documentation. Click Ektron API Documentation in the filter drop-down box.

  You can also access the API documentation online by clicking Ektron Developer Reference.

• Extensions

  Extensions are developer-defined software modules that modify the behavior of Ektron.

  In versions previous to Ektron version 8.0, developers used the Plug-in Extension Wizard to extend the system. As of version 8.0, Extensions are preferred over the Plug-in system.See Also: Extending CMS Behavior

• Ektron Server Controls Toolbox

  Ektron controls are installed with the Developer SDK. Server controls let you insert, via drag and drop or programmatically, many standard methods and properties within the Visual Studio environment. This means that you can see the effect of your changes in real time -- you don’t have to modify a page then compile a sample project to see the results.

An opportunity to install the Developer SDK appears during the installation or upgrade of Ektron (see third checkbox from top in the following dialog box).

If Developer SDK is not checked during installation, you can install it by going to Windows Start button > All Programs > Ektron > CMS400vxx > Utilities > CMS400SDK Install.