Ektron CMS400.Net Reference

>>Managing User Communities > CommunitySearch Server Control

CommunitySearch Server Control

The CommunitySearch server control allows a site user to find users or community groups registered on the Web site. Upon viewing the results, a user can add a colleague or join a community group.

When a user hovers over a user or community group link, profile information appears. Which information appears depends on the status of the user performing the search and the profile settings of the user or group returned in the results.

The CommunitySearch control provides these types of searches:

Directory - filter users by a letter in the alphabet. A user can select whether to search by first or last name. See Using the Directory Tab to Filter for Users.

Basic Search - allows users to search for users and groups. See Performing a Basic Community Search.

Advanced Search - allows users to search based on individual or multiple criteria. See Advanced Community Searching.

Location Search - allows users to search by the location of a user or group. See User Location Searches.

Using the Directory Tab to Filter for Users

The Community Search's Directory tab lets a user filter users based on a letter in the alphabet. For example, John wants to find all users whose first name begin with the letter S. He navigates to the CommunitySearch control on his site, clicks the Directory tab, and selects First Name from the Sort By list. Then, he clicks the letter S. Next, the control displays all users whose first name begins with S.

Performing a Basic Community Search

A Basic search is the easiest to perform and returns the most results.

A Basic search uses the following criteria:

Email

Display Name

First Name

Last Name

Custom User Properties

Personal Tags

Group Name

Group Description

Group Tags

To use a basic search, a user enters a name, email, group name, tag, or a word he believes might appear in a group’s description. Then, he clicks Search. All matches are returned in the results. See Also: Using Community Search Results.

Users can also perform wildcard searches, but the wildcard must appear after the first letter in the search. For example, you can search for J*, but not *J. J* returns all users and community groups that start with J or have a word that starts with J in their email, tags, or description.

Advanced Community Searching

The CommunitySearch's Advanced Search tab lets a user apply multiple search criteria on community groups and users.

In addition to the basic search criteria, advanced search lets users search by taxonomy category if taxonomy ID is defined in the GroupTaxonomyID property, UserTaxonomyID property, or both properties.

Warning! If both the GroupTaxonomyID and UserTaxonomyID properties are set to 0 (zero) or if there are no users or groups assigned to the selected taxonomy, the Category option does not appear on the Group or User drop down list.

See Also: Performing a Basic Community Search

Multiple search criteria have an “and” relationship, so results must match each filter. For example, if you select the Tags filter and the Display Name filter, users or groups must match both criteria to appear in the results. If a user or community group matches only one criterion, it does not appear in the results.

To search using the Advanced Search tab, follow these steps.

1. Navigate to a Web page that hosts the CommunitySearch control.

2. Click the Advanced Search tab.

3. Select the criteria by which to filter the search results.

4. Click Add Filter to add additional filter.

5. Enter text in one of the text boxes.

Note: If a user enters text in both the Users and Groups text boxes, the search returns any matching users or groups.

6. Click Search.

User Location Searches

The Location tab lets a user search for another user based on location. User results are displayed as pins on a map.

For users to be found in the search, they must fill out the Address field in their profile. Ektron CMS400.NET retrieves the longitude and latitude for the address to populate the user location search.

Warning! This tab imports the Map server control. To learn about the Map server control and how to enable location searches for your site, it is strongly recommended that you review the Map server control chapter. See Map Server Control.

If you have not enabled location searches for you site, you can suppress the Location Search tab by setting the EnableMap property to false. This also suppresses the Map icon next to a user’s name in search results.

Using Community Search Results

Once a search is complete, a list of users and groups who match the search term appears. This list shows an avatar, display name, and status for each user or group. In addition, if a user has entered a valid address in his profile, a map icon () appears below the user’s name. Clicking this icon launches the location tab with a map showing the user’s location.

The Status column indicates whether the user is already a colleague, or if you can add him as a colleague via a colleague request. It also allows you to join a community group if you are not already a member.

Click Add as Colleague to send the colleague request or the Join this Group link to join the community group. Status information for each user or group is only displayed when you are logged into the site.

When is a User’s Profile Accessible in Search Results

