Group Finder

Instructions for configuring and using the Group Finder in your Rock.

Requires:

• Rock 19.0+ (churches on Rock v16 to v18 should stay on Group Finder v1.1)
• Google Maps API Key

Overview

The 9 Embers Group Finder makes it simple for people to discover and join the right group in Rock RMS. Users can filter by location, day, time, campus, keywords, leader name, or custom attributes and browse in a clean map or list view, all with fast performance and easy customization.

If you prefer step-by-step video instructions you can view that here: Group Finder Video Instructions.

What's New in v1.2

• Group members on the map – Optionally show the members of selected group types on the map, so people can see who lives near them. See Showing Group Members on the Map below.
• Now requires Rock v19. Churches on Rock v16 to v18 should stay on v1.1.
• Address lookups now use the Google API Key Server global attribute when it's set, and fall back to the Google API Key global attribute otherwise.
• Fixes – Map cluster counts no longer grow each time filters change, saving block settings now refreshes all cached templates, and the Refresh Group Finder Cache job now respects the Include Full Groups setting.

Key Features

• Flexible filtering – Search by keywords, campus, meeting day, meeting time, leader or host name, and custom attributes to quickly narrow options.
• Display modes – Choose a map view, list view, or both.
• Map integration – Show group and campus locations with clear markers and info windows.
• Location clusters – Groups located close together cluster until you zoom in.
• Group members on the map – Optionally show nearby group members, with their locations blurred for privacy.
• Registration support – Link directly to a sign-up page or trigger a workflow for seamless group registration.
• Performance optimization – Built-in caching keeps pages fast and responsive.
• Accessibility & responsive design – Works smoothly on desktop or mobile and handles full groups gracefully.

Standout Features

Map clustering makes it easier to view groups in crowded areas. Groups located close together will cluster until you zoom in, making dense regions simple to explore.

Each group, whether selected from the map or a card view, includes a "Learn More" link that opens a detailed page with general location mapping to preserve privacy, along with all group details.

You can also assign custom colors to different group types for quick visual recognition.

For joining a group, you can use Rock's core Group Member Registration block or direct users to a workflow. The Join Group button navigates to the standard Rock group sign-up experience.

Installation & Configuration

After purchasing the Group Finder plugin, Rock will automatically add a new Group Finder block along with the required Lava files and CSS styles. The block is placed on a new Group Finder page (with a Group Registration page beneath it) within the default public site that comes with Rock, making it easy to preview and explore right away.

Build your Group Finder by adding a new Group Finder block to any page where you want it to appear. Then configure the block attributes to match your church's needs.

Block Attributes

The Group Finder block includes settings grouped into three sections: General, Map Settings, and Templates. You'll update these in the block's Properties panel to decide how the finder looks and functions.

General Settings

This first section controls the information shown and how people can filter or browse groups.

• Group Types – Choose which types of groups to display.
• Member Group Types – (New in v1.2, optional) Choose group types whose active members should be shown on the map. Leave blank to show no members. See Showing Group Members on the Map below before turning this on.
• Data View – (Optional) Limit the groups to those in a Group data view. The groups must still belong to one of the selected Group Types.
• Item Cache Duration – How long, in seconds, the group data is cached before refreshing. Defaults to 3600 (1 hour). Caching is recommended to keep the page loading quickly.
• Show Keyword Filter – Displays a keyword search box for filtering groups. Defaults to Yes.
• Show Address Filter (Map Only) – Shows an address box. Entering an address moves the map to that location so people can see nearby groups; it doesn't remove any groups from the results. Defaults to No.
• Show Campus Filter – Displays a campus dropdown to filter groups by campus. Defaults to Yes.
• Enable Campus Context – If the page has a campus context, use it as the campus filter. Requires Show Campus Filter. Defaults to No.
• Campus Types to Include – Limits the campus filter to specific campus types.
• Campus Filter Behaviour – How groups are filtered when a campus is selected:
  • Campus on Group – Groups whose campus is the selected campus (default).
  • Distance – Groups within the Distance from Campus setting of the selected campus.
  • None – The campus is used to position the map but no groups are filtered out.
