About the Project
Donation Builder is a framework to help organizations showcase their work and seek new members and support for funding their projects. The primary audience for this project is nonprofit organizations with small teams who want a better and quick-to-set-up way to inform potential new members and supporters about their mission and work, as well as easily lead them through the donation process.
Why We Built It this Way
We chose Middleman for the project because we wanted a mostly static site. The Google Drive gem for Middleman provides the ability to easily update the content on the site without touching the code once it's set up, for those elements that are dynamic.
- Fully responsive framework ready to be customized with an organization's visual brand, including images, colors, and fonts
- Ability to load information from Google Spreadsheets, so that non-technical members of your team can update membership levels and benefits, contact information, organization information, social share messages, content to highlight, and more
- Easily integrated with your Google Analytics account
- Ability to hook up to a variety of payment processors, including Dwolla, Givalike, and DonorPerfect, to accept the donations
- Ability to deploy through Amazon Web Services or Heroku
- Chrome, Firefox, Safari, IE9+
- Tested with Browserstack across a variety of devices
To get started, clone down the project repo.
If you don't already have Ruby installed, you need to install it. You need Ruby version 2.1.4, which is specified in the .ruby-version file. One way to manage your Ruby versions is to use rbenv.
You need the Ruby gem bundler. If you need to install the bundler, run:
gem install bundler
Install the necessary gems from the Gemfile by running:
If you've never worked with Middleman before, you can check out the docs here.
Middleman is configured to live reload the project in the browser as changes are made to files. To start up the Middleman server, run:
bundle exec middleman
To build the site, run:
bundle exec middleman build
When Middleman builds, it creates a static file for each file located in the source folder. The build process is configured in config.rb.
Integrating with Google Drive
Donation Builder uses the middleman-google_drive gem to integrate with Google Drive. Configure your Google Docs authentication as detailed in the Setup section.
The project is set up so that the site can be updated and customized through Google Spreadsheets. Use the same setup for your Google Spreadsheets to correctly pull in the info. You can view the spreadsheet setup here.
You can hook up the project to your Google Analytics account to track how people are interacting with the site. In the Google Spreadsheet, you should have an Analytics tab. Look for the column labeled 'google_analytics_id', and enter your Google Analytics ID here. A second column labeled 'google_analytics_domain' is where you should enter your domain.
See this screenshot.
Donation Builder uses Sass to write its styles. In _settings.scss, there are some color variables. The project uses three theme colors, a main theme color, a secondary theme color, and a tertiary theme color. These colors are then applied to the buttons, navigation links, labels, and other UI elements throughout the project to quickly and easily use your organization's colors.
You can customize the site with the fonts your organization already uses. This can also be done in the _settings.scss file. Look for the variables $main-font and $secondary-font. The default main font is 'Roboto' with a sans-serif fallback; the default secondary font is 'Open Sans Condensed', which has another sans-serif font as a fallback.
To switch out most images, you can replace an image in the /source/images folder that corresponds to the image you'd like to change. These images are named in an intuitive manner so that it's clear where each image appears in the project. The images and where they appear are described below in case the names are not clear. If you still aren't sure, try switching out the image and see where it appears in the project.
Your organization's logo appears in the masthead of each page on the site. The logo should be approximately 300px wide and 60px tall. In the source/images/ folder is an image named logo.png. Replace this image with your logo.
You may want to customize the favicon that appears on the browser tab. To do this, replace the image called favicon.ico with your favicon.
You can customize the backgrounds used for the banners at the top of each page with your organization's photos. To set a background for the landing page banner, replace the photo named landing-header-bg.jpg. To set a background for the premium membership page banner, replace the photo named premium-membership-banner.jpg.
In the AboutOrg tab of the Google Spreadsheet, you can set up the summary for your organization, a short tagline, a call-to-action, your organization's name, and the url for your organization.
Contact information letting people know who to contact with questions can also be configured in the Google Spreadsheet, under the Contacts tab. You can set department, name, title, phone, and email for each contact.
You can set up your organization's membership level names, donation amounts and benefits in the Google Spreadsheet. You do this on the MemberLevels tab. See this screenshot.
This field is your membership level name. For example, "Activist" or "Enthusiast".
This is the donation amount that people should give to be at the membership level. Add the amounts without dollar signs. For amounts over 999, include the comma (for example, 1,000).
Set this to TRUE for your most popular membership level, and leave this field blank for all other levels. This activates a "Most Popular" flag when this level is displayed on the landing page and on the membership grid page.
Set this to TRUE for any premium membership levels that your organization offers. This activates a "Premium Member" flag when this level is displayed on the landing page and on the membership grid page. It also tells the project to feature these premium membership levels on the premium membership page.
You can list the benefits for each membership level here. Between each benefit, include <br> to put in a line break. You may also want to include "Plus all above benefits" as one of the benefits in this field.
On both the landing page and the premium membership page, there are four spots provided for you to showcase either images or videos to inform people what their donations will go toward supporting. You set them in the Showcase tab. See this screenshot. To showcase images, enter 'images' in the 'content_type' column, and to showcase videos, enter 'videos' in the 'content_type' column.
If you selected images, upload the images of your choice and name them "image-one.pg" (This is the top featured image), "image-two.png", "image-three.png", and "image-four.png".
If you selected videos, upload the videos of your choice and name them "video-one.pg" (This is the top featured video), "video-two.png", "video-three.png", and "video-four.png". You'll also need to set the Youtube link for your videos in the Showcase tab under "video_one", "video_two", "video_three", and "video_four".
Labels for the images or videos can be set in the spreadsheet with the columns "label_one", "label_two", "label_three", and "label_four".
You can set your page titles, headers, and urls in the Pages tab of the Google Spreadsheet.
You can add more navigation links to the navbar as needed. These links are included in both the desktop nav and the mobile nav. For example, you might want to add a "Quick Donation" link or a link to more information about your organization. Additional nav links can be set up in the NavLinks tab. For each additional nav link, add the URL target and the link text to display. It's recommended that you add only up to three additional nav links so you don't overwhelm the page.
You can set up the links that should appear in the footer in the FooterLinks tab. For each link you'd like to include in the footer, add the URL and the link text to display. Note that the project is configured to hide the footer by default if the device width is 985px or greater. You can change this in the _footer.scss file if you prefer a different behavior here.
You can customize the default messages for when people choose to email, tweet or post to Facebook about donating to your organization. You configure this in Google Spreadsheets on the Social tab. See this screenshot. The Facebook fields set the Open Graph metadata for your site, to ensure Facebook scrapes and displays the information you want when people post.
To set your Facebook share image, you also need to include the image you'd like to use there in the /source/images folder named facebook-share-image.png.
Integrating with a Payment Processor
The project is designed to be able to be integrated with the payment processor that works best for you. It's set up to integrate most fluidly through linking to a form where people can then enter their information and submit their contribution. Some examples of payment processors with which it works well include Givalike, Dwolla and DonorPerfect.
You can set up the links where people should be sent to enter their information and submit their contribution in the DonationInfo tab. See this screenshot. You can set different URLs here for generic contributions and for renewals.
Amazon Web Services
To deploy to AWS, the project uses the middleman-s3_sync gem to push and compile the site to Amazon S3 after building.
By default, in config.rb, config.after_build is set to false. Set this to true. Check that your AWS_ACCESS_KEY and AWS_ACCESS_SECRET environment variables are set, and then run:
bundle exec middleman build
In your terminal, you should see s3_sync applying any updates to the files in the project. You can also check the project S3 bucket to ensure that all files have been synced there. Change config.after_build back to its default of false after deploying.
If you've never used Heroku before, you'll need to create a Heroku account.
Heroku deployment uses config.ru and the Rakefile. For Heroku, you'll need Ruby 2.1.4.
To create your project for Heroku, run
To push the project to Heroku, run
git push heroku master
Rsync, FTP, SFTP and Git
You can use a middleman-deploy gem to deploy the project over Rsync, FTP, SFTP or Git.
The Texas Tribune uses this project for its donations site. You can see it live here and visit the repo here. This should give you a good idea of what's possible with the project and what additional customizations you can add to the project so that it fits your particular needs.
Thank you to Masonry, the digital creative agency we worked with to reach the design for this project.