Using Search Server Controls

Customizing a Single Instance of a Templated Search Server Control

1. Open a page in Visual Studio.
2. Drag an InputView or a ResultsView control onto the page. This section uses the SiteSearchResultsView server control as an example.
3. Insert <ItemTemplate> tags between the control's opening and closing tags. <ItemTemplate> tags instruct the server control to ignore the default properties.
   

   <ektron:SiteSearchResultsView ID="SiteSearchInputView1" 
     ControllerID="Scontroller" Visible="true" runat="server"> 
     <ItemTemplate> </ItemTemplate>
   </ektron:SiteSearchResultsView>

4. Copy the default markup from the control's corresponding .ascx file. Here is a portion of that.
   

   <ektron:SiteSearchResultsView ID="SiteSearchInputView1" 
     ControllerID="Scontroller" Visible="true" runat="server"> 
     <ItemTemplate> 
       <h1>Search Phrase:<%# Eval("QueryText") %></h1> 
       <asp:ListView ID="aspResults" runat="server" 
         DataSource='<%# Eval("Results") %>' 
         ItemPlaceholderID="aspPlaceholder"> 
         <layouttemplate>
           <ul class="results"> 
             <asp:PlaceHolder ID="aspPlaceholder" runat="server"> |
             </asp:PlaceHolder>
           </ul>
         </layouttemplate> 
         <itemtemplate> 
           <li class="result ektron-ui-clearfix"> 
             <h3 class="title">
               <a href="<%# Eval("Url") %>"><%# Eval("Title") %></a> 
             </h3> 
             <div class="summary">   
               <%# Eval("Summary") %> 
             </div> 
             <span class="url ektron-ui-quiet">  
               <%# Eval("Url") %>
             </span> 
             <span class="date ektron-ui-quiet"> 
               <%# Eval("Date") %>
             </span> 
           </li> 
         </itemTemplate> 
       </asp:ListView> 
     </Itemtemplate> 
   </ektron:SiteSearchResultsView>

5. Modify the markup to your specifications.

Modifying the Default Markup

InputView and ResultsView controls have a corresponding .ascx template that contains their default markup. To change a control's default markup, modify its template.

To find a control's template file, open the folder siteroot\workarea\FrameworkUI\Templates\Search, and locate the .ascx file that matches the control's name. For example, siteroot\workarea\FrameworkUI\Templates\Search\SiteSearchResultsView.ascx.

NOTE: "Controller"controls only process data. Because they have no UI component, they do not have a template file.

The default .ascx file affects all instances of a control on your website. However, you may customize single instances of a control. To do so, see Customizing a Single Instance of a Templated Search Server Control.

Modifying a Templated Control's Markup

Within an </ItemTemplate> tag, use an eval statement <%# Eval() >) to access Ektron's Search API object and expose its properties to the data binder. For example, <%# Eval (“QueryText”)%> displays the search term in the search results.

As an example, you can remove the summary from the search results by deleting this line.

<div class="summary"><%# Eval("Summary") %></div>

Modifying the Text Displayed by Templated Server Controls

To modify the text displayed by a templated control (for example, no results found), edit the corresponding .resx file in the siteroot\workarea\FrameworkUI\Templates\Search\app_loclaresources folder.

For example, to edit text supplied by the Site Search template, edit siteroot\workarea\FrameworkUI\Templates\Search\app_loclaresources\SiteSearchInputView.ascx.resx.

Injecting Your Own Service

Ektron's templated server controls use an MVC architecture, which is a common design pattern for user interfaces. MVC consists of a

• Model, which stores the state and accesses the application code used by the control; resides in the service layer
• View, which renders the data
• Controller, which maps action inputs to the model and elements view; also performs the business logic of the UI

Because MVC architecture separates the display layer from the data layer, a designer can work on the styling of the search results page, while a developer focuses on data being rendered.

Using the Advanced Query Text Parameter

The AdvancedQueryText parameter lets you customize the behavior of the search controller. As examples, you can restrict search results to