When a user is logged in and hovers the mouse over the display name link, a floating profile window pops-up. Several factors determine whether a user’s profile is displayed in the pop-up. The table below shows an example of when a user’s profile is accessible in the search results. This example uses John and Jane. John is a user with a profile, while Jane is performing a search.

John’s Profile is ...

Jane is a ...

and Her Login Status is ...

The ResultsProfile Property is ...

Therefore John’s Profile is ...

Public

User

Logged Out

Full

Accessible

Public

User

Logged Out

NonPrivate

Accessible

Public

User

Logged Out

NonPrivate-Authenticated

Not accessible

Public

User

Logged Out

None

Not accessible

Public

User

Logged In

Full

Accessible

Public

User

Logged In

NonPrivate

Accessible

Public

User

Logged In

NonPrivate-Authenticated

Accessible

Public

User

Logged In

None

Not accessible

Public

Colleague

Logged Out

Full

Accessible

Public

Colleague

Logged Out

NonPrivate

Accessible

Public

Colleague

Logged Out

NonPrivate-Authenticated

Not accessible

Public

Colleague

Logged Out

None

Not accessible

Public

Colleague

Logged In

Full

Accessible

Public

Colleague

Logged In

NonPrivate

Accessible

Public

Colleague

Logged In

NonPrivate-Authenticated

Accessible

Public

Colleague

Logged In

None

Not accessible

Private

User

Logged Out

Full

Accessible

Private

User

Logged Out

NonPrivate

Not accessible

Private

User

Logged Out

NonPrivate-Authenticated

Not accessible

Private

User

Logged Out

None

Not accessible

Private

User

Logged In

Full

Accessible

Private

User

Logged In

NonPrivate

Not accessible

Private

User

Logged In

NonPrivate-Authenticated

Not accessible

Private

User

Logged In

None

Not accessible

Private

Colleague

Logged Out

Full

Accessible

Private

Colleague

Logged Out

NonPrivate

Not accessible

Private

Colleague

Logged Out

NonPrivate-Authenticated

Not accessible

Private

Colleague

Logged Out

None

Not accessible

Private

Colleague

Logged In

Full

Accessible

Private

Colleague

Logged In

NonPrivate

Accessible

Private

Colleague

Logged In

NonPrivate-Authenticated

Accessible

Private

Colleague

Logged In

None

Not accessible

Restricting the CommunitySearch to Membership Users

When searching for users, the CommunitySearch server control can return all users or Membership Users only. You can limit the search to Membership Users by setting the control's MembersOnly property to true.

You might want to restrict searches to Membership Users when creating a public facing site. This prevents site visitors from finding Ektron CMS400.NET users. Alternatively, if your site is internal , such as a company intranet, you could allow searching of all users.

Filtering Search Results by Category

The Filter by Category feature helps a site visitor zero in on relevant users and groups. As explained in Assigning Content to a Taxonomy/Category , the Taxonomy Feature lets users assign information categories to user and groups. For example, you might categorize employees by department, such as:

accounting

human resources

purchasing

manufacturing

As new users and groups are created, apply relevant taxonomy categories to them. This makes it easier to find them on your site, because a visitor can search by category along with search text. For example, you might quickly find all employees in manufacturing whose first name is Tom.

Note: This search criterion relies on the assignment of taxonomy categories to users and groups. If they are not categorized, the filter hides relevant but non-categorized users/groups. For example, someone enters a new user (Tom in Manufacturing) but doesn't assign a department to him. If a site visitor on the search page enters Tom and selects the Manufacturing category, he will not find that user even though he exists in Ektron CMS400.NET.

Effect of Setting EnableFilteringResults to True

If you set the EnableFilteringResults property to true, initially the site visitor sees no difference. However, if he enters a search term that returns one ore more users or groups to whom a taxonomy category is assigned and clicks Search, he sees Filter by Category above the results (illustrated below).

Note: If no categories are assigned to the users in the search results, the Filter by Category link does not appear.

If he clicks Filter by Category, the visitor sees all taxonomies with at least one user or group that contains the search text. He can then select categories from the taxonomy structure. If he does, the results refresh, and only user and groups that contain the search text and are assigned to the selected categories appear. If a visitor selects several categories, content that is assigned to any selected category appears.

