# Welcome to Formjoy

Thanks for trying out FormJoy! We're excited to help you create effective, user-friendly surveys that integrate with your NationBuilder website and database.

See the following guide to FormJoy's tools and features, and let us know if you have any questions at <support@formjoy.com>


# Create an account

You can create a FormJoy account at at <https://www.formjoy.com/users/sign_up> by filling in your personal details and your nation slug.

If you've been invited to your organisation's existing FormJoy account by a colleague, then just click the 'Accept invitation' button in the invite email you receive from <support@formjoy.com>. This will direct you to a sign up form to enter your personal details.


# Enable FormJoy on your site

Once you've created your FormJoy account, you'll need to edit your website's theme to support FormJoy custom features and functionality. To do this, follow the instructions at <https://www.formjoy.com/setup>.&#x20;

If you have any questions about these steps, don't hesitate to contact us at <support@formjoy.com>


# Choose a plan and add payment details

You can select your subscription type and enter your payment details at <https://www.formjoy.com/subscription>

You can also change your plan type at <https://www.formjoy.com/subscription/edit>.


# Add users to your account

To invite your colleagues to your FormJoy account:

1. Navigate to <https://www.formjoy.com/accounts>
2. Click on the name of your account.&#x20;
3. Click "Invite A User"
4. Enter your colleague's name and email, and click "Send invitation". This will trigger an email to them with a link to create their account.

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI2IK7u8RWMLt2F-51I%2FScreen%20Shot%202020-09-25%20at%201.25.15%20PM.png?alt=media\&token=7f11ce55-d6c9-4cbc-92da-3db0d1f41b49)

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI2IqOSGdpdzPN7gzVa%2FScreen%20Shot%202020-09-25%20at%201.29.29%20PM.png?alt=media\&token=1bb93ef0-90bd-4030-9377-e3aeb17cb637)


# Create a survey

You will create your survey pages in NationBuilder, just as you normally would, though you will add a lot of additional features/functionality in FormJoy. To create a new survey page:

1. In your website's backend, click "New page".&#x20;
2. Give your new page a name and slug, click "Show all page types" and select "Survey" from the list of options
3. Navigate to your new page's Survey Settings > Basic. Under 'Survey', either connect this page to an existing NationBuilder survey, or click the "Create a new survey" button to connect a brand new survey.
4. Open your new survey page in your web browser, and you'll see your one-page FormJoy survey already displaying!

For more guidance on creating NationBuilder surveys and survey pages, see <https://support.nationbuilder.com/en/articles/2306373-create-a-survey>


# Add multi-select questions

Native NationBuilder surveys allow for multiple choice questions, but they only allow your supporters to select *one* answer from a list. In contrast, FormJoy enables you to create multiselect questions, to which your supporters can give multiple responses, e.g.:

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI12J9vA9YXbAO_GwEq%2F-MI1rEHJTPwswNP2sUez%2FScreen%20Shot%202020-09-25%20at%2011.23.44%20AM.png?alt=media\&token=e1e5ed21-cf36-43e6-ba56-9f08ebf52597)

To add a multiselect question to your survey:

1. In your NationBuilder backend, navigate to People > Surveys and click on your survey.&#x20;
2. Click New question, and **give your question a slug that includes the word`"multiselect"`**&#x20;
3. Enter your question text, select the "Multiple choice" question format, and click "Save survey question"
4. You will then be directed to the "Possible responses" tab - enter as many response options as you'd like. Note that you can also tag supporters based on their responses to these questions

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI12J9vA9YXbAO_GwEq%2F-MI1puyr7AOX9Xg_I25S%2FScreen%20Shot%202020-09-25%20at%2011.18.47%20AM.png?alt=media\&token=95afddb6-6e7b-484a-8178-da723e8c6795)


# Set a limit on multi-select options

Use custom javascript to limit users to their top e.g. 5 options

If you want to limit people's selections to a multi-select question, you can do so following the instructions below:

1. Go to your Survey Pages screen at <https://www.formjoy.com/survey_pages>
2. Click 'Edit settings' for the relevant survey
3. In the Custom JavaScript section, add the code provided below, with a few updates:
   1. Set the maxCheckboxes variable to whatever limit you want to place (e.g. 5)
   2. Replace QUESTION\_SLUG on line 4, with the checkbox question slug from your NationBuilder survey

{% code overflow="wrap" lineNumbers="true" %}

```javascript
// Set max checkbox limit
$(function () {
  var maxCheckboxes = 5;
  var checkboxes = $('.checkbox-group[data-question-slug="QUESTION_SLUG"] .form-checkbox');

  checkboxes.on('change', function (evt) {
    var checkedCheckboxes = checkboxes.filter(":checked");
    if (checkedCheckboxes.length > maxCheckboxes) {
      this.checked = false;
      alert("Please select a maximum of " + maxCheckboxes + " options.");
    }
  });
});
```

