In This Article:

    Embed a signup form in your website

    In This Article:

      This section shows how to embed a signup from in your website.  A new supporter that uses this form is automatically added to your supporter database in Salsa.
       
      If you need a technically simpler solution, read about embedding forms via an iframe

      Before you begin...

      Gather  the following information. You'll need it to customize the signup form.

      Item Required? Description
      API_HOST Yes The hostname where data will be submitted. Click here to learn more about the API_HOST for your organization.
      organization_KEY Yes The unique identifier that Salsa assigns to your organization. Click here to learn how to retrieve the organization_KEY .
      chapter_KEY No The unique chapter identifier that Salsa assigns to your chapter. This field is only required if your credentials are only valid in a chapter. Click here to learn how retrieve the chapter_KEY.
      groups_KEY No The groups_KEY s of groups that the supporter will be added to as part of registration. Please click here to learn how to retrieve the groups_KEY based on a group name.
      tag or tags No The tag(s) values to assign to supporters as part of registration. Click here to learn more about groups and tags in Salsa.
      email_trigger_KEY(s) No The email_trigger_KEY(s) for autoresponse(s) that the new supporter will receive after registering. Click here to learn more about autoresponses and triggered emails.
      Redirect URL Recommended The URL of the page that the new supporter will see after they are signed up.

       

      This table shows the values used in the examples.

      Field Value
      organization_KEY 5881
      chapter_KEY 887
      groups_KEY 13
      tag excellent
      email_trigger_KEYs 12644 and 12655


      Basic signup form

      Line Content
      1 <form action="https://API_HOST/save" method="POST">
      2 <input type="hidden" name="organization_KEY" value="5881"/>
      3 <input type="hidden" name="chapter_KEY" value="887"/>
      4 <input type="hidden" name="email_trigger_KEYS" value="12644,12656"/>
      5 <input type="hidden" name="object" value="supporter"/>
      6 <input type="hidden" name="Receive_Email" value="1"/>
      7 <label for="first_name">First Name:</label><input type="text" id="first_name" name="First_Name"/><br/>
      8 <label for="last_name">Last Name:</label><input type="text" id="last_name" name="Last_Name"/><br/>
      9 <label for="email">Email:</label><input type="text" id="email" name="Email"/><br/>
      10 <style>.memberCode{display:none;}>/style>
      11 <div class="memberCode"> Optional Member Code <input name="first_name_949" value=""/></div>
      12 <input type="hidden" name="link" value="groups"/>
      13 <input type="hidden" name="linkKey" value="13"/>
      14 <input type="hidden" name="tag" value="excellent"/>
      15 <input type="hidden" name="redirect" value="http://YOUR URL"/>
      16 <input type="Submit" value="Sign up" />
      17 </form>

       

      Line-by-line-description

      • Line 1 sets the form's action to use the standard Salsa /save controller to save the contents of the form.
      • Line 2 contains your organization_KEY. The organization_KEY goes between the quotation marks in the value parameter. 
      • Line 3  contains your chapter_KEY if you are in a chapter. The chapter_KEY goes between the quotation marks in the value parameter. If you are not in a chapter, then do not include this line.
      • Line 4 contains the email_trigger_KEY of the autoresponse you would like to attach to this form. The autoresponse is automatically sent to the new supporter when the form is submitted.  If you are sending more than one triggered email, then separate the email_trigger_KEYs with commas and no spaces.
      • Line 5 tells the save controller to make modifications to the supporter database.
      • Line 6 sets the Receive Email field for new supporter to "Imported or unknown".  This value allows you to send email blasts to the new supporter..
      • Lines 7-9 specify the fields of the supporter record that you'd like to save.  This form collects three pieces of information: First Name, Last Name and Email.  A full list of all fields can be found here.
      • Lines 10-11 contain the "spam catcher". The spam catcher has been very effective in stopping bad guys from stuffing unwanted ("spam") supporters into our client databases.  We strongly recommend it.  Click here to learn more about spam catchers.
      • Lines 12-13 is an example of adding a supporter to a group automatically.  In this example, a new supporter is added to the group with key 13. Notice that each group requires two hidden input fields: link and linkKey. The link parameter always contains "groups".  The linkKey parameter contains the groups_KEY for the group where you want the supporter added.
      • Line 14 is an optional line that contains a tag for supporters that use your form.  This line is optional. Tags and groups together can be very helpful for learning more about your supporters.
      • Line 15 contains the URL of the page that the new supporter will see after the form is submitted.
      Getting a copy of the form

      Here are some steps you can use to copy the form to your website.

      1. Click here to see the page where the sample forms lives.
      2. Click on the Raw button after the page appears.
      3. A window will open that contains just the solution.
      4. Copy the contents of the window and close it.
      5. Paste the copied text into the configuration tool for your website.
      Modify the pasted form using the previous sections, then test!

      A note about the spam catcher

      The spam catcher is invisible to users, but is visible to automated systems. An automated system will generally fill in a value for that field.  It has a tasty looking name and is an input field.  

      If the spam catcher is filled in, then Salsa immediately and silently throws away the data from that supporter. The spam catcher is only visible to the bot or software that bad guys use.  If it's filled in,then it's clear that the record is not one that you want.

      This technique has proven to be quite effective in reducing spam submissions, and Salsa strongly recommends having a spam catcher in any public-facing form.

      Note: Some screen readers for the visually-impaired will also show this field, which is why an innocuous description (Optional Member Code, in this case) is included. This can be any text you would find suitable for screen readers.

      Forward to a signup page

      Sometimes, a signup form on your website is a good starting point, but you really need the information in the that form to go to a Salsa signup page.  For example, you'd like to have a full address, or a phone number, or ask the new supporter about their interests.

      The best way to do all of these things is to create a signup page that collects the information that you need.  The embedded signup form can then send the supporter to the signup page when the form is submitted.

      Begin by creating a signup form using the first parts of this article.  Next, modify the form to pass the collected information to your signup page.  Here are some steps that you can use.

      1. View the signup page.
      2. Copy the contents of the address bar. The copied text is the signup page URL.
      3. Remove "&okay=true" if it appears in the URL.
      4. Return to the embedded signup form.
      5. Replace "https://API_HOST/save" in line 2 with your signup page URL.  Make sure that the URL is inside the quotation marks.
      6. Remove the the redirect field (all of line 17).
      7. This would be a good time to save the embedded form.
      When the supporter clicks on the submit button, Salsa will send the information in your form to the signup page, ready for the new supporter to complete with the information that you need.

      Forward to a donation page

      A signup form can be used to collect supporter fields and an amount, then forward that to a donation page.  Start by using the first part of this article to create a signup page will all of the fields that you'd like to forward to the donation page.  Next, modify the form to include this anywhere before the </form> tag:

      <label for="amount">Amount:</label>
      <input type="text" id="amount" name="amount" value="50.00"/>

      Note that "50.00" is a suggested amount.  It's not required, and you can remove it if you'd like to have a blank amount field in your form.

      Next, change the action from this

      <form action="API_HOST/save" method="POST">

       to this

      <form action="THE_URL_OF_YOUR_DONATION_PAGE" method="POST">
      

      and remove the redirect field (Line 17).

      The URL of your donation page appears in the browser's address bar when you are viewing the donation page. When the supporter clicks on the submit button, Salsa will send the information in your form to the donation page.  All of the information that's filled in on the embedded form is automatically passed to the donation page.

      If you'd like the passed amount to click one of the amount radio buttons on your donation page, then please click here for an idea about how to do that.

      Required groups

      The signup form described at the top of the page automatically adds supporters to a single group (See lines 12 and 13). Adding a supporter to a group requires two lines of code.

      <input type="hidden" name="key" value="groups"/>
      <input type="hidden name="linkKey" value="GROUPS_KEY"/>

      where "GROUPS_KEY" is the key for the group. Click here to learn how to retrieve a groups_KEY.

      It's important that both lines appear for each group.  For example, if you want to automatically add new supporters to three groups, then the two lines need to appear three times -- once for each group.

      Optional groups

      The signup form described at the top of the page automatically adds supporters to a single group. A signup page can also be configured to allow a supporter to choose groups by clicking on checkboxes, much as optional groups are handled on Salsa pages. Here are some steps that you can use:

      Before you begin

      Make a list of the optional groups that you'd like to present to users.  You'll need the groups_KEY and the group name.  Please click here to learn how to retrieve the groups_KEY based on a group name.

      Do this once for the form

      Optional groups need a script to make them work properly.  Installation only needs to be done once for per form.  Here are some steps to use:

      1. Locate the </form> tag in the external form.
      2. Add an empty line just after the </form> tag.
      3. Click here to see the page where the script lives.
      4. When the page appears, click the Raw button.
      5. A window will appear that contains just the script.
      6. Copy the contents of the window and close it.
      7. Paste the copied text into the empty line just after the </form> tag.

      Do this once for each group

      Use these steps for each of the groups that you gathered in the "Before you begin" topic (above).

      1. Copy this text:
      <input type="checkbox" id="GROUPS_KEY" name="GROUPS_KEY"/>
      <label for="GROUPS_KEY">GROUP_NAME</label>
      1. Add an empty line where you want the optional groups to appear in your signup page.
      2. Paste the copied text into the empty line.
      3. Change GROUPS_KEY to the groups_KEY for the optional group that you're adding.
      4. Change GROUP_NAME to the group name for the optional group that you're adding.

      Once all of the optional groups are added, then that would be a good time to save the contents of the form and test.

      Confirmed opt-in

      A signup form can be used to register supporters and require them to click on a link to actually opt-in.  This process is known as "Confirmed Opt-In" or "Double Opt-In".   You can learn more about confirmed opt-ins by clicking here.  When that page opens, look for the header named "Options".

      A confirmed opt-in signup form has the same structure as the example (above).  There are three changes that must be made to make the standard signup form into a confirmed opt-in form:

      1. Change the organization_KEY to be a negative value. For example, if you organization_KEY is 12345, then the form needs to have -12345.
      2. Change the Receive_Email to 10.
      3. Create an autoresponse as shown in the confirmed (double) opt-in page documentation. Put the email_trigger_KEY for the new autoresponse into the email_blast_KEYS field. For example, the email_trigger_KEY for the autoresponse is 98765 in the example that follows.

      Once these three changes are in place, then the embedded signup form is equipped to add supporters via a confirmed opt-in.  Kudos to Ziggy West Jeffry at Truthout for this great idea.

      Submit a petition

      A signup form can be used to submit a petition. A supporter simply provides the contents of the signup form. The supporter is automatically added to the signature list for the petition.

      Before you begin...

      View the petition and retrieve the action KEY. The action key appears in the browser's address bar after action_KEY=. For example, a URL that contains

      action_KEY=12345

      has an action key of 12345.

      Installation steps

      1. Locate the </form> tag.
      2. Insert a blank line just before the </form> tag.
      3. Copy these two lines.
      <input name="link" value="action"/>
      <input name="linkKey" value="12345"/>
      1. Paste the copied text in the newly inserted line in the form.
      2. Change 12345 with the action key you retrieved from the petition.
      3. This might be a good time to save the form.
      Important note.  Please read now!

      This technique only applies to petitions.  If you want to have supporters sign up to a targeted action, then please use an iframe instead.

      Required fields

      Salsa does "server-side validation" for required input fields. If a the contents of a required field are empty, then Salsa attempts to return to the same page with error messages. Your server will need to know that error messages can be returned and that they should be displayed.

      Having to figure out Salsa's error code and display them correctly is a total pain. It's also not the best way to do validation. A much better approach is to use client-side validation. "Client-side validation" is a script that checks the contents of the inputs and displays errors if required fields are missing.  The data doesn't get sent to Salsa until all of the required fields are filled in.

      Your best bet will be to get help from the web developers that created your website.  If that's not possible, then send mail to support@salsalabs.com and we'll be glad to help.

      Questions?

      If you have any questions, then please gather this information.

      • Your organization_KEY
      • Your chapter_KEY if you are in a chapter
      • The URL of the page that contains the signup form.
      • A screenshot, if possible.

      Send this information to support@salsalabs.com, and we'll be glad to help.

      Was this article helpful?
      0 out of 0 found this helpful
      Have more questions? Submit a request

      Comments

      0 comments

      Please sign in to leave a comment.