Motivation

A common customization scenario we hear about is performing an action after a user donates. When a donation comes in you may want to alert someone, update a report, or log the donation to a 3^rd party system. The most obvious way to do this is by writing a custom donation form with the NetCommunity API, but that’s an awful lot of work just to tack something onto the end of the donation process. In this article I’ll show you an easy way to take action after a constituent donates online. We’ll be relying on the custom confirmation screen feature of the donation form, but all the techniques will work with the event and membership forms as well.

Technique

To perform an action after a donation, we need to answer two questions:

1.       How do we know a user has just donated? The URL of the donation form doesn’t change after a completed donation.

2.       How do we access the transaction data? To do anything interesting after a donation, we will need some information about the transaction. The amount donated, for instance.

The answers are to be found in custom confirmation screens. Custom confirmation screens let you design the page (using the NetCommunity WYSIWYG editor and merge fields) that shows after a donation. You have complete control over the markup. We’re going to take advantage of that to introduce some special markup that will make it easy for JavaScript to read values from the confirmation screen. Then we can determine if we are on a confirmation screen and get any relevant transaction values.

Enough talk. Let’s code.

Simple Example

First, I’ll create a donation form with a really simple custom confirmation screen. Here’s the HTML for my screen (I’ve abbreviated the merge field markup for readability):

<div>

 <img src=”...” (Individual.Begin Section)>

</div>

<div>

 Name:<span class="TSName"><img src="..." (First Name)></span>

</div>

<div>

 <img src="..." (Individual.End Section)>

</div>

<div>

 Amount:<span class="TSAmount"><img src="..." (Gift Amount)></span>

</div>

This just displays the first name of the donor and the amount of the donation. If you look carefully though, I’ve added a “class” attribute to the span tags that hold the merge fields. jQuery loves class attributes, and makes it super easy to get data from elements with unique classes. If you feel more comfortable using document.GetElementById, then by all means give the span tags an Id attribute.

Now that we have our custom confirmation screen all set to go, we have to write some script to parse it. Create a new formatted text and images part, switch to HTML mode and enter this script:

<script type=”text/javascript”>

function AfterDonation() {

       if ($(".TSName").length > 0) {

              fname = $(".TSName).children(":first").text();

              alert("Thanks " + fname + "!");

       }

}

$(document).ready(

    function() {

        Sys.WebForms.PageRequestManager.getInstance().add_endRequest(AfterDonation);

    }

);

</script>

 

Technical Note

The NetCommunity donation form uses an asp.net UpdatePanel when processing a donation. The sys.webforms… line of code tells asp.net to fire the AfterDonation function whenever the updatepanel completes an update. The AfterDonation function checks to make sure it is actually on a confirmation screen by verifying that our custom confirmation screen markup is present, and then fires off the alert. We need to verify that it is actually a confirmation screen because the update panel could update with a validation message instead of a successful donation, which would cause the AfterDonation function to fire, but in that case we are not actually on a confirmation screen. Finally, to get the Name value out of the confirmation screen, we select the span element containing the merge field, and then get the value of the next child span tag. This is because merge fields render as span tags, so we wind up with another span tag inside the original span tag that we decorated with the class name.

 

 

Disclaimer: This script is a bit "fragile". If we decided at some point to change how merge fields are rendered, then this will stop working. The way merge fields render has remained the same for a long time and, while we don't anticipate changing them, this is not a 100% future-proof solution. As always, test all mission critical site functionality before upgrading.

 

Now that we have the technique down, we can use it for all kind of cool things. Here are two examples.

 

Example 1 – Google eCommerce Integration

(note: This code has only been tested in BBNC version 6.10)

About Google Analytics & eCommerce

Google eCommerce is an advanced set of tools inside Google Analytics that gives deep insight into the behavior of your visitors and some really handy reports and metrics about your monetization efforts. Digging into all the features of Google eCommerce tracking and how to use them is beyond the scope of this footnote, but for those of you who have a handle on the basic functionality in GA, I definitely encourage you to explore the eCommerce features. Here’s a link to get you started: http://www.epikone.com/blog/2008/06/25/google-analytics-e-commerce-tracking-pt-3-why-everyone-should-use-it/

 

I use this script in my site tracking box to send data over to Google eCommerce (See Footnote #2 for information about Google Analytics' eCommerce features) after a user has donated. The new parts are in red, the rest is the default Google Analytics code that you probably have in your site tracking box already:

<script type="text/javascript">

var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");

document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));