{% endcode %}

If you wanted to do this for multiple checkboxes, you would need to duplicate rows 3-12 of the code above, and update the variable names of:

1. maxCheckboxes
2. checkboxes
3. checkedCheckboxes

I.e. if you had a multiselect question asking people their preferred news sources, and another asking them their most important policy issues, your code might look like the below. You would again need to replace NEWS\_QUESTION\_SLUG and ISSUES\_QUESTION\_SLUG with the relevant question slugs:

{% code overflow="wrap" lineNumbers="true" %}

```javascript
$(function () {
  // Set News checkbox limit
  var maxSelectedNews = 5;
  var checkboxesNews = $('.checkbox-group[data-question-slug="NEWS_QUESTION_SLUG"] .form-checkbox');

  checkboxesNews.on('change', function (evt) {
    var checkedCheckboxesNews = checkboxesNews.filter(":checked");
    if (checkedCheckboxesNews.length > maxSelectedNews) {
      this.checked = false;
      alert("You can only select up to " + maxSelectedNews + " options.");
    }
  });

  // Set Issues checkbox limit
  var maxSelectedIssues = 5;
  var checkboxesIssues = $('.checkbox-group[data-question-slug="ISSUES_QUESTION_SLUG"] .form-checkbox');

  checkboxesIssues.on('change', function (evt) {
    var checkedCheckboxesIssues = checkboxesIssues.filter(":checked");
    if (checkedCheckboxesIssues.length > maxSelectedIssues) {
      this.checked = false;
      alert("You can only select up to " + maxSelectedIssues + " options.");
    }
  });
});
```

{% endcode %}


# Add checkboxes

To create a checkbox (e.g. "Check this box to confirm you accept our terms and conditions"), just create a multiple choice question with only one possible response, as in the screenshot below:

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI12J9vA9YXbAO_GwEq%2F-MI1sU-Ml-p6Lrp9CQpt%2FScreen%20Shot%202020-09-25%20at%2011.30.11%20AM.png?alt=media\&token=9b79917c-f133-454f-acfb-5ec979962ab4)

If you'd like to make your checkbox compulsory, you can add some custom logic through our Javascript editor - see the separate page with guidance on that below.


# Edit your survey settings in FormJoy

While you can create your survey and add some question types in NationBuilder, you will need to use FormJoy to enable some features and functionality. To do this, just:

1. Navigate to <https://www.formjoy.com/survey_pages>, and log in if you haven't already.&#x20;
2. Click the pencil-and-pad icon to the right of your survey (edit settings)

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI28dSQfkFjF7j_uN1v%2FEdit%20survey.png?alt=media\&token=632d7ef1-22bc-454d-b983-7c3284ae87c6)

This will enable you to use many of the custom features laid out in the pages below.


# Set your autoresponder email

NationBuilder surveys have traditionally been the only action page that doesn't allow you to send an autoresponder to supporters. It's often critical you're able to thank each respondent for sharing their thoughts and let them know other ways to support your efforts. **You can now do that easily with FormJoy.**\
\
To configure an autoresponder for a survey, simply click the edit option next to the survey where it appears in the main list within your account: <https://www.formjoy.com/survey_pages>. See the guidance on editing your survey settings in FormJoy, for instructions on navigating to the settings page.

You can then customise the sender details as well as the autoresponder subject line and email body, including support for key variables (e.g. first\_name).

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI2FhHXTQRvI6Omh8JA%2FScreen%20Shot%202020-09-25%20at%201.16.00%20PM.png?alt=media\&token=d8ce146b-c776-414a-9140-d978d311e9f7)


# Set up notification emails and landing page

You can now configure notification emails and landing page for all your survey pages! Simply click the edit link for a survey page and enter the email(s) where a notification should be sent every time a survey response is submitted, and the page that supporters should be directed to once they complete the survey. See the guidance above on editing your survey settings in FormJoy, for instructions on navigating to the settings page.\
\
The notification emails include:

* the supporter's name, email and NationBuilder profile link
* all the supporter's answers to the survey questions

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI2DPhwsJtElFCd_S0x%2FScreen%20Shot%202020-09-25%20at%201.05.30%20PM.png?alt=media\&token=9ae5c002-af4f-483c-a0dd-c954d41ec6c5)


# Add custom styling (CSS) and logic (Javascript)

You can now customise your surveys to exactly match your website design and apply any additional styles you need. Simply navigate to the edit page for your survey and enter your styles through our modern code editor. See the guidance on editing your survey settings in FormJoy, for instructions on navigating to the settings page.