• Distance from Campus – The radius in miles used when Campus Filter Behaviour is Distance.
• Show Meeting Day Filter – Lets people filter by the day a group meets. Defaults to Yes.
• Show Meeting Time Filter – Lets people filter by the time of day a group meets. Defaults to Yes.
• Attribute Filters – Add extra filters based on your own group attributes. Enter the attribute key and the caption to show (for example: AgeGroup and Age Group). Field types such as Defined Value, Single Select, Day of Week, and Yes/No work well.
• Person Role Filters – Add a text box that filters groups by the name of a person in a specific role. Enter the role name and the caption to show (for example: Leader and Leader Name). Any group with a person in that role whose name contains the text entered is shown.
• View Options – How groups can be displayed:
  • Map – Map view only.
  • List – List view only.
  • Both (with Toggle) – Both views with a button to switch between them (default).
  • Both (at Same Time) – The map and list shown together.
• Default View – Which view loads first: List (default) or Map.
• Filter to Use – When View Options is Both (at Same Time), which set of filters to show: the Map filters or the List filters.
• Show Group Count – Displays the number of groups that match the selected filters. Defaults to Yes.
• Show Filter Criteria – Shows a summary of the filters currently applied. Defaults to Yes.
• Register Page – The page people are sent to when registering for a group.
• Register Workflow – (Optional) A workflow to launch when someone registers for a group.
• Include Full Groups – Whether groups at or over capacity are shown. Defaults to No.

Map Settings

These options control how the map is displayed.

To use the map features, make sure your Rock system has a Google Maps API key entered in the Google API Key global attribute. To look up addresses for the address filter, the Group Finder uses the Google API Key Server global attribute if it's set, and the Google API Key otherwise.

• Map Height – The map's height in pixels. Defaults to 800.
• Map Style – The look of the map. Defaults to Google. (Styles are managed under Admin Tools > Settings > Defined Types > Map Styles.)
• Map Info Window Contents – The Lava shown in the pop-up when someone clicks a group marker. Available merge fields: Group, Location, DayOfWeek, TimeOfDay, LeaderNames, HostNames, Color.
• Group Member Map Info Window Contents – (New in v1.2) The Lava shown in the pop-up when someone clicks a group member marker. Available merge field: Person. Anything this template displays is publicly visible, so only show what you're comfortable sharing.
• Maximum Zoom Level – How close people can zoom in. Defaults to 16 (19 is building level).
• Minimum Zoom Level – How far people can zoom out. 0 shows the whole world.
• Initial Zoom Level – The zoom level when the map first loads, and when a campus is selected. Defaults to 12. A campus with a MapZoomLevel attribute value uses that value instead.
• Map Marker – The marker shape for groups. Defaults to Marker with Dot. (Managed under Admin Tools > Settings > Defined Types > Map Markers.)
• Attribute for Marker Color – The key of a group attribute used to color markers and cards. The attribute must use a defined type whose values have a Color attribute. See Colors below.
• Map Member Marker – (New in v1.2) The marker shape for group members. Defaults to Marker with Dot.
• Default Marker Color – The marker color to use when neither the marker color attribute nor the group type sets one. Defaults to #ee7725.
• Group Member Marker Color – (New in v1.2) The color of group member markers. Defaults to #ee7725.
• Cluster Color – The color of clusters of nearby markers. Defaults to #999999.
• Location Precision Level – How close each group's marker is placed to its actual address: Precise (default), Narrow, Close, or Wide. Use a less precise level if you'd rather not show a host's exact address. Group member markers are never shown more precisely than Close. If several markers land on the same spot, they're offset slightly so each can be seen.
• Campus Marker – The marker shape for campuses. Leave blank to hide campus markers.
• Center on Campus – By default the map is zoomed to show all campuses and groups. Select a campus here to center the initial view on that campus instead.

Templates

These settings control the layout and styling of the Group Finder. If you want to customize a Lava template, copy it first, then make your changes to the copy. Any future updates to the plugin will overwrite changes made to the original Lava files.

• Pass Current Person to Lava – Makes the logged-in person available as CurrentPerson in the Group Detail Lava Template, for personalization. Defaults to No. (The group cards are cached and shared by everyone, so they only get the current person when Item Cache Duration is 0.)
• Main Lava Template – The main layout that builds the page, including the filters, map, list, and group count.
• Group Summary Lava Template – How each group appears in the list view (the group cards).
• Group Detail Lava Template – The detailed view shown when someone clicks Learn More or a map marker.
• CSS File – The path to the style sheet, if you want to adjust colors, fonts, or other design elements. Defaults to the plugin's own style sheet.

Showing Group Members on the Map

