Custom Handlers

Custom handlers are custom Blackbaud Internet Solutions components that allow you to manage the REST (Representational State Transfer) model of web requests and responses for your website. The REST model defines the underlying concept that just by specifying a URL, you can get a response that is appropriate for a task.

You store custom handlers as classes on your web server, and they receive unique URLs but are not associated with web pages or web services. With custom handlers, you can write REST-based custom code to handle custom requests and responses for your website. These custom handlers can access data from your Blackbaud CRM back office as well as data from your website. This allows you to make data requests from other programs and to return data in response to data requests

Write a Custom Handler

To create a custom handler, you write a class that inherits from BBNCExtensions.CustomHandlers.CustomHandler. You need to override the ProcessRequest sub that receives the ASP.NET HttpContext for the request. The context contains the Request and Response objects.

You use the Request object to inspect the request, looking for query string parameters or posted form fields that your handler may expect. You use the Response object to write out a response.

Just like custom parts, custom handlers have an API property to access the things exposed in the API. This allows handlers to access RSS feeds, documents, part data, and much more.

Since you have a reference to BBNCExtensions, you can call Custom Web Methods that you can write for the RE7Service, where you have access to Blackbaud Internet Solutions.

Call a Custom Handler

You compile your project and deploy it to the \NetCommunity\bin folder of your installation directory. The URL for the custom handler uses the following format: http://{your site}/components/custom.ashx?handler={your assemblyName.typeName} To pass parameters to the handler, place them at the end of the URL: http://{your site}/components/custom.ashx?handler={your assemblyName.typeName}&foo=bar

The handler code can inspect the Context.Request.QueryString ("foo") item to get the value (“bar”). Consumers of your handler can also post form elements to your handler, in which case you look to Context.Request.Form ("foo") for that value.

You can also create a part to supply the response to your the custom handler. For example, you can create a custom part with a text box on the part editor to allow you to edit the content for the response. You can use the API to get the content from the custom part because all custom handlers have access to the API. Here is a simple example:

'locate the FBML part that holds the fbml to return
Dim oPart As FBMLContent

oPart = Me.API.Parts.LoadCustomContentFromPartId(_
  CInt(context.Request.QueryString("partid")), GetType(FBMLContent))
 
If oPart IsNot Nothing Then
  sResponse = oPart.FBML

In the sample code, an FBML custom part stores an FBMLContent object as its content. The handler supports a Query String parameter called partId to identify the particular instance of the custom FBML part get. So if the part ID is 616, the URL to call the handler would be: http://blackbaud.org/netcommunity/components/custom.ashx?handler=facebooksample.getfbml&partid=616.