Compass now provides your organization with the ability to add a Find-a-Workshop search directly in your website!  With just a few lines of code (described below) added to your site, potential participants can search for workshops and directly register without ever leaving your site!  

  1. Before You Begin
  2. Installation
  3. Pre-populate Participant Information
  4. Customizing the look and feel

mceclip0.png


Before You Begin

Please note that this will embed a large table and search box on your site.  Please make sure you place it in an area of your site that allows for a wide container (preferably 1200px).

An example of the complete installation can be found here: https://www.compasshp.org/find-a-workshop/index.html.


Installation

First, add the following snippet in the section of your page you would like to display the find-a-workshop.  All of the options available are described below the snippet.

<div id="compass-app"></div>

<script type="text/javascript">
var compass_options = {
owner_api_key: "[YOUR_OWNER_API_KEY]",
partner_api_key: "[YOUR_PARTNER_API_KEY]",
base_url: "https://compasshp.org",
callback_url: "[YOUR_CALLBACK_URL]",
ask_address: true,
history_mode: "hash",
};
</script>

<script type="text/javascript" src="//compasshp.org/find-a-workshop/dist/js/app.js"></script>

Configuration

To configure the Find-a-workshop feature, create a compass_options Javascript object.  You can then use the following properties to customize your installation.

 Attribute Description
owner_api_key

If you are a state organization, overseeing all organizations/partners for your state, this is the unique API key for your entity.  Providing this API key will only list programs and workshops for your organization.

You can locate your owner API key (if available) here: https://compasshp.org/in/api-keys

partner_api_key

If you are an individual organization and want to only list your workshops, you can specify this key.  Providing this API key will only list programs and workshops for your organization.

You can locate your owner API key (if available) here: https://compasshp.org/in/api-keys

base_url

(Optional) If you are testing out the find-a-workshop feature, and wish to point to a different environment other than the live Compass site, you can specify a different base URL.  For instance, you can point at the Compass demo site by specifying "https://dev.compasshp.org" in this option.

We recommend omitting this option before you go live, so you are always pointed at the live Compass site.

callback_url

(Optional) If you wish to have the find-a-workshop feature call a URL on your application once the participant has registered, you can specify that URL here.  The request will contain all of the participant's information that was requested on the Registration form, along with several additional elements:

  • id - The ID of the participant in Compass
  • organization_participant_id - The ID that was optionally passed in from the find-a-workshop search that links your organization's participant record to ours.
  • workshop_id: The Workshop ID from Compass
  • workshop_name: The name of the workshop (which includes the program name).
ask_address

(Optional) Set this to false if you do not want to ask for the participant's address.

Default value is true.

require_address

(Optional) Set this to false if you do not want to require the participant's address.

Default value is true if ask_address is set to true.

registration_message

(Optional) If you would like to display a message to potential participants, such as how their information is used, you can specify it in this field.  HTML is allowed in this parameter.  The default location of the message is at the top of the registration form, but can be placed underneath by setting the registration_message_position (described below).

registration_message_position

(Optional) If you are displaying a registration message (described above), you can specify either top or bottom in the registration_message_position parameter to place this message above or below the registration form.  

Default value is top.

history_mode

(Optional) There are 2 ways of browsing the find a workshop: hash and history

  • hash - default - Using hash will append all URLs in the find-a-workshop with a # sign when users are browsing the find a workshop.  For instance, when users perform a search, the URL bar will be appended with something like:

    http://www.yoursite.com/find-a-workshop#zipCode=1234&programId=22
    http://www.yoursite.com/find-a-workshop#/registration/3022.  

    Using this method means that you won't need to account for additional URLs on your server.
  • history - For advanced users - If you choose history mode, you will need to account for any sub-directories/URLs on your server when users are browsing your site.  When users are browsing the find-a-workshop on your site, URLs will appear in the following format:

    http://www.yoursite.com/find-a-workshop?zipCode=1234&programId=22
    http://www.yoursite.com/find-a-workshop/registration/3022

    In order for this method to work, you will need to add a wildcard catch-all on your server so that every portion of your URL after your default find-a-workshop link will automatically load the find-a-workshop page.  

Pre-populate Participant Information

If you are using a system that already has the participant's information in a database, you can prepopulate the registration form with the participant's contact information, so that your user does not need to manually enter that data. 

<!-- Amend your compass_options object -->
<script type="text/javascript">
var compass_options = {
owner_api_key: "[YOUR_OWNER_API_KEY]",
partner_api_key: "[YOUR_PARTNER_API_KEY]",
history_mode: "hash",

participant: {
organization_participant_id: "12345677ABCDEFG",
first_name: "Michael",
last_name: "Smith",
phone_number: "5188888888",
email: "mike.smith@somewhere.com",
send_email: false,
self_register: true,
address: {
address: "123 Main Street",
city: "Albany",
state: "NY",
zip: 12210
}
}
};
</script>

Configuration

If you are using the Find-a-Workshop feature in a system that already manages participants, you can add a participant object to the compass_options object, and populate it with the fields defined below.

 Attribute Description
organization_participant_id

If you wish to link the participant to your system, please specify your unique ID for the participant in this field.  Letters, numbers, and some special characters are allowed.

first_name

The first name of the participant.

last_name

The last name of the participant.

phone_number

10-digit phone number.  Numbers only!

email

E-mail address.  Required if you want to send a registration e-mail to the participant.

send_email

If an e-mail is provided, and this is set to true, a registration e-mail will be sent to the participant when they register.

self_register

Toggle true if the participant is registering for themselves.

address.address

The participant's street address.

address.city

The participant's city.

address.state

The participant's state (2 character state code!).

address.zip The 5-digit zip code for the participant.

Customizing the look and feel

The theme of the find a workshop search is based off of Bootstrap 3.  All of the styles associated with the theme are wrapped with the #compass-app element ID.  You can override any parts of the theme by adding CSS that customizes Bootstrap's theme.  For instance, to change the color of the buttons, you can apply CSS like so:

<style type="text/css">
 #compass-app .btn.btn-primary {
background-color: #204d74;
border-color: #122b40;
}
#compass-app .btn.btn-info {
background-color: #269abc;
border-color: #1b6d85;
}
#compass-app .btn.btn-danger {
background-color: #269abc;
border-color: #1b6d85;
}
</style>

All of the styles can be overridden by simply wrapping your CSS declaration with #compass-app.  Just inspect the element, find the CSS class, and customize away!