• content properties, such as
  • content in a folder, or a folder and all of its child folders
  • Spanish-language content
• user properties, such as
  • tags set to "Race Car Fans"
  • email address includes "widgets.com"
• eCommerce product properties, such as
  • catalog number is between 1 and 10,000
  • sale price is less than $50 US

Here is a sample AdvancedQueryText statement that restricts search results by language and folder.

(Assumes a SiteSearchController named siteSearchController1 is defined on my page)

<ektron:SiteSearchController ID="siteSearchController1"></ektron:SiteSearchController>

Set the AdvancedQueryText property in the code-behind for that page:

protected void Page_Init(object sender, EventArgs e)
  {
    siteSearchController1.AdvancedQueryText = string.Format(
       "({0}:1033 AND {1}:10)",
       SearchContentProperty.Language.Name,
       SearchContentProperty.FolderId.Name);
  }

The value assigned to AdvancedQueryText is appended to the user’s input.

Property Usage Table

Web Search server control properties generally affect the control in one of three ways.

• Search Display—the server control’s appearance on a Web page
  • ButtonImgSrc
  • ButtonText
  • DisableForumSearch
  • EnableAdvanced Link
  • Hide
  • Language
  • MaxCharacters
  • ShowSearchOptions
  • Text Box Size
  • WrapTag
• Search Criteria
  • CustomSearch
  • FolderID
  • Language
  • Recursive
  • SearchFor
  • ShowCategories
  • ShowSearchOptions
  • ShowSuggested Results
• Search Results Display
  • CustomOrderBy
  • DynamicContentTemplate
  • DisplayXslt
  • Hide
  • Language
  • LinkTarget
  • MaxTeaserLength
  • OrderBy
  • OrderDirection
  • RemoveTeaserHtml
  • ResultsPageSize
  • ResultTagId
  • ShowCustomSummary
  • ShowSearchBoxAlways

WebSearch Property Descriptions

The following table describes the Web Search server control properties. See Also: Property Usage Table.

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.

• Authenticated (Boolean)Indicates if you are logged into the CMS Explorer and can use it to browse to content, collections, and so on. See Also: Browsing Your Ektron Site Using CMS Explorer.
• ButtonImgSrc(String)

  If you want to display an image on the submit button, enter the server path to the image.

• ButtonText(String)

  The button text if no image source is identified in the ButtonImgSrc property. If an image source is identified, this is alternate text for the button.

• CustomOrderBy(String)

  Provide a property’s Friendly Name defined in the Indexing Service to sort search results by that property. For example, if you define DocAuthor, results are sorted by the document’s author. A property's Friendly Name can be found in Computer Management > Services and Applications > Indexing Service > Your Index > Properties > Friendly Name column.

  Results can be ascending or descending based on OrderDirection. If you enter an invalid property, no search results are returned.

  If you specify CustomOrderBy and OrderBy, the OrderBy property is ignored.

• CustomSearch(String)

  If you want the search to include folders outside of Ektron, enter the folder names here. Separate multiple items with a comma. You do not need to enter the folder path, but it must reside within the site root folder. See Also: Including External Files in Your Search.

• DisableForumSearch(Boolean)

  Set to true if you want to remove Forums from the list of content types that appears on the Search server control. The default value is false. Regardless of this setting, if a user selects Site from the list, forum posts are searched.

• DisplayXslt(String)

  Determines the display of the search results page.

  • None—databind only
  • ecmNavigation—lists the title of every content item found by the search
  • ecmTeaser—lists the title and summary of every content item found by the search

    See Also: ecmTeaser Display Example.

  • ecmUnOrderedList—sorts in no particular order. Shows the title and content summary.

  • Path to Custom Xslt—Enter the path to an Xslt that determines the display of the page.

    WARNING! If you specify an external Xslt file, it is strongly recommended that you do not store this file in your site's Workarea folder. If you store this file in the Workarea folder, the file will be lost when you upgrade.

    WARNING! If you enter a valid EkML file at the MarkupLanguage property, this 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.