</script>

<script type="text/javascript">

function GetValue(className) {

       val = $("." + className).children(":first").text();

      

       //if there are any currency symbols, strip them out. GA doesn't like them.

       m = /^"$|"£|"€/g;

       return val.replace(m, "");

}

try {

       var pageTracker = _gat._getTracker("UA-4094862-3");

       pageTracker._trackPageview(BBNCAnalyticsURL);

       if ($(".TSConfirmation").length > 0) {

              //Generate a fake order ID, thanks to http://www.epikone.com

              var d = new Date;

              var unixTime = parseInt(d.getTime / 1000);

              var orderID = pageTracker._visitCode() + '-' + unixTime;

             

              //Only Order ID and Total are required

              //Feel free to track more information if you want

              pageTracker._addTrans(

                  orderID,                       // Order ID

                  "",                            // Affiliation

                  GetValue("TSAmount"),          // Total

                  "",                            // Tax

                  "",                            // Shipping

                  "",                            // City

                  "",                         // State

                  ""                             // Country

               );

               

               pageTracker._addItem(

                  orderID,                        // Order ID

                  "",                             // SKU

                  "",                             // Product Name

                  "",                             // Category

                  GetValue("TSAmount"),           // Price

                  "1"                             // Quantity

               );

               pageTracker._trackTrans();

       }

} catch(err) {}</script>

