Before you begin...
Gather the following information. You'll need it to customize the signup form.
||Yes||The hostname where data will be submitted. Click here to learn more about the
||Yes||The unique identifier that Salsa assigns to your organization. Click here to learn how to retrieve the
||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.|
|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.|
|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.
Basic signup form
|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/>|
|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" />|
Line 1sets the form's
actionto use the standard Salsa
/save controllerto save the contents of the form.
Line 2contains your
organization_KEYgoes between the quotation marks in the
Line 3contains your
chapter_KEYif you are in a chapter. The
chapter_KEYgoes between the quotation marks in the
valueparameter. If you are not in a chapter, then do not include this line.
Line 4contains the
email_trigger_KEYof 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 5tells the save controller to make modifications to the
Line 6sets the
Receive Emailfield for new supporter to "Imported or unknown". This value allows you to send email blasts to the new supporter..
Lines 7-9specify the fields of the
supporterrecord 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-11contain 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-13is 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:
linkKey. The link parameter always contains "groups". The linkKey parameter contains the groups_KEY for the group where you want the supporter added.
Line 14is 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 15contains the URL of the page that the new supporter will see after the form is submitted.
Here are some steps you can use to copy the form to your website.
- Click here to see the page where the sample forms lives.
- Click on the
Rawbutton after the page appears.
- A window will open that contains just the solution.
- Copy the contents of the window and close it.
- Paste the copied text into the configuration tool for your website.
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.
- View the signup page.
- Copy the contents of the address bar. The copied text is the signup page URL.
- Remove "&okay=true" if it appears in the URL.
- Return to the embedded signup form.
- Replace "https://API_HOST/save" in line 2 with your signup page URL. Make sure that the URL is inside the quotation marks.
- Remove the the
redirectfield (all of line 17).
- This would be a good time to save the embedded form.
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:
<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">
<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.
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.
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:
- Locate the
</form>tag in the external form.
- Add an empty line just after the
- Click here to see the page where the script lives.
- When the page appears, click the
- A window will appear that contains just the script.
- Copy the contents of the window and close it.
- Paste the copied text into the empty line just after the
Do this once for each group
Use these steps for each of the groups that you gathered in the "Before you begin" topic (above).
- Copy this text:
<input type="checkbox" id="GROUPS_KEY" name="GROUPS_KEY"/> <label for="GROUPS_KEY">GROUP_NAME</label>
- Add an empty line where you want the optional groups to appear in your signup page.
- Paste the copied text into the empty line.
groups_KEYfor the optional group that you're adding.
GROUP_NAMEto 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.
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:
- Change the
organization_KEYto be a negative value. For example, if you organization_KEY is
12345, then the form needs to have
- Change the
- Create an autoresponse as shown in the confirmed (double) opt-in page documentation. Put the
email_trigger_KEYfor the new autoresponse into the
email_blast_KEYSfield. For example, the
email_trigger_KEYfor the autoresponse is
98765in 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
has an action key of
- Locate the
- Insert a blank line just before the
- Copy these two lines.
<input name="link" value="action"/> <input name="linkKey" value="12345"/>
- Paste the copied text in the newly inserted line in the form.
12345with the action key you retrieved from the petition.
- This might be a good time to save the form.
This technique only applies to petitions. If you want to have supporters sign up to a targeted action, then please use an iframe instead.
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 firstname.lastname@example.org and we'll be glad to help.
If you have any questions, then please gather this information.
chapter_KEYif you are in a chapter
- The URL of the page that contains the signup form.
- A screenshot, if possible.
Send this information to email@example.com, and we'll be glad to help.