Open topic with navigation

Using the search server controls

Beginning with Ektron version 8.5, search capabilities are enhanced with the following 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.

NOTE: To apply paging to a search results page, use an EktronUI:Pager.

Templated 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 are more specialized than their predecessors, which typically used 1 control to retrieve and display results. To provide search functionality, use 3 templated controls.

The following example shows this relationship using site search controls.

Benefits of these controls include the ability to:

To replicate all of the previous search server controls' functionality, use a combination of templated controls. For example, use the Pager control to manage the paging of search results. Also, use the Advanced Query Text parameter to limit results to those in a selected folder, in a selected 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 go content independent of the folder structure. category, and so on.

Search server controls have no Ektron-specific properties. In contrast, the pre-8.5 Search server control properties let you configure language, Display XSLTExtensible Stylesheet Language Transformations, folder ID, and so on.

References

Modifying templated server controls

You modify the behavior of templated controls by editing their markup. You no longer use Ektron server control properties nor an XSLT to edit the control's behavior.

You can edit a control's default markup, as well as the markup on any page that contains it.

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>

Data fields available to an Eval statement

Use an <%# Eval()> statement to determine which field properties appear in search results. For example, <%# Eval("Summary")%> displays each content item's summary.

When you insert <%# Eval()> between a set of </ItemTemplate> tags, a model is passed to the statement. Each set of controls has a model that determines available fields and properties. For example, the SearchModel's Results property includes these fields:

  • Date (late edited)
  • Summary
  • Title
  • Type
  • Url

Discovering a model's fields using the object browser

  1. Open your Ektron website within Visual Studio.
  2. Open the Object Browser.
  3. In the Browse field, enter the set of controls whose model you want to view. For example, ProductSearchModel.

    Other models are SearchModel (covers content and XML Smart Forms) and UserSearchModel. The model's fields appear in the right pane.

  4. To view any field's properties, enter its name into the object browser. Omit the angle brackets (<>).

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.

Adding search server controls to Visual Studio

  1. Open your Ektron project in Microsoft Visual Studio 2010.
  2. Open the Visual Studio Toolbox.
  3. Add a tab and give it a name like Ektron Search.
  4. Click Choose Items....
  5. Click Browse.
  6. Choose siteroot/bin/Ektron.Cms.Framework.UI.Controls.dll.
  7. Click OK. The controls appear on the Toolbox tab

You should also add EktronUI controls to the Visual Studio toolbox at this time.

Customizing templated server controls

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.

Creating a custom service

You can extend the functionality of templated server controls by creating a custom service. For example, you can dynamically replace the content of the search results. You might want to do this to create a profanity filter, or to implement a "blacklist" of replacement terms in search results.

The following image illustrates the location of a custom (passthru) service within MVC architecture.

.

The passthru service completes these steps.

  1. Takes user input from View and Controller Layers.
  2. Modifies it.
  3. Sends modified data to Model Layer.
  4. On the way back, can modify results again.
  5. Send results to Controller.
  6. Controller pushes results to the View Layer.

Creating a custom service procedure

Use the siteroot/ektron.cms.framework.ui.unity.config file to map each search type to a service. The following code example show the section of the file that accomplishes the mapping. By default, Ektron search controls use ISearch.Service to take in and return data.

There are separate register statements for regular searches, product searches, and user searches.

NOTE: The ISearchController service handles regular content and XML Smart Form searches.

<register 
  type="Ektron.Cms.Framework.UI.ISearchController, Ektron.Cms.Framework.UI"  
  mapTo="Ektron.Cms.Framework.UI.Services.SearchController, 
  Ektron.Cms.Framework.UI.Services"/>
<register 
  type="Ektron.Cms.Framework.UI.IProductSearchController, 
    Ektron.Cms.Framework.UI"
  mapTo="Ektron.Cms.Framework.UI.Services.ProductSearchController, 
    Ektron.Cms.Framework.UI.Services"/>
<register 
  type="Ektron.Cms.Framework.UI.IUserSearchController, 
    Ektron.Cms.Framework.UI"
  mapTo="Ektron.Cms.Framework.UI.Services.UserSearchController, 
    Ektron.Cms.Framework.UI.Services"/>