This is really just the code that Google provides for eCommerce integration (See: http://www.google.com/support/analytics/bin/answer.py?hl=en&answer=55528). All I did was rip some values out of the confirmation screen. I also wrote a bit of code to generate a unique order ID and a function to get a merge field value and remove any currency symbols. NetCommunity already takes care of firing the tracking code after a donation form update, so this is all I had to do. You can easily pull some other data points off the confirmation screen to fill out other values you find useful in your reports. Easy!

 

Example 2 – Twitter Updates

(note: This code has only been tested in BBNC version 6.10)

What would a sample be without Twitter integration? Here’s a custom part that I’ve named TweetStream that sends an alert to Twitter whenever someone donates, using the 3^rd party TweetSharp library. You can use this part to generate a live feed of donations as they come in. Here’s a screenshot of an integrated Twitter account after a few donations (you can see this live at http://www.twitter.com/DemoOrg):

 

 

And here’s the editor for the part:

 

Once you’ve download and installed the part (don’t forget to put TweetStream.js in your Client"Scripts folder!), create a new TweetStream part, fill out the settings, and place it on a page with a donation form. The part is invisible, but will detect a completed donation and update the Twitter account you specified in the editor. The code is heavily commented and should be easy to understand and expand. This is a little different than previous examples because it actually makes an Ajax request (via the asp.net ICallBackHandler, though you could use any Ajax technique you like) back to the server after the donation, and the Twitter update is performed server side. From the server you could update a database, call out to a 3^rd party system (as I did here) or perform analysis on transactions as they come in. Now that’s really powerful!

That’s it for today! I hope you’ll find some awesome new uses for this technique!

Google Analytics in NetCommunity Demystified

A Little Background

Why do I need to web analytics?

Trying to run a successful web site without analytics is like writing a novel by putting alphabet soup in a blender. You know what’s going in, but have no way to control what’s coming out. I believe that good, actionable web analytics are as important as your marketing copy and site design, and represent the biggest opportunity to make money and generate leads online. Web analytics help you turn an opaque and faceless stream of online visitors into a fascinating source of insight and action.

Why Google Analytics (GA)?

GA is powerful, free, constantly adding new features, and supported by a large, stable company. It integrates well with Google AdWords for organizations who are interested in running a online ad campaign. NetCommunity’s analytics integration has been designed with GA in mind. It will work with most any analytics solution, but going forward NetCommunity will include more and more first-class hooks into Google Analytics.

            How does GA track my site?

After signing up for GA, you are given a piece of Javascript code and told to put it on every page of your site. The script runs every time someone views a page, and sends Google information about that visitor like:
                - How did this person get to your site?
                - Where is the visitor, geographically?
                - What URL is the visitor looking at? (n.b. this makes the URL very important)
Based on just that information you can learn an incredible amount about how your site is performing and what your visitors are doing.

Setting up Google Analytics in NetCommunity

Signing up

Go to http://www.google.com/analytics and sign up for an account (it’s painless, I promise). When you finish the sign-up you will be presented with your tracking script. Save it somewhere (though you can always find it again on the GA site).

Configuring GA

           

This will let you see what your users are searching for inside NetCommunity. It will pick up queries from both the Search Part and the Quicksearch Part.

Configuring NetCommunity

Go the Administration->System Options, and scroll down to “Enable Site Tracking”. Check the box and copy-paste the code GA gave you into the site tracking script box. Now, we have some slightly different instructions depending on which version of NetCommunity you are using:

                 5.6 – You’re done!

Save.

Whoa, whoa, whoa, what was that? Why are things different between the two versions? Good question! Allow me to digress into a…

Soul-Crushing Technical Discussion (TM)

GA tracks visitors by examining the URLs a person visits while on your site. This can cause a bit of confusion is complex web applications. Here’s an example - let’s say you have a donation form at URL http://MyOrg.com/page.aspx?pid=100. When a visitor makes a donation and sees the confirmation screen, the URL doesn’t change. GA has no way to distinguish between users who actually donated and users who just viewed the donation form and then did something else. That’s a pretty big problem! How can you measure the effectiveness of your site if you can’t even track how many people donated? Similar problems exist for the Event Registration Form and the Membership Form.

NetCommunity’s solution is to build up a special URL for consumption by GA. This URL has extra analytics goodness on it to help you make sense of your data. For example when someone views that donation form, the URL that gets sent to GA looks like:

Page.aspx?DonationStep_51=DonationStep_Checkout&pagename=Donate&pid=100

And when a visitor completes a donation the URL looks like this:

Page.aspx?DonationStep_51=DonationStep_Acknowledgement&pagename=Donate&pid=100

Voilà! You can distinguish between people who did and did not donate. There is some extra information in there as well, like the part ID # of the donation form (51) and a human-readable page name. Any information that was originally present on the URL is also sent over.

What changed between version 5.6 and version 6.10 is how NetCommunity sends this special URL to the analytics service. In 5.6 NetCommunity built an invisible iFrame on each page containing your tracking code and pointed the iFrame to the special URL. The tracking code would see the URL of the iFrame and send it over to GA. This worked ok, except for one major problem – GA lost all referrer information. If someone clicked through to your site from a blog, there was no way to know because the tracking script got loaded in an iFrame which always had a URL referrer of the host NetCommunity page. Referrer information is extremely important when analyzing traffic because it allows you to place value on you marketing, PR, and advertising efforts.

In version 6.10, NetCommunity eliminated the iFrame and put the tracking code into the main page. NetCommunity then writes a Javascript variable called “BBNCAnalyticsURL” to every page. You can tell the GA code to use a URL other than the one in the address bar by passing the new URL into the trackPageView() method as instructed for 6.10 users above. Now we have the best of both worlds. The tracking code is running in the correct page, we get extra information on the URL, and we have our referrers intact.

Looking at the Data

Setting up Goals in GA

Tracking conversions in GA is done by setting up Goals. Goals are triggered when someone completes an action on your site. I’ll quickly show you how to set up a goal for a completed donation. You can set up different goals of your own, and with some clever Javascript you can even track things that NetCommunity doesn’t build into its special URL by modifying the BBNCAnalyticsURL variable.

            

All BBNC donation confirmation pages will contain the value “DonationStep_Acknowledgement” and by using the Regular Expression Match Type, any URLs that contain that value will count as a completed goal. You can look through the NetCommunity documentation to see how the URLs are built for different part types.

Where to go from here

Digging deep into GA and generating actionable metrics is well beyond the scope of this document, but here are a few resources to get you started:

1.       Avinash Kaushik’s Blog – Avinash is one of the real analytics gurus out there and has a great archive of blog posts explaining the ins and outs of web analysis.

2.       CopyBlogger – Fantastic advice for converting traffic, optimizing landing pages, and writing copy that generates results.

3.       Conversion Room – Tips for conversion written by the Google Analytics team.

4.       Conversion University – A thorough nuts & bolts guide to GA written by the Google team.

5.       Practical eCommerce – Blogs and articles to help get value from your visitors. Many articles are applicable to nonprofits as well as ecommerce sites.

Up Next

          eCommerce in GA

I’m going to write another article showing you how to set up the eCommerce features of GA and integrate them into NetCommunity. Even if you aren’t selling anything or soliciting donations the ecommerce reports in GA can be powerful tools.

Testing Your Content

I’m going to dig into the Content Comparison part and show you how simple tests can make a big difference in your online revenue. I’ll also look at the testing functionality built into GA.

In this sample we explore the possibilities of creating donations and other payments via the NetCommunity API, by building our own custom giving form. Donations collected through the API become standard donation transactions that get delivered to The Raiser's Edge or Blackbaud eCRM just as if they were captured with the built in BBNC donation form part. This means you can focus on presenting a unique giving experience, yet get all of the built in back office donation integration for free. 

• How to record a donation
• Using gift attributes, including how to get all gift attribute types from RE7
• Selecting a Raiser's Edge Appeal using the CFAPicker Server Control
• Clearing a Credit Card
• Designing and sending a custom email acknowledgement that uses custom merge fields, using the EmailEditor Server Control
• Using jQuery scripts and images from embedded resources

The announcement came in a blog post by Scott Guthrie, a vice president in Microsoft's developer division, who described the library's attraction:

The jQueryScript Custom Part

What would I do with jQuery? 

Example: A Better Weblog Display

• NetCommunity Lab Notes with default weblog display
• NetCommunity Lab Notes using jQuery 

Using the jQueryScript Custom Part

Themes and the NetCommunity Document API

So How Does this Help Our jQuery Story?

1. Upload the theme zip file created on jQuery ThemeRoller site
2. Crack the zip file using the Zip routines in ICSharpCode.SharpZipLib which ships with NetCommunity
3. Add each image file into the Document Library of the users chosing
4. Update the CSS file to use image Urls that reference the document.doc?id=x Urls for each added image
5. Add the modified CSS file to the selected Document Libary

And of course once you've uploaded theme images into a document library your free to use them yourself in other content, which is what I did in my sample jQuery script above, to add the little orange document image  (which I'm also using here!).

Embedded Resources

• Description: Anything you like that helps you keep track of this entry
• Shared Key: A secret key that only you and the incoming system know. This is any string value. A long combination of letters and numbers is a good bet.
• Querystring Parameter names. These are the variable names of the 3 parameters that the other system will be passing in on the URL for the following values
  • Username - plain text username
  • Time - epochtime when the Url was created (the time in number of seconds since Jan 1, 1970)
  • MD5 Hash - MD5 hash of the concatention of Secret key, Username, IP address, and epochseconds
• Expiration - number of seconds after the Time value to expire the Url
• Include IP - check this box if the hash contains the known caller's IP address

Skinning the menu 

Javascript for the menu

 Changing presentation based on a User's role

Accessibility

ScreenShots

5 menus with different skins on the same page:

 

Expanded Menu:

Vertical Menu:

 

Menu Challenges

How NetCommunity Helps

The Menu API

1. API.Navigation.GetMenuXML(MenuPartId) - this version simply returns the XML document as a string, passing in the id of the menu part whose data you want. You would then typically load the document with something like:
   
   

   Dim xmlDoc AsNew XmlDocument

   xmlDoc.LoadXml(Me.API.Navigation.GetMenuXml(MyContent.MenuPartId))

   
   
2. API.Navigation.GetMenuXMLUrl(MenuPartId) - this versions returns a fully qualified URL from your NetCommunity server that will return the XML document. This is very handy if you want to get your menu data from within a Flash or Silverlight menu implementation for example.

Menu XML

• active - meaning the page this item is linked to is the page you are currently on
• target - the name of any target window you specified for this link
• caption - the menu item text
• tooltip - the tooltip you specified
• pageid - the id of the NetCommunity page if this item is linked to an internal page, otherwise 0
• tabid - some internal pages have "tabs" (e.g. login, fundraiser) so you can link directly to the different stages of the certain parts that are on them, like straight to the new user sign up form of the login page.
• url - the fully qualified url to the linked page built for you

That's all there is to it.

Building a Different Menu 

• <ul><li> based - using strictly an html unordered list of anchor tags, creating sub lists where appropriate to keep the hierarchy represented.
• CSS based - the elements are all styled with some crafty CSS.
• No Javascript required
• No dynamic pop-out sub menus
• Graceful down-level rendering for accessible and mobile browsers

Style It

The Current Active Item

.LeftMenu1 .MenuItemActive:link,
.LeftMenu1 .MenuItemActive:visited,
.LeftMenu1 .MenuItemActive:hover,
.LeftMenu1 .MenuItemActive:active{
    color:#fff;
}

.LeftMenu1 li ul .MenuItemActive:link,
.LeftMenu1 li ul .MenuItemActive:visited,
.LeftMenu1 li ul .MenuItemActive:hover,
.LeftMenu1 li ul .MenuItemActive:active
{
    color:#fff;
}

PartSelect and PartEdit Server Controls 

Before we part, we've used two new powerful Server Controls that can be found in the NetCommunity v5.5 API that are worth explaining, The PartSelectButton and the PartEditButton.

 

If you take a look at the Custom Menu part editor you'll see these two buttons:

 

 

• partId
• partName

For the PartEdit button the retValue is a string which is either "SAVE" or "CANCEL", indicating the user's action to close the part editor's dialog.

Summary

Some call it eating your own dog food, but that's a little rough (sorry). We prefer to call it, Drinking our own champagne. Blackbaud Labs has been ported over to run entirely on the soon to be released Blackbaud NetCommunity 5.5.

We are very excited about the numerous benefits we're going to gain from what turned out to be a pretty seamless and enjoyable move.

• Labs was getting bigger. We needed a better way to organize and manage all the articles and documents that we were posting. Hmmm, where could we get a powerful CMS from...?
  
• More people were wanting to post stuff, so we needed an easier way to support contributors, both inside and outside of Blackbaud Product Dev. and even outside the company.
  
• The BBNC team has been working double time to get v5.5 ready and a big part of that release is a massive expansion to the BBNC API. And since Labs is all about things that interest the developer, we needed a way to demonstrate the slew of these new features we've added to the open API. What better way to do that than to see it in action as you read about it?
  

• How we built the Labs site itself. It has some interesting custom parts that are worth a look-see. We're going to share all the code, both as a demonstration of the new API(s) and in case there's something here you'd like to download and use on your site.
• Demonstrations of the various new areas of the API object model
• Building custom donation forms that create built-in donation transactions
• Email Acknowledgments with custom merge data
• Document Management
• Taping into the RSS feeds
• Building your own menus (css based)
• Div/Css based site layouts (labs is layed out this way)
• Creating user accounts and custom login forms
• A cool bread crumb control
• New Server controls in the API for access to selecting pages, parts, and images in your custom part editors
• API Server controls for WYSIWYG html editing and displaying
• and much more

The one RSS feed we had (http://labs.blackbaud.com/rss.xml) has being replaced with multiple new feeds, and since they are BBNC feeds they have different URLs. The old feed will get one more post with links to the new feeds. Info on the new feeds can be found here.

By the way, one cool new feature in 5.5 is that feeds/posts can contain categories so the sorting and filtering of feeds in IE 7 and other browsers kicks in nicely.

That's probably it for now. Have a look around and stay tuned.

“I can pull up by the curb, I can make it on the road goin’ mobile. I can stop in any street, invitin’ people that we meet, goin’ mobile…”  - Pete Townshend

Look around the airport, the restaurant, the movie theatre, or the Laundromat, and it’s hard not to find someone surfing the web on their cell phone. With the arrival of the iPhone, the ubiquitous Blackberry, and the slew of phones now running Windows Mobile (aka Smartphones) this trend will likely continue. So much so that the web’s major content providers are tapping into it. Google, Facebook, ESPN, MSN, Yahoo, and everyone else it seems are now offering their content and online tools to the mobile consumer. In this article we’re going to explore just how easy it is for you to target this growing base of web users with your Blackbaud NetCommunity web site.     Read more...