Saving Data

Saving data to Salsa uses the same API and controllers as our internal DIA form processor. Each call includes a standard controller -- usually the 'save' controller -- as well as parameters to be saved.

You can use controllers either with <form> elements on a web page, or with server to server scripts such as CURL. By default, the standard controllers will redirect the user back to the page they were on. For use with automated systems, or in Ajax calls, XML can be returned by adding a parameter 'xml'. For example, submitting this form through a browser: 

<form action="http://sample.nodeurl.tld/save">
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="Email" value="mytest@email.com"/>
</form>
is identical to making this call with CURL: 
http://sample.nodeurl.tld/save?xml&object=supporter&Email=mytest@email.com
Controllers are also commonly used in Ajax methods to save data in the background while users are navigating the site.

The Flash Object -- Error messages

When using Salsa controllers, it is useful to report back to the user the last error received. For example, if you're submitting a form from a third party site, you may want to include error messages above the form. For example:
To retrieve error messages, use the flashMessageJS.sjs SalsaScript page to return back the last set of error messages. These messages are intended for one submission only, and are cleared when retrieved, and cleared on every new submission.

This example would retrieve flash messages for any submissions to the Sandbox: 

<script type="text/javascript" src="http://sandbox.wiredforchange.com/api/flashMessageJS.sjs"></script>
Note: Individuals with Javascript disabled would not see these error messages. This is a small fraction of individuals, but if that is a concern, you can also use an iframe: 
<iframe src="http://sample.nodeurl.tld/api/flashMessage.sjs"></iframe>

Save

Accessible via the absolute url "/save" on any node, or via the relative url "save" in any package, the Save controller is the most commonly used controller in the system. It takes parameters that specify the object to save, the key to save to (or '0' for a new item), and then a listing of parameters that are saved to that object. It handles all security methods, and redirects once a method has completed. A successfully entry will redirect to the previous page with either the key that you supplied or a new key (?key=123).

Single object insertions

For example: 
<form action="/save">
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="key" value="123"/>
...
</form>

Redirects

You can also specify the a redirect parameter to direct people to a specific page upon successful completion. By default, upon error, the Save controller directs the user back to the original page. 
...
<input type="hidden" name="redirect" value="http://www.mywebsite.org"/>
...

Multi object insertions

You can enter data into more than one table when submitting a form. In our database architecture, supporter information is entered into the supporter table and relational information is entered into tables as follows supporter_relational table. For example supporter group information is stored in a 'supporter_groups' table, similarly supporter custom field information is stored in a table called 'supporter_custom'. If the information you are entering is new: 
....
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="key" value="123"/>
...
<input type="hidden" name="link" value="custom"/>
<input type="hidden" name="linkKey" value="0"/>
....
<input type='checkbox' class='checkbox blockInput' value='1' id='f8' name='BOOL2'  >
<input type=hidden name='BOOL2' value='0'/>
...
Here you would be updating a supporter record and adding custom field information Here is another example where you would be entering supporter group information To add group information: 
<form action="/save">
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="key" value="123"/>
...
<input type="hidden" name="link" value="groups"/>
<input type="hidden" name="linkKey" value="11"/>
....
</form>
The same thing where you are entering information for multiple groups 
<form action="/save">
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="key" value="123"/>
...
<input type="hidden" name="link" value="groups"/>
<input type="hidden" name="linkKey" value="11"/>

<input type="hidden" name="link" value="groups"/>
<input type="hidden" name="linkKey" value="12"/>

<input type="hidden" name="link" value="groups"/>
<input type="hidden" name="linkKey" value="13"/>
....
</form>

Copy

To copy items, the standard Copy controller is provided 
<form action="/copy">
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="key" value="123"/>
....
</form>
This will copy supporter 123 and create a new record with the data from that supporter.

Delete

To delete items, the standard Delete controller is provided For example: 
<form action="/delete">
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="key" value="123"/>
...
</form>
This will delete supporter 123. Please note that this delete is not reversible. The selected object is completely removed from the database and no backup is made. It is essential that you add logic informing the supporter that these removals are final and not undoable.

Email

You can access our tell-a-friend functionality as follows: 
<form action="/email">
<input type="hidden" name="object" value="supporter"/>
<input type="hidden" name="key" value="123"/>
...
  <label><em>F</em>irst Name</label>
  <input title="First Name" type="text" name="First_Name" value="" size="25" />

  <label><em>L</em>ast Name</label>
  <input title="Last Name" type="text" name="Last_Name" value="" size="25" />

  <label><em>E</em>mail</label>
  <input title="Email" type="text" name="Email" value="mysupporter@theirorg.org"
    size="25" />
 
  <label>Subject</label>
  <input size=45 name="subject" value="test subject"/>

  <label>Customize your message</label>
  <textarea rows=6 cols=50 name="content">lorem ipsum</textarea>

  <label>Email: </label>
  <div>use comma, space or semi-colon (, ;) to separate your email addresses</div>
  <textarea id="emails" name="to" cols="30" rows="6"></textarea><

  <input type="hidden" name="tell_a_friend_KEY" value="456"/>

  <input type="Submit" value="Spread the Word!">

</form>

A REST based API query would look like this:

http://sample.nodeurl.tld/email?xml&tell_a_friend_KEY=456&to=myfriend@gmail.com&username=xxx&password=xxx&subject=test&from=me@my.org&content=something else

Change the server URL to match the server that your account is on.