The following steps show how to create your own service and map it to a search type.

  1. In Visual Studio, open siteroot/unity.ui.services.config.
  2. Update the service registration with a new service name. This example assigns to ISearchService a service named DemoSearchService.
    <register 
  type="Ektron.Cms.Framework.UI.ISearchService, 
    Ektron.Cms.Framework.UI"
  mapTo="Demo.DemoSearchService"/>
  3. In Solution Explorer, right click the AppCode folder and select Add New Item.

  4. Select C# Class and give your new service a name.

  5. Within the .cs file, insert this statement: using Ektron.Cms.Framework.UI;
  6. Assign the name of the service that you are overriding. (Service names are listed in unity.ui.services.config.)
    public class DemoSearchService: ISearchService
{
}
  7. Right click the mouse and select Implement Interface > Implement Interface.

  8. Several statements are inserted. They provide inputs to the search service.
    public void AdvancedSearch(SearchModel model)
{
throw new NotImplementedException();
}
  9. To create a passthru service, first instantiate the old mock search service. See also: Creating a custom service
    public class demosearchservice : ISearchService
ISearchService searchService;
public DemoSearchService()
{
this.searchService= new MockSearchService();
}
  10. Inside the Advanced, Basic, GetXmlSearchFieldList and XmlSearch methods, call the old service and pass in the same data. For example
    public void BasicSearch(SearchModel model)
{
this.searchService.BasicSearch(model);
}

    Now, when you drop inputview and resultsview controls on a page...

    • it instantiates the controller.
    • it ties the input and results view controls to the controller.
    • it instantiates the service, which ties the controller to the service.

Example 1: Any search returns “fifteen” for a result

  1. Open the site search template page.
  2. Within SiteSearchResultsView tags, insert a set of <itemtemplate> tags.
  3. Within the <itemtemplate> tags, insert <%# Eval(“QueryText”) %>
    <ektron:SiteSearchResultsView ID="SiteSearchResultsView1" 
  ControllerID="Scontroller" runat="server"> 
<ItemTemplate> <%# Eval(“QueryText”) %> </ItemTemplate>
</ektron:SiteSearchResultsView	\>
  4. Within the new.cs file that you created in Creating a custom service procedure, modify the value of QueryText. For this example, change the query text to "fifteen." To do this, edit the .cs file, like this.
    ‘Public void BasicSearch(SearchModel model)
{
model.Querytext = “fifteen”; }

Example 2: Replace “Summary” with “Ektron” in all results

This example shows how search results may be modified after they are retrieved (that is, on the way back). To do this, edit the .cs file that you created in Creating a custom service procedure like this.

Public void BasicSearch(SearchModel model)
{
  model.Results.ForEach(result => 
   { result.Summary = result.Summary.Replace(“Summary”, “Ektron”); });
}

The above code loops through all results (Results.ForEach) and replaces "Summary" with "Ektron" in each one.

Example 3: Remove first result

This example shows how to remove the first search result that is retrieved. To do this, edit the .cs file that you created in Creating a custom service procedure like this.

Public void BasicSearch(SearchModel model)
{
model.Results.RemoveAt(0); 
}

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.

Retrieving folder vs. folderpath

  • To reference a folder by id number, use folderid:10
  • To reference a folder and all of its children, use folderidpath:'10'
  • To exclude a folder but include all of its child folders, use (folderidpath:'10' AND NOT folderid:10)

    NOTE: You cannot use the root folder as part of the foldernamepath.

Obtaining searchable properties

The following links go to Ektron's searchable properties from the API.

Allowed operators in the AdvancedQueryText parameter

  • equals (=)
  • greater than (>)
  • less than (<)
  • contains (:)

Web search server control

The Web Search server control lets you customize the behavior of search. You place this control on any Web form from which a site visitor can search your site. For more information about the site visitor experience, see Setting up search for your website.

The Web Search server control is deprecated in Ektron version 8.5 and higher. So, pages created prior to 8.5 that use the Web Search server control should work with one important exception: the Solr search provider is incompatible with the Web Search server control.

For new pages, developers are encouraged to replace the Web Search server control with Templated Search server controls. See also: Modifying templated server controls.

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

Web search property descriptions

The following table describes the Web search server control properties. See also: Property usage table.

  • Authenticated (Boolean)
  • 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 a 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)
  • 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)
  • MarkupLanguage (String)

    See also: websearch.ekml

    NOTE: 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 does not 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.

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

    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)

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

Open topic with navigation