• DynamicContentTemplate(String)

  Sets the template for dynamic content. This property overrides any quicklink template for the content.

• EnableAdvancedLink (Boolean)

  Set to true to display an additional tab (Advanced) on the Search control. See Also: Advanced Search.

• FolderID(String)

  The folder at which the search begins. The starting folder need not be the root folder. The Recursive property determines if the search examines this folder’s subfolders. See Also: Browsing Your Ektron Site Using CMS Explorer.

• Hide (Boolean)

  Select False to display this server control on the page. Select True to suppress it.

• Language (Integer)

  If the template on which this server control resides includes a language selection control, and you want to let the site visitor select the language, enter zero (0). Otherwise, click the field, then the ellipsis button and a popup box appears. Select a language from the list.

  This property shows results in design-time (in Visual Studio) and at run-time (in a browser).

• LinkTarget(String)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: Controlling Output with Ektron Markup Language, websearch.ekml.

  NOTE: If you enter a valid EKML file at the Markup Language property, the Dispay xslt property value is ignored. If the EkML file contains the [$ImageIcon] variable, the IncludeIcons property acts as True.

• MaxCharacters(Integer)

  The maximum number of characters the Search text box accepts. If you enter less than 50, set the TextBoxSize property to the same number.

• MaxTeaserLength(Integer)

  Limits the length of any returned content’s abstract. To allow unlimited length, set to zero (0). This property is active only if both of these conditions are true.

  • You use the DisplayXslt property to identify an xslt and ecmteaser as a value of that property. If you enter an .ekml file at the MarkupLanguage property, this value is ignored.
  • the ShowCustomSummary property is set to false. If it is set to true, the entire summary appears in search results.

• OrderBy(String)

  The field that determines the sorting of search results.

  NOTE: The Order Direction field determines the direction of the search results. For example, if you sort by ID and Order Direction is set to Descending, the results sort by ContentID with the highest ID number at the top of the list.

  • Title—The content title (alphabetical)
  • ID—The content ID number
  • Date Created—The date the content was created
  • Date Modified—The date the content was most recently modified
  • Editor—The user who last edited the content (alphabetical)
  • Rank—The content's rank. See Also: Search Result Ranking.
• OrderDirection(String)

  The direction in which search results are sorted. The default is Ascending.

  Ascending—Alphabetical results from A to Z; numeric values low to high; dates from oldest to most recent

  Descending—Alphabetical results from Z to A; numeric values high to low; dates from most recent to oldest

• Recursive(Boolean)

  Determines whether to search sub-folders of the starting folder. The FolderID property determines the starting folder.

• RemoveTeaserHTML(Boolean)

  Set to true if you want to remove HTML tags from the content summary within search results.

• ResultsPageSize (Integer)

  Set the maximum number of search results on a page. If a search returns more than this many results, the following text appears below the last one:

  Result Page: 1 2 3 Next

  The user can click Next or a number to view additional results.

  This property defaults to the value set at the ek_PageSize element in the siteroot\web.config file.

  Property’s Effect on Suggested Results

  Only the number of Suggested Results up to this maximum appear. If more than this number should display, they do not. This is unlike natural search results, whose additional links are available via numbers below the maximum page size.

  See Also: Providing Suggested Results.

• ResultTagId(String)

  Lets you designate where search results appear. You can place search criteria in one area of a Web form and results in another. For example, you have the following tag.

  <span id=”results”></span>

  In this case, enter results for this property's value.

• SearchFor(String)

  Choose the type of content that may be searched via this control.

  • All
  • HTML
  • Documents
  • Images
  • Multimedia
  • Discussion Forums
  • Tags
  • eCommerce products
  • PageBuilder

  If the value is anything other than All, this server control only examines the selected content type.

  IMPORTANT: If this property is set to anything other than All, the search options drop-down does not appear.

• SearchSynonyms (Boolean)

  If set to true, the Synonym Search is included with the search. If false, Synonym Sets are ignored. See Also: Using Synonym Sets.

