CustomSalsa is a bundle of utilities for enhancing pages from Salsa Labs' Cosm product. It mostly consists of a large JavaScript object, called customSalsa, along with some basic CSS.
This code is highly experimental at this point and not recommended for live sites. It's more of a public sandbox at the moment.
If you're feeling brave, feel free to clone/fork and play around. You'll need an environment that supports Grunt and Compass in order to do much.
Use the grunt commands (watch/css/js) to compile CSS and minify JS as needed.
js.src/customSalsa.js is where the guts live. Basically, that file creates an singleton JS object customSalsa that in turn loads v1.11.2 of jQuery as the object jQ (rather than the more-familiar $ or jQuery). This prevents collisions of problems with the ancient (1.3.2) version of jQuery that Salsa automatically loads.
Once customSalsa is instantiated, use main.js to start invoking various methods that will do various and interesting things to your Salsa pages. See main.js for a very basic example.
So basically: include js.dist/library.js in your template, then edit to your own needs and include js.dist/main.js as well. For styling, add your own version of css/style.css to your template as well, compiling it from the sass files.
This is a rough overview of the methods and properties of the customSalsa object that is created.
This contains a large number of values customSalsa consults in the course of doing various things; overwrite these stock values to change the defaults.
A full enumeration of all the settings and their uses is forthcoming. Eventually.
This is essentially a private object that stores various state changes so that various one-time methods aren't repeatedly invoked by accident.
Method that loads jQuery and maps it to jQ. This method is called at the end of the file.
This implements a number of custom jQuery event triggers on document in response to Salsa's built-in AJAX calls (most of which are a part of the advocacy module). Use these to trigger your own custom jQuery reactions to Salsa events.
Lifted from cosm-body-classes, this method adds a css class (or two) to the <body> element based on the kind of page it detects is being rendered. This provides a great way to target CSS to particular page types: make donation form inputs look one way, and advocacy forms another!
This adds CSS classes checked or unchecked to <label> elements that are tied to radio buttons. Useful for styling: you can hide your radio button s entirely and style up your labels to look like buttons themselves! Pretty cool. See it in action at [...]
Salsa's forms don't include the wonderful HTML5 placeholder attribute. While we could add one (and maybe we will add that to customSalsa eventually), one elegant workaround is to style and position the labels so they look and act like placeholders. This method invokes the show/hide behavior; SASS is forthcoming to style & position them (or write your own!)
When using placeholderLabels, it looks weird to have <select> elements with labels showing. This hides them.
Method that adds a smattering of CSS classes to Salsa's markup to facilitate styling. Needs more work still.
Whoever built Cosm wasn't very diligent about remembering to include the type="text" attribute on various inputs, which can be super-annoying when trying to style different kinds of s differently. This helps by adding it. Note that it's not state-aware; if a new input is added to the DOM via AJAX you'll need to reset customSalsa.status.addMissingInputTypes and call this again. We should probably improve this...
Private method used by other methods to determine what counts as "valid" for a given input.
Private method used by other methods to validate an individual field's value based on its contents and type.
Why wait for Salsa to make its AJAX calls before alerting users to missing/incomplete information? Do it on form submit with this!
Private helper method for the above.
It's 2015. Users shouldn't have to manually identify their credit card type: If they're entered a valid number, it's easy to determine the type. Hide the usual Salsa type stuff and call this on donation form submit. Less work for users!
Private method that runs user-inputted credit card number through the Luhn checksum. Doesn't guarantee a number is valid, but helps suss out blatantly invalid ones.
Like the above, but for bank routing numbers. Per Brainjar.com.
Performs a Luhn check on the credit card number as well as checking the length/format of the CVV to make sure it corresponds to the card type.
Checks that all required fields are valid, payment info is good, etc. on a donation form. Call this on form submit so your users don't have to wait for Salsa's response! (Note: doesn't check everything quite yet)
If you're using the makeMultistep method (see below), this method validates a particular 'step' before users can move on to the next one.
Checks that all required fields are valid, payment info is good, etc. on a donation form. Call this on form submit so your users don't have to wait for Salsa's response! (Note: doesn't check everything quite yet)
This gargantuan method (which itself contains many other methods) can be called to transform a regular donation form into a fancy, beautiful multi-step donation form a la the Obama campaign. Best when used with the SASS multistep partial. COMPLETELY UNTESTED in this context; this is code that was written as a standalone system and recently folded into this project — there may be bad function calls and whatnot that still need to be resolved.
Implements a lightbox on the donation form that will prompt for a recurring gift if the user opts to give a single gift when initially submitting the form. Highly configurable and proven to increase giving, but may not work in all situations (currently under refinement). Make sure you've got _lightbox.sass compiled into your CSS or this will be a disaster.
Helper method for the lightbox, will push events into Google Analytics based on user interactions with the lightbox. Will also update Donation_Tracking_Code input field in Salsa.
Basically a wrapper around several other methods that improve CSS targeting, which in turn helps facilitate better mobile responsiveness. Best in combination with _mobilizr.sass.
Changes the input type of some form fields from 'text' to more HTML5-appropriate values (e.g. 'email') to facilitate user input on touch devices.