Note: If the visitor selects a parent category, all of its child categories are selected by default.

In the example above, the site has four users or groups with the letter S. If the user selects Filter by Category then drills down to Management, only one user is found.

If a site visitor performs any of the following actions, all taxonomy category selections are cleared, and a new search is performed.

clicks Search

presses <Enter>

performs an Advanced Search

On the other hand, if a site visitor closes folders in the taxonomy structure, all selected categories remain selected.

Showing a User’s Custom Properties

In search results, you can have a user’s custom properties appear in the information pop-up box when his link is hovered over. To have custom properties appear, add a comma delimited list of custom property IDs to the CustomPropertyID property.

Custom properties are created by the site administrator and applied by a user. See Also: Custom User Properties

CommunitySearch Server Control Properties

The CommunitySearch server control properties are described in this table.

Property

Description

Data Type

Authenticated

Indicates if you are logged in to
the CMS Explorer and can use it to browse to Content, Collections, etc. See Also: Working with Ektron CMS400.NET Server Controls

String

CacheInterval

Sets the amount of time the server control’s data is cached. The default is 0 (zero). This is the amount of time, in seconds, a control’s data is cached. For example, if you want to cache the data for five minutes, set this property to 300 (three hundred). See Also: Caching with Server Controls

Double

CustomPropertyID

Specify a comma delimited list of custom property IDs. These custom properties appear in the pop-up information box for a user when search results are returned. See Also: Showing a User’s Custom Properties

Integer

DisplayXslt

Determines how information is displayed on the page. Enter the path to the XSL file. It can be relative or absolute. The default file is CommunitySearchDirectory.xsl.

Warning! If you want to edit this file, it is strongly recommended that you make a copy, change its name and move it outside of your site's Workarea folder. If you make changes to this file and do not move it out of the Workarea, this file and the changes will be lost when you upgrade.

String

 

DoInitFill

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 codebehind and have it render with your changes shown.

Boolean

EnableFilteringResults

Set to true to display a Filter by Category option when this server control appears. This option helps a site visitor zero in on relevant content by selecting taxonomy categories.

Set to false to suppress the Filter by Category option. See Also: Filtering Search Results by Category

Boolean

EnableGroup

Results

Set to true to include community groups in the search results. Set to false to prevent community groups from appearing in search results.

Boolean

EnableMap

Set to false to hide the map functionality in this control. This hides the Location tab when the control is displayed on a Web site and the map properties in Visual Studio. See Also: User Location Searches

Boolean

EnableMouseOver

True = Enable the profile pop-up when hovering over a display name in search results.

False = Disable the profile pop-up when hovering over a display name in search results.

Boolean

EnableMouseOutHidesInfo

If this property is set to True and a user moves his mouse away from a search result’s information pop-up box, the box disappears.

If this property is set to False, a user must click the close button in the upper right corner of the information pop-up box to hide it.

Boolean

EnableUnauthorizedSearching

True = a user does not need to be logged in to perform a user search.

False = a user must be logged in to perform a user search.

Boolean

EnableUserResults

Set to true to include users in search results.

Set to false to exclude users from search results.

Boolean

FriendsOnly

Set to True to limit the results to a user’s colleagues. When set to False, returns all matches.

Boolean

GroupTaxonomyID

Enter the ID of the taxonomy you want to associate with this control. This allows users to search for community groups based on assigned taxonomies.

If set to 0 (zero), the Category option does not appear in the Group drop down list on the Advanced tab. See Also: Filtering Search Results by Category

Long

Hide

Used to hide output of the control in design time and run time.

True = Hide control

False = Display control

Boolean

InfoBoxShowsEmail

Set this property to True if you want a user’s email to appear when hovering over his name in the search results.

Boolean

Language

Set a language for viewing the server control. This property shows results in design-time (in Visual Studio) and at run-time (in a browser).

Integer

LoadingImage

The image to display while the User Search is loading. The default is <site root>\Workarea\images\application\ajax-loader_circle_lg.gif.

String

MapControl

This property allows you to set properties for the Location Tab’s map. These properties are identical to the properties in the Map server control. For information on the Map control’s properties, see Map Server Control. The EnableMap property must be set to true to see the Map control properties. See Also:

Note: Only Ektron's Map server control properties are described in this section. It does not describe native .NET properties such as font, height, width and border style. For documentation of these properties, see Visual Studio help.

Ektron.Cms.
.Controls.Map

MarkupLanguage

Identify the template markup file that controls the display of the server control. For example, mymarkup.ekml. If the *.ekml file is located in the same folder as the Web form containing the server control, just enter its name. Otherwise, the path to the file can be relative or absolute. See Also: Controlling Output with Ektron Markup Language

String

MaxTagCount

The maximum number of personal tags to display for each user in the search results.

Integer

MembersOnly

When set to True, this server control only returns Membership Users. When set to False, the control returns Ektron CMS400.NET and Membership users.

Boolean

PageSize

The maximum number of user results to show per page.

Integer

ResultsProfile

Determines whether profile information is displayed. This is based on the state of the user performing the user search. See When is a User’s Profile Accessible in Search Results.

Choices are:

full - always show user profile information.

nonprivate - display user profile information only when a user’s profile is not marked private.

nonprivate-authenticated - display user profile information only when a user’s profile is not marked private and the user performing the search is logged in.

none - never show user profile information.

String

SearchPrivate

When set to False, this property excludes users with private profiles from search results.

Boolean

ShowNameEmail

When set to True, populates the drop down list with these additional options:

First Name - perform searches based on a user’s first name.

Last Name - perform searches based on a user’s last name.

Email - perform searches based on a user’s email address.

When set to False, the drop down list is populated with these properties:

Tags - perform searches based on a user’s tags.

Display Name - perform searches based on a user’s display name.

Boolean

StartingTab

Select which tab appears when the control is first rendered on a Web page. Choices are:

basic

advanced

location

String

Stylesheet

Specify the path to a style sheet for use with this server control. The location can be relative or absolute. Leave blank to use the default style sheet.

Warning!   If you enter a valid EkML file at the MarkupLanguage property, the Stylesheet property is ignored.

String

SuppressWrapperTags

Suppresses the output of the span/div tags around the control. The default is False.

True - Suppress wrap tags.

False - Allow wrap tags.

Boolean

TemplateGroupProfile

The URL path of the community group template. This path can be relative or absolute.

String

TemplateUserParamName

Gets or sets a Querystring parameter for the ID of users returned in search results.

This parameter is passed to the template page defined in the TemplateUserProfile property when a user clicks the Location (map) icon associated with a search result.

String

TemplateGroupParamName

Gets or sets a Querystring parameter for the ID of groups returned in search results.

This parameter is passed to the template page defined in the TemplateGroupProfile property when a user clicks the Location (map) icon associated with a search result.

 

TemplateTarget

Defines the way a the template appears when the Location link is clicked.

Choices are:

_blank - This target causes the link to always be loaded in a new blank window. This window is not named.

_self - This target causes the link to always load in the same window the anchor was clicked in. This is useful for overriding a globally assigned BASE target.

_parent - This target makes the link load in the immediate frameset parent of the document. This defaults to acting like “_self” if the document has no parent.

_top - This target makes the link load in the full body of the window. This defaults to acting like “_self” if the document is already at the top. It is useful for breaking out of an arbitrarily deep frame nesting.

ItemLinkTargets

TemplateUserProfile

The URL path of the user profile template. This path can be relative or absolute.

String

UserTaxonomyID

Enter the ID number of the taxonomy associated with users to appear in this server control. This allows searching for users based on an assigned taxonomy.

If set to 0 (zero), the Category option does not appearon the Advanced tab's User drop down list . See Also: Filtering Search Results by Category

Long

WrapTag

Allows a developer to specify a server control’s tag.

The default is Span.

Span - The <span> tag is used to designate an inline portion of an HTML document as a span element.

Div - The <div> tag is used when you want to apply attributes to a block of code.

Custom - Allows you to use a custom tag.

String


Visit the Ektron Dev Center at http://dev.ektron.com 1-866 - 4 - EKTRON

Ektron CMS400.NET Reference Version 8.02 SP1 Rev 1

Ektron Documentation,© 2011 Ektron, Inc.