• ShowCategories (Boolean)

  If set to true, this server control displays a Filter by Category option, which helps a site visitor zero in on relevant content. If false, Filter by Category does not appear.

  IMPORTANT: In order for the Filter by Category option to appear, the ShowSearchBoxAlways property must be set to true.

  As explained in Organizing Content with Taxonomies, the Taxonomy feature lets users assign information categories to content. For example, if your organization is a university, taxonomy categories might be Athletics, Alumni, Admissions, Academic Departments, and so on. As new content is created, users should apply relevant taxonomy categories to it. This enables a site visitor to search by category and search terms. For example, if the search term is calendar and the category is Athletics, the search would typically return calendars of sports teams but not other calendars, such as those for graduation, exams, or parent weekend.

  NOTE: This property depends on the assignment of taxonomy categories to content. If they are not, the filter hides relevant but unclassified content.
  For example, an author creates an article on “Treating Heart Disease” but doesn't assign a taxonomy category to it. If a site visitor on a search page selects Filter by Category then the Medical Forum > Heart Disease category, he will not find that article.

  A developer can control whether results must match all categories selected in the Filter by Category tree, or at least one category. To display results that must match all categories, set the TaxonomyOperator property to And. To show results that match one or more categories, set TaxonomyOperator to Or. By default, the property is set to Or, which provides a wider range of results.

  Effect of Setting ShowCategories to True

  If you set ShowCategories to true, initially the site visitor sees no difference. Upon entering a search term that exists in content to which a taxonomy category is assigned and clicking Search, Filter by Category appears above the results (illustrated below).

  —Image—

  

• ShowCustomSummary (Boolean)

  If set to true, the search results display the content item’s summary. If false, the search results display the characterization. The default is false.

  NOTE: If this property is set to true, the MaxTeaserLength property is ignored. So, the entire summary appears with search results, regardless of length.

• ShowSearchBoxAlways (Boolean)

  If set to true, the search box appears on the PostBack screen. If false, the search box does not appear on the PostBack screen. The default is true.

• ShowSearchOptions (Boolean)

  If set to true, the following drop-down appears to the right of the Search box.

  —Image—

  

  A site visitor can click an option to limit the search by content type. If the user accepts the default value, Site, all content types are searched.

  WARNING! If the SearchFor property is set to anything other than All, the search options drop-down does not appear.

  NOTE: If the DisableForumSearch property is set to true, Forums does not appear in the drop-down.

• ShowSuggestedResults (Boolean)

  If set to true, Suggested Results related to the search term appear. If false, Suggested Results do not appear. See Also: Providing Suggested Results.

  NOTE: If the ResultsPageSize property value is less than the number of suggested results applied to a term or synonym set, only the property’s number of results appears. For example, if you assign five links to a Suggested Result set but set ResultsPageSize to three, only the first three results appear.

• Stylesheet(String)

  If you want to define a style sheet for the search results page, specify its path relative to the site root folder. For example: Workarea\csslib\mytest.css. Leave blank to use the default style sheet, webroot\Workarea\csslib\search.css.

  WARNING! If you enter a valid EkML file at the MarkupLanguage property, or a value at the DisplayXslt property, this property is ignored.

• SuppressWrapperTags (Boolean)Suppresses the output of the span/div tags around the control.
  • True—Suppress wrap tags.
  • False (default)—Allow wrap tags.
• TaxonomyOperator (Enum-TaxCategoryOperator)

  Select whether to use an And or Or operator when filtering results by taxonomy. the default value is Or.

  And—Only results that match all categories selected in the Filter by Category tree appear. For example, if a site visitor is searching for a medical document in the Hospital and Doctor’s Office categories, only documents assigned to both categories appear.

  Or—If more than one category is selected in the Filter by Category tree, results needs to only match one category to be shown.

  NOTE: For this property to be active, the ShowCategories property must be set to true.

• TextBoxSize (Integer)

  The size of the search text box for user input, in number of characters.

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