TeamRaiser: Event Search Component and API

Melissa Ugiansky

Feature Summary

Release: Fall '09

Author: Noel Beebe

ALL TEXT IN RED IS INTERNAL AND NOT CLIENT FACING

Overview

Clients often have multiple TeamRaiser events within one instance of Convio.  As a participant, it can be difficult to locate the correct event to register for.  This Event Search feature consists of a search component that can be dropped into a Pagebuilder page so that participants and donors can search for an event by event name, city, state, and/or county, or enter their ZIP code and perform a radius search to find the event closest to them.  These search methods are also available via API in case clients would like to post a search opportunity on a third-party site.  API Documentation will be provided separately on http://open.convio.com.

New Concepts or Terms

n/a

Use Scenario

Jane would like to register for her local “Run for Clean Air” event, but is not sure which event is closest to her.  She visits the Clean Air Society site, and goes to a landing page for the “Run for Clean Air” event series.  There is an opportunity for her to enter search terms and locate the event closest to her. She chooses to search by ZIP code, so she enters her 5-number ZIP code, selects the radius of 25 miles, and clicks “search.”  When the list of events matching her criteria appears on her screen, she clicks the closest event and is taken to the greeting page for that event, where she completes her registration.

Key Features

• New WYSIWYG Component allows constituents to visit a Pagebuilder page and search for an event by Name, City, State, County, or distance from ZIP Code.
• Configuration options for admins to constrain the event results to a specific security category, center, or event type, and determine other search parameters such as radius options or units of distance.
• New S Tag available to hand code the TeamRaiser search component (S408)
• New API methods allow clients to create a search widget on a third-party site, or in another presentation layer, like Convio CMS.

Feature Configuration & Use

Please note that in order to use location or ZIP code searching, clients MUST have location details entered for each TeamRaiser event.  If location details are not present, no search results will return from a search by location or ZIP code. To configure location details, administrators can edit a TeamRaiser and go to Step 3 “Configure Event Options” and select Enter Location Details from the Related Actions.

This feature will be available by default.  To use the event search, clients can edit a Pagebuilder page, click the Components icon/drop-down, and select the TeamRaiser Search Components > Event Search.  The configuration options will appear, allowing the administrator to choose the search parameters available, the ZIP code radius values available, the units (miles or kilometers) in which to calculate distance from ZIP code, the security category of the events to be searched, the event type to be searched, and the number of event results that should appear on each page.  The administrator can configure these options and insert the component in the page.

There are three new SDPs available to set the default options available in the component:

• F2F_EVENT_SEARCH_DISTANCE_UNITS – determines whether miles or kilometers are displayed by default
• F2F_EVENT_SEARCH_RADIUS_VALUES – determines the default values of distance from the zip code entered
• F2F_EVENT_SEARCH_RESULTS_PER_PAGE – determines the default number of search results that display on each page

S Tag Configuration

This Component is also available via S Tag for hand-coding as S408.

Syntax:]

Parameters

• include_name - A value of "0" means the form will not render the field allowing users to search by Event Name. Any other value will result in the event name field being available. It is recommended that you use either "0" or "name" for this parameter.
• include_city - just like name, but for the field that searches by Event City. A 0 means the field will not be displayed. Recommended: "0" or "city".
• include_county - just like name and city, but for the field that searches by Event County. A 0 means the field will not be displayed. Recommended: "0" or "county".
• include_state - like name and city, but for the state search field. Recommended: "0" or "stateprov".
• include_postal - like name, city, and state, but for the zip code field and distance search. Recommended: "0" or "postal"
• comma_separated_list_of_radius_values - This is a comma separated list of numbers that will be presented to the user in the selection form for distance searches. Valid numbers are 0-200, inclusive. Values under 0 or over 200 will be ignored when the component renders. If no valid values are provided, will attempt to use the values in the SDP F2F_EVENT_SEARCH_RADIUS_VALUES. If the SDP contains no valid numbers, the component will use a default value of "5,10,15,25,50,100,200". Duplicate entries in the list will not be displayed as duplicate choices to the site visitor. Entries will appear in the order that they are entered (they are not automatically sorted - that is, a list of 10,5,20 will display to the user as a list of 10,5,20).
• units_of_distance - Will limit the distance search to this unit of measurement, or will allow the user to select whether they want to search by miles or kilometers. Accepted values are: mi, km, or choice. If an invalid option is passed in, the component will use the value of the SDP F2F_EVENT_SEARCH_DISTANCE_UNITS. If the SDP does not contain one of the 3 valid options, the system will default to using choice.
• category - Limits the search results to events within this category, a value of 0 will search all security categories. Accepts either the category_id or the category Name. If there is no category with the specified category_id or name, the component will render an error message. May be used in conjunction with the classification parameter to limit the search to events within a specific category and within a specific event type.
• Classification - Limits the search results to events with a Primary Event Type (also known as a classification) equal to the specified parameter. A value of 0 will search all event types. Accepts either the classification id or the classification name. If there is no Primary Event Type with the specified classification id or name, the component will render an error message. May be used in conjunction with the category parameter to limit the search to events within a specific category and within a specific event type.
• results_per_page - sets how many rows will be displayed per page in the search results. Valid ranges are 1-50, inclusive. If an invalid value is passed in, the component will attempt to use the value from the SDP F2F_EVENT_SEARCH_RESULTS_PER_PAGE. If the SDP contains an invalid value, the component will default to a value of 20 results per page. You cannot display more than 50 results per page. Values under 5 are not recommended as they provide bad usability, but values under 5 are great for testing.

Limitations and Out of Scope Features

1. The ZIP code search works for US ZIP Codes only – at this time there are no plans to incorporate other postal codes.
2. The TeamRaiser search component is not available in the CMS Convio Components option at this time – please use the API to incorporate the event search component in CMS.

FAQs

Q: Is this component available in both the old and new WYSIWYG?

A: Yes, the component can be used in both versions of the WYSIWYG, or as an S Tag.

Screenshots

Configure Search in New WYSIWYG

Configure Search in Legacy WYSIWYG

Search by Event Information - User View Search and Results

Search by ZIP Code

##END

IMPORTANT NOTE: THIS DOCUMENT INTENDS TO PROVIDE A COMPLETE AND ACCURATE REPRESENTATION OF WHAT CONVIO FULLY EXPECTS TO DELIVER IN FALL ‘09 (AS OF SEVERAL WEEKS PRIOR TO LAUNCH) BASED ON COMPLETED SOFTWARE DEVELOPMENT.  THIS DOCUMENT AIMS TO SERVE AS THE BASIS FOR PLANNING AND PREPARATION WELL IN ADVANCE OF ACCESS TO THE NEW FEATURES.  GIVEN THIS DOCUMENT WAS DRAFTED PRIOR TO COMPLETED QUALITY ASSURANCE, ALL FEATURES, CAPABILITIES, SCREENSHOTS, ANSWERS, CLIENT IMPACTS, SITE DATA PARAMETERS, AND LIMITATIONS LISTED HEREIN, WHILE REASONABLY CERTAIN FOR INCLUSION IN THE RELEASE, ARE SUBJECT TO CHANGE AT ANY POINT UP UNTIL ROLLOUT ON YOUR CONVIO SITE.