Filter URL parameters

Tip Because the process for identifying and encoding filter URL parameter values can be a bit complicated, you can accomplish the same thing more easily by creating a filter view. If you want help comparing filter and filter view parameters and deciding which to use, contact Trumba Support. Learn more about filter views and filter view URL parameters.

Filter parameters are optional parameters that can be:

• Included in the url argument in the $Trumba.addSpud() method.
• Appended to the trumbaEmbed parameter in a URL-encoded query string.
• Appended to the base URL for an RSS, Atom (XML), iCalendar (ICS), Comma Separated Value (CSV), or JSON calendar feed.

I'd like to see a complete list of URL parameters.

I'd like to know more about calendar feeds.

How filter parameters work

• To use filter parameters, you must have configured one or more filter control spuds. Configuring a filter spud means selecting the field(s) and field values by which you want to filter.

  Tell me more about filter spuds.

• To see results when you filter, your published calendar must include events that use the fields and field values represented by the parameters with which you're filtering.
• For any published calendar, you can filter by a maximum of five custom and/or built-in fields across all of the filter spuds as well as the filter views you configure.

  Tell me more about filter views.

• Filter URL parameters take the form of filter1, filter2, filter3, filter4, and filter5. You can use one filter parameter at a time or use any number (up to five) of filter parameters together.
• The numbers indicate the order in which you assigned fields to the filter spuds and filter views you configured.

  For details about how to find the assigned fields and the order in which you assigned them, see Constructing filter URL parameters.

Application

Filters the events you see by specific field values from the filter spuds you configured.

Tip If you haven't assigned the fields and field values you're filtering by to any events on your published calendar, you'll get zero results.

• An art gallery configures a Category filter and then provides a dedicated webpage to display only events with the field value Docent Talks.
• An Admissions Office configures a Visit Type filter and then provides a link to an "overnight visits" view that lists only events with the field values Overnight Visits for Girls and Overnight Visits for Boys.

Values

The values that filter parameters take are the field values for which a filter spud is configured. In some cases the field values are represented by text and in other cases the field values are represented by numbers.

For example, an Alumni Chapter filter's field values might be represented by text such as Washington, California, and New York.

An Audience filter's field values might be represented by numbers similar to 274766 and 274767.

For details about how to find the words and numbers that represent field values, see Constructing filter URL parameters.

Works with

• Main calendar spuds
• Month list spud
• Filter spuds
• Promotion spuds

Constructing filter URL parameters

Constructing a filter parameter is a three-step process:

1. Determine which filter parameter number you want to use.
2. Find the words or numbers that represent the field values by which you want to filter.
3. Add a filter URL parameter to the url argument in spud code and/or to a URL-encoded query string.

Determine which filter parameter number you want to use

To see a list of the fields assigned to filter spuds and views and the order in which you assigned them:

• In the Publishing Control Panel, click the Publish Settings tab. Under Distinct filter fields, the fields are listed in their assigned order.

  

  In this fields list, filter1 is Audience, filter2 is Event Type, filter3 is Delivery / Format, and so on.

Find the words or numbers that represent the field values by which you want to filter

To find the word or number that represents a field value:

1. Go to the webpage on your site where the main calendar spud and filter spuds are embedded.

   If you haven't published your calendar yet, in the Publishing Control Panel, on the Publish Settings tab, click Preview all Spuds.

2. In the filter spuds, select the field values that create the filtered view you want.
3. View the source code for the frame that contains the main calendar spud.

   The way you do this differs by browser. For example:

   • In Mozilla® Firefox®, right-click the main calendar spud, and then select This Frame > View Frame Source.
4. In the source code, there's a variable toward the top of the page that shows you the URL for the spud. That URL, which contains the field values, will look something like these examples:
   var trumba_baseUrl = '/calendars/calendarname?
   template=detaillist&filter1=_California_Washington_&filterfield1=3599&
   calendar=calendarname';

   This URL indicates that the field values for filter1 are the words California and Washington.

   var trumba_baseUrl = '/calendars/calendarname?filter2=_459464_459465_&filterfield2=31340&calendar=calendarname';

   This URL indicates that the field values for filter2 are the words 459464 and 459465.

Tip

• If you can't or don't want to view the source code, you can find the filter field values another way. Click the RSS feed button at the top of the main calendar spud. The URL of the RSS feed window that opens contains the field values. The URL will look something like these examples:

  http://www.trumba.com/calendars/calendar.1005492.rss?filter1=_California_Washington_&filterfield2=30476

  This URL indicates that the field values for filter1 are the words California and Washington.

  http://www.trumba.com/calendars/calendar.1008652.rss?filter2=_428302_428303_&filterfield2=30476

  This URL indicates that the field values for filter2 are the numbers 428302 and 428303.

Add a filter URL parameter

Use the examples that follow for specific guidance on adding filter parameters to url arguments in spud code and URL-encoded query strings.

The examples illustrate these guidelines:

• Wrap the entire field values string in underscores.
• If you filter by multiple values, use an underscore to delimit the values.
• To use a filter value that contains an underscore, such as a Region defined as WI_Midwest, encode the underscore by preceding it with a period.

  For example, WI_Midwest becomes _WI._Midwest_.

• If a field value contains multiple words, in URL-encoded query strings, encode the space character between the words as %20.
• If a field value contains a period (.), in URL-encoded query strings, encode the period using another period (.).

  For example, Under $10.00 becomes _Under%20%2410..00_. (%24 is the URL-encoded dollar sign ($).)

Tip In calendar feed URLs, it's not necessary to wrap entire field value strings in underscores or to encode periods. However, you must put underscores between field values and period-encode underscores. See the Calendar feed URL section below for specific examples.

Examples