New in v1.2. The Group Finder can also show individual group members on the map, for example so people can see others from their church who live nearby. This is turned off by default.

To turn it on:

1. In Member Group Types, choose the group types whose members should appear.
2. Optionally set Map Member Marker and Group Member Marker Color so members look different from groups.
3. Optionally set Group Member Map Info Window Contents to control what appears when someone clicks a member.

Privacy: member information is shown to anyone who can view the page, including people who aren't logged in. Before turning this on, make sure your church is comfortable with that and that the members involved have agreed. To protect members:

• Only active members of active groups are shown.
• Each marker shows the member's nickname and last initial.
• Member locations are never shown more precisely than Close, even if Location Precision Level is set to Precise or Narrow, so a marker can't be traced to a specific house.
• Members without a mapped home address aren't included.

Member markers are hidden whenever a filter is applied (other than the address filter), because the filters only apply to groups. To hide members on a particular page, add ?includeMembers=false to the page's URL.

Final Touches

Adding Filters

You can add filters to your Group Finder to help people narrow down and find the right group. These might include things like topic of study, group type (like Women's, Men's, or Singles), or even a filter to show which groups offer childcare.

To add filters, first define them on the Group Type in the Group Attributes section.

Then in the Group Finder block settings under General > Attribute Filters, add your attribute key and the caption to show.

Linking to Pre-Filtered Results

You can link to the Group Finder with filters already applied by adding them to the page's URL:

• hc-campus – a campus Id
• hc-dow – a meeting day (0 = Sunday through 6 = Saturday)
• hc-tod – a meeting time, such as 7:00 PM
• hc-keywords – keywords, separated by commas
• hc-address – an address to center the map on
• An attribute filter's key, with the value to filter on
• A person role filter's role name, with the name to search for

For example: /page/123?hc-campus=1&hc-dow=3.

Colors

Map Pinpoints

Group markers use the first color that's set, in this order:

1. The color from the group attribute named in Attribute for Marker Color.
2. The group's Group Type Color (in the Display Options section of the Group Type).
3. The block's Default Marker Color.

If your map includes more than one Group Type, each group type's markers can have their own color.

Category Colors

By default, cards in the Group Finder display the color set on the Group Type. To enhance visual appeal and improve the user experience, you may want to assign distinct colors to different categories or subjects.

1. Create a Defined Type for the category where you want to apply color. Be sure to add a Color attribute to it, using the key Color.

2. In the Group Type settings, under Group Attributes, add an attribute that uses the Defined Type you created. For example, you might add a Type of Group attribute that references your Types of Group defined values.

3. In the Group Finder block, go to the Map Settings section and set Attribute for Marker Color to the key of the group attribute you created.

You'll now see the colors applied on the cards and map markers.

Caching

The Group Finder caches its group data for the Item Cache Duration (1 hour by default) to keep the page fast. Saving the block's settings clears that block's cache right away. Changes made to groups themselves, such as a new group, a new meeting time, or a color change, appear once the cache expires. To see them sooner:

• Use the Clear Cache option on the page, or
• Run the Refresh Group Finder Cache job from Rock's Jobs Administration page. It clears and reloads the cache for every Group Finder block.

The plugin installs the Refresh Group Finder Cache job set to run every hour. Keep its schedule in line with the block's Item Cache Duration. For example, with the default of 3600 seconds, run it hourly. That way the cache is rebuilt in the background and visitors don't have to wait for it.

Troubleshooting

• Map not loading – Make sure a valid Google API Key is set and that a Map Style is selected. If problems continue, check the browser console for error messages.
• Address filter not working – Check that the Google API Key Server global attribute (or, if that's blank, the Google API Key) is set and has the Geocoding API enabled in Google Cloud.
• Filters not showing – Confirm that filters such as Keyword or Campus are turned on, and double-check the key and caption for any custom attribute filters.
• No groups found – Verify the Group Types and Data View, and that each group has a valid location for the map view.
• Changes not showing – The group data is cached. See Caching above.
• Group members not showing – Check that Member Group Types is set, that the members have a mapped home address, and that no filters are applied.
• Details or form not working – Ensure a Register Page or Register Workflow is set up correctly. Look for errors when loading group details.
• Styling issues – Confirm the path to the CSS file is correct and inspect page elements using your browser's developer tools.

Support

If you need help installing the Group Finder or would like customization, please reach out using our Contact Us form.