Examples of "PageBuilder APIs" -- Roll your own API!

James Zetlen

We haven't yet developed Open APIs for all of the information you might want to get out of your Convio system. Noah Cooper developed a technique for bridging the gaps where an S tag can do something that APIs can't! A few weeks ago, he described this system in a Community document. I thought we could also have a thread where we share the simple APIs we've developed based on this technique.

The basic idea is the same for all of them: you need information that only an S-tag (or other Convio template tag) can provide, exposed via a RESTful API. Here's one that I just developed for retrieving Donation campaign information:

 ]x::::](]]
     ]x::x]x::
          ]x::
               ]x::
                    {
                         "errorResponse":
                    }
               ::
               ]:title]]x::
                    {
                         "errorResponse":]'."
                              }
                         ]
                    }
               ::
                    {"getDonationCampaignInfoResponse":{"name":]:title]]]],"goal":]:goal]]]],"amountRaised":]:amountRaised]]]]}}
               ]]]]
          ::
               {
                    "errorResponse":
               }
          ]]
     ::
          {
               "errorResponse":]'."
                    }
               ]
          }
     ]]
     ]x:::]]

If you drop that into a PageBuilder page, call it "pbAPI", and publish it, you've got yourself a simple PageBuilder API.

If you call the method using the following GET syntax:

http://www.example.com/site/PageServer?pagename=pbAPI&pgwrap=n&api_key=yourAPIKey&v=1.0&method=getDonationCampaignInfo&campaign_id=1301

You'll get a response:

{"getDonationCampaignInfoResponse":{"name":"General Campaign","goal":"1000000","amountRaised":"573000"}}

The goal and amount raised are in cents, not dollars.

If you use the "callback" feature to return JSONP, then you can use that API like this, on any page--on Convio or off!:

<h2>Campaign Name</h2>
<p id="campaignname"></p>
<h2>Campaign Goal:</h2>
<p id="campaigngoal"></p>
<h2>Amount Raised:</h2>
<p id="campaignamountraised"></p>
<h2><span id="percentraised"></span> raised!</h2><script type="text/javascript" charset="utf-8">
     function parseResponse(json) {
          var parsedJSON = eval(json); // normally an awful idea but the JSON in question here is quite small
          document.getElementById('campaignname').innerHTML = parsedJSON.getDonationCampaignInfoResponse.name;
          document.getElementById('campaigngoal').innerHTML = '$' + (parseInt(parsedJSON.getDonationCampaignInfoResponse.goal)/100);
          document.getElementById('campaignamountraised').innerHTML = '$' + (parseInt(parsedJSON.getDonationCampaignInfoResponse.amountRaised)/100);
          document.getElementById('percentraised').innerHTML = Math.round(parseInt(parsedJSON.getDonationCampaignInfoResponse.amountRaised)/parseInt(parsedJSON.getDonationCampaignInfoResponse.goal)) + '%';
     }
</script>
<script type="text/javascript" charset="utf-8" src="http://www.example.com/site/PageServer?pagename=pbAPI&pgwrap=n&api_key=yourAPIKey&v=1.0&method=getDonationCampaignInfo&campaign_id=1301&callback=parseResponse"></script>

If you understand what's going on above, then you can turn S tags into APIs pretty easy. Does anyone else have any examples or suggestions?

Michael

Doesn't that sort of fly in the face of Convio's conventional thinking on JSONP?

For example, see this thread from a couple years ago:

http://community.customer.convio.com/message/2378

Noah Cooper

Michael :

Doesn't that sort of fly in the face of Convio's conventional thinking on JSONP?

For example, see this thread from a couple years ago:

http://community.customer.convio.com/message/2378

Michael,

I think the difference here is that you wouldn't use this to expose sensitive constituent data, only non-sensitive data like the name and amount raised for a donation form.

James Zetlen

Michael :

Doesn't that sort of fly in the face of Convio's conventional thinking on JSONP?

For example, see this thread from a couple years ago:

http://community.customer.convio.com/message/2378

That's why I chose the S15 tag, since it doesn't reveal sensitive information about either constituents or finances. The JSONP policy explained by Dave Hart pertains to those systems that our Engineers had exposed as APIs at that point. Currently, this JSONP hack is for S tags that aren't exposed as APIs yet. As we develop more (and more innocuous) API methods, we could use JSONP for those, too, but you've gotta use your best judgment about what information to expose.

Noah Cooper

Here's an example that I just worked on for the Humane Society Legislative Fund:

http://action.humanesociety.org/site/TR?fr_id=1080&pg=entry

The organization is using TeamRaiser to allow constituents to host parties on its behalf. As part of the TeamRaiser signup process, team captains (party hosts) are asked three questions:

1) The location of their party

2) Whether or not they want to show the team roster (the party's guest list) on their team page

3) Whether or not they want their team to show up in search results

The attached code is used in a PageBuilder page to render the team captain's response to each of these questions as jsonp. jQuery is used on the team page to display the location from question #1 under the team name and to hide the team roster if the captain answered "No" on question #2:

<script type="text/javascript">
     $(function(){
          $.each($('td.tr_captain'),function(){
               if($(this).html().indexOf('px=')!=-1){
                    var teamCaptainConsID=$(this).html().split('px=').split('&');
                    $.getJSON('PageServer?pagename=teamCaptainPartyResponse&fr_id=]&teamCaptainConsID='+teamCaptainConsID+'&pgwrap=n&callback=?',function(data){
                         $.each(data.captains,function(){
                              if(this.location&&this.location!=''){
                                   //Location is not null
                                   $('p.cstmTitle').html($('p.cstmTitle').html()+'<br />'+
                                   '<span class="teamCaptainLocation">'+this.location.replace(new RegExp('\\\\n','g'),'<br />')+'</span>');
                              }
                              else if(this.participationTypeId=='1121'){
                                   //Virtual Host
                                   $('p.cstmTitle').html($('p.cstmTitle').html()+'<br />'+
                                   '<span class="teamCaptainLocation">Virtual Host</span>');
                              }
                              if(this.showTeamRoster&&this.showTeamRoster=='No'){
                                   //Hide team roster
                                   $('table.tr_roster').css('display','none');
                                   $('table.tr_legend').css('display','none');
                              }
                         });
                    });
               }
          });
     });
</script>

On the search page, each of the teams returned on the results page are checked, and if the captain answered "No" to #3, the team is hidden:

<script type="text/javascript">
     $(function(){
          $('table.lc_Table').css('display','none');
          var pbUrl='PageServer?pagename=teamCaptainPartyResponse&fr_id='+$('#fr_id').val()+'&pgwrap=n&callback=?';
          var i=1;
          $.each($('div.lc_Text p a'),function(){
               var teamCaptainConsID=$(this).attr('href').split('px=').split('&');
               $(this).attr('id','teamCaptain-'+teamCaptainConsID);
               if(i==1)
                    pbUrl+='&teamCaptainConsID='+teamCaptainConsID;
               else
                    pbUrl+='&teamCaptainConsID'+i+'='+teamCaptainConsID;
               i=i+1;
          });
          $.getJSON(pbUrl,function(data){
               $.each(data.captains,function(){
                    if(this.showTeamInSearchResults&&this.showTeamInSearchResults=='No'){
                         //Hide team row in search results
                         $('a#teamCaptain-'+this.teamCaptainConsID).parent().parent().parent().parent().css('display','none');
                    }
               });
               $('table.lc_Table').css('display','');
          });
     });
</script>

Adrian Cotter

Noah Cooper:

Here's an example that I just worked on for the Humane Society Legislative Fund:

http://action.humanesociety.org/site/TR?fr_id=1080&pg=entry

The organization is using TeamRaiser to allow constituents to host parties on its behalf. As part of the TeamRaiser signup process, team captains (party hosts) are asked three questions:

1) The location of their party

2) Whether or not they want to show the team roster (the party's guest list) on their team page

3) Whether or not they want their team to show up in search results

The attached code is used in a PageBuilder page to render the team captain's response to each of these questions as jsonp. jQuery is used on the team page to display the location from question #1 under the team name and to hide the team roster if the captain answered "No" on question #2:

<script type="text/javascript">
     $(function(){
          $.each($('td.tr_captain'),function(){
               if($(this).html().indexOf('px=')!=-1){
                    var teamCaptainConsID=$(this).html().split('px=').split('&');
                    $.getJSON('PageServer?pagename=teamCaptainPartyResponse&fr_id=]&teamCaptainConsID='+teamCaptainConsID+'&pgwrap=n&callback=?',function(data){
                         $.each(data.captains,function(){
                              if(this.location&&this.location!=''){
                                   //Location is not null
                                   $('p.cstmTitle').html($('p.cstmTitle').html()+'<br />'+
                                   '<span class="teamCaptainLocation">'+this.location.replace(new RegExp('\\\\n','g'),'<br />')+'</span>');
                              }
                              else if(this.participationTypeId=='1121'){
                                   //Virtual Host
                                   $('p.cstmTitle').html($('p.cstmTitle').html()+'<br />'+
                                   '<span class="teamCaptainLocation">Virtual Host</span>');
                              }
                              if(this.showTeamRoster&&this.showTeamRoster=='No'){
                                   //Hide team roster
                                   $('table.tr_roster').css('display','none');
                                   $('table.tr_legend').css('display','none');
                              }
                         });
                    });
               }
          });
     });
</script>

On the search page, each of the teams returned on the results page are checked, and if the captain answered "No" to #3, the team is hidden:

<script type="text/javascript">
     $(function(){
          $('table.lc_Table').css('display','none');
          var pbUrl='PageServer?pagename=teamCaptainPartyResponse&fr_id='+$('#fr_id').val()+'&pgwrap=n&callback=?';
          var i=1;
          $.each($('div.lc_Text p a'),function(){
               var teamCaptainConsID=$(this).attr('href').split('px=').split('&');
               $(this).attr('id','teamCaptain-'+teamCaptainConsID);
               if(i==1)
                    pbUrl+='&teamCaptainConsID='+teamCaptainConsID;
               else
                    pbUrl+='&teamCaptainConsID'+i+'='+teamCaptainConsID;
               i=i+1;
          });
          $.getJSON(pbUrl,function(data){
               $.each(data.captains,function(){
                    if(this.showTeamInSearchResults&&this.showTeamInSearchResults=='No'){
                         //Hide team row in search results
                         $('a#teamCaptain-'+this.teamCaptainConsID).parent().parent().parent().parent().css('display','none');
                    }
               });
               $('table.lc_Table').css('display','');
          });
     });
</script>

This is a neat little hack, thanks for sharing.

Is the pgwrap=n parameter new? I think there were various times where I was hoping to find a way to do that... deliver a page without its wrapper.