It's also possible to add custom scripts to your survey pages so you can **apply form logic to hide/show fields depending on other responses**, set minimum and maximum lengths for text fields, make certain questions compulsory and/or **display feedback messages and other content depending on which options are selected** in multiple choice fields.

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI2FUrJR_mK6MejlmUb%2FScreen%20Shot%202020-09-25%20at%201.14.45%20PM.png?alt=media\&token=dddcd23a-0982-4a78-b2e2-672c07277b41)

<br>


# Make question required

To do this, you will need to add some custom code to FormJoy's in-built javascript editor. See the page above for instructions on how to access this tool.&#x20;

Then, for any question type except for multiselect checkboxes, add this code to the Javascript editor:

$("\[data-question-slug='`QUESTION_SLUG`']").prop("required", true);

Just replace `QUESTION_SLUG` above with the slug of your question - keep all of the inverted commas and brackets. See the below example to make a question with slug `text_question_2` required.

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI90U7PUn9c4Yecvwx7%2F-MI90aUvHoMm4Uznl7qI%2FScreen%20Shot%202020-09-26%20at%208.47.20%20PM.png?alt=media\&token=66f7ff20-9ad5-4129-b16d-3b2777887307)


# Add native NB fields (e.g. address, mobile)

You can capture the exact supporter data you need by selecting which NationBuilder fields to include in your surveys. This is perfect for asking supporters to provide their postcode or other address information, or for requesting additional details relevant to your community, including employer, role, or website.\
\
To collect extra data in your surveys, simply navigate to <https://www.formjoy.com/survey_pages>, and click the third Action icon on the right of your survey (edit fields):

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI2BMgkOn6UN2DCFBIw%2FEdit%20fields.png?alt=media\&token=76bc7cce-64bb-4281-9635-133edf67dfc1)

Then click "Add Extra Field" and select any NationBuilder data field from the dropdown:

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MI25jreXWcEOy1YXPrf%2F-MI2CH4RGmFpciuZFz0I%2FScreen%20Shot%202020-09-25%20at%2012.59.02%20PM.png?alt=media\&token=7672298f-3ea4-4c3c-b6d7-b35791b78139)


# View and export all survey responses

You can easily view all of the responses to your survey in one place. From your [Survey Pages screen](https://www.formjoy.com/survey_pages), just click the fourth Action icon for the survey you are interested in (see screenshot below). You'll then be taken to that survey's responses page, which includes each supporter's full details for easy reference when viewing their answers.

![](https://56006180-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-MI11dITk91hmGgkKYdT%2F-MLwBY6whx0vSM88sa7t%2F-MLwD25GYvxXxKYaJn17%2FView%20all%20responses.png?alt=media\&token=9f19e402-f390-44ef-8c73-739714bb67b6)

From this page, you can also export all of the survey's responses, by clicking the Export Responses button.


# New features

We're constantly updating and improving the FormJoy toolset - keep an eye on <https://www.formjoy.com/announcements> for info on new features!


# Is it possible to have ranked responses?

We’re eager to add new question types in future but 'ranking questions' (ie that ask people to order their preferences from 1 - 5) are not currently supported.


# How many surveys can I create?

All plans offers unlimited surveys, responses and users.


# Will setting up FormJoy break my existing surveys?

Happily, the answer is no! The new system will apply to all existing survey pages once it’s published theme-wide (so they’ll all continue to work, just with the new system rather than the old), with the exception of pages that have a custom page template.

If you are testing out FormJoy on a new survey but also have existing surveys live on your NationBuilder site, you have two options:

1. **Apply the changes suggested theme-wide (as per the setup instructions)**. If you do this it will update all existing surveys to use the FormJoy integration (e.g. so all questions will start to appear in a single form), and those surveys will all continue to work seamlessly. This would apply the FormJoy integration to all existing surveys except for any that have custom page templates, which would remain unchanged.
2. **Specifically apply the changes suggested to a single test survey by creating a custom page template for that new test survey.** Once you create a custom page template for your new test survey you can simply replace all the code in that existing page template with the code here: <https://gist.github.com/coreyaus/7a6368684599faec51c1e3e02c2d65bf>. The `pages_show_survey.html` version will display the form alongside the content whereas the `pages_show_survey_wide.html` version will show the survey form directly below the page content (it's up to you which one you'd prefer to use). If you would like a hand with this then we can help set up an example test survey for you (we would just need admin access to your nation).&#x20;


# How are the notification emails implemented?

The notification emails to admins are sent from <support@formjoy.com> so that domain is all configured with the necessary sender authentication and SPF records.&#x20;

However, the autoresponders are sent from the email address specified by you We can definitely help you complete the sender authentication process so your domain/subdomain is verified for email delivery through the FormJoy SendGrid account. That process isn’t yet visible through the FormJoy interface but it’s an easy thing we can configure for each organisation to maximise the email deliverability of their autoresponders.