Quick Start 

This article covers the details of building a basic custom part from scratch. If you haven't already done so, take a look at The Anatomy of a Custom Part to get the idea of what a custom part is and how it is composed. In this installment we are going to step through the creation of a simple one.
 
Recall that a custom part is comprised of two ASP.net user controls, so we are going to use Visual Studio 2008 to build our part. You can use Visual Studio 2005, but make sure you at least have version 3.5 of the ASP.net framework installed if you are building parts for NetCommunity 5.5 or higher. Note: These same steps will apply to creating a custom part for NetCommunity 5.0, but we recommend upgrading to NetCommunity 5.5 as the NetCommunity API has gained considerable power in this later release.
 
So for a given custom part we will create two user controls:
  • Display Control: used for displaying the part on a web page
  • Edit Control: used to edit the part's content

Content can come from a variety of sources. It can be a simple as text or HTML stored in the Blackbaud NetCommunity database or it can come from remote systems such as a constituent’s giving history from The Raiser's Edge, or both. In any case, each part in Blackbaud NetCommunity stores some level of content within the Blackbaud NetCommunity database to define either its actual content or where to get the actual content, as well as any other design options for its display or behavior. So, the Editor Control for a part may offer a place to edit the actual content or just properties for locating remote content, as well as any additional properties for the content. It's completely up to you.

A custom part will also have a code-behind DLL assembly. This is where the part’s executable code lives for all of its associated user controls. This is a common ASP.NET practice.
 
When installing a custom part to the system you will place all of your non-compiled files (.ascx files, images files, .js files, etc.) into the \NetCommunity\Custom folder of your NetCommunity installation. A ggod practice is to create a sub folder below \NetCommunity\Custom for each of your custom parts, for instance \NetCommunity\Custom\MyPart. (Note if there is no “custom” folder in your NetCommunity folder then you need to create one.) All compiled files (e.g. your code behind DLL) and required references (.dll) must be placed in the \NetCommunity\bin folder.

You must then add your custom part to the Custom Parts gallery within the Administration tool of Blackbaud NetCommunity. Your part will then be acknowledged by the system and ready for use.

Create the Part

 
Following are the basic steps for creating a simple Custom Part.
  1. On a machine with Blackbaud NetCommunity installed, create a new ASP.net application using Visual Studio 2008.
  2. Set a reference to the Blackbaud NetCommunity Extensibility library (BBNCExtensions.dll) located in the \bin folder of your Blackbaud NetCommunity installation.
  3. Create two Web User Controls. One for your display control and one for your editor control.
    1. For the Display Control: Set your code-behind class to inherit from BBNCExtensions.Parts.CustomPartDisplayBase
    2. For your Editor Control: Set your code-behind class to inherit from BBNCExtensions.Parts.CustomPartEditorBase
  4. Put some HTML in your display control (e.g. “Hello World”)
  5. Put some HTML in your edit control (e.g. “Hello web designer”)
  6. Build your project

At this point you have a simple custom part that can be installed to Blackbaud NetCommunity. This simple “Hello World” part has no design-time properties or content to edit, store, or retrieve. It just shows some hard-coded HTML.

Deploy the Part 

Deploying our built part to our NetCommunity site is to simple steps:
  1. Copying the files to the appropriate folders on your NetCommunity web server
  2. Telling NetCommunity about your new part

Copying the Files

A typical custom part will consist of two main user controls (.ascx files) and one or more DLL assemblies for your project. Copy the .ascx file into the \Custom folder of the Blackbaud NetCommunity installation, and copy the .dll file(s) into the \bin folder of the NetCommunity installation.

Because you will need to deploy your custom part everytime you recompile it, during development it is a convenient practice is to use Visual Studio Build Events to deploy your parts automatically after every successful recompile. This makes deployment much quicker and less error prone. In our sample we are deploying to a folder located at \NetCommunity\Custom\Hello.   
 
To create Build Events in a Visual Studio project, open the properties sheet for the project you want to deploy. On the Compile tab you'll find the "Build Events" button towards the bottom of the page. Clicking that, then clicking the "Edit Post Build..." on the next dialog, should bring up something like this:
 
 
In the Post Build Event Command Line edit window enter this:
 
copy "$(ProjectDir)*.ascx"  "c:\Program Files\Blackbaud\NetCommunity\Custom\Hello"
copy "$(TargetDir)$(ProjectName).*" "c:\Program Files\Blackbaud\NetCommunity\Bin"
 
Be sure to substitute the destination paths as appropriate for your NetCommunity installation. These commands will copy all of the .ascx user controls from your project to the right spot, in our example, the Hello folder under \custom.  The DLL should always get copied to the \bin folder of your NetCommunity installation. Note the use of $(ProjectName) to make sure we only copy our DLL and not the ones we reference that may be in our \bin folder.
 
As your custom parts get more complex, you could add more commands to handle copying other related files such as images, scripts, and stylesheets.

Telling NetCommunity About Your Custom Part

Once you've deployed your custom part's files you are ready to tell Blackbaud NetCommunity you have a new custom part and where to find its files. This only needs to be done once, unless you decide to move your files to a new location.
 
In the Admin tool of NetCommuninity click the Administration -> Custom Parts menu item to get to something that looks like this:
 
 
 
Click the New Custom Part button to get to this page where we fill out the details for our new custom part:
 
 
 
 The Display Control Source and Edit Control Source are the paths to the .ascx files for your display and edit controls, respectively. Note the use of the ASP.net  "~\"  path syntax to create paths relative to the web application's root directory. These paths should match where you deployed the files to. You do not have to specify the location of your code-behind assembly DLL, as you copied that to the \bin folder and ASP.net is smart enough to find it there.
 
The Requires SSL option can be selected if you want your part to force any page its placed on to respond on an SSL connection. NetCommunity will handle this for you when the page is requested. This is a good idea if your part captures or displays any sensitive information.
 
For the sake of our quick start, we will skip the "Supports Personalization" for now. We will dedicate a whole article on that advanced topic.
 

Using Your Custom Part

Now that everything is installed, you are ready to use your custom part. At this point, your part is treated just like any built in part. You can create instances of it from the Parts gallery or directly from the page designer. Editing your part will bring up your part’s Edit Control and on every page you place your part you will see your Display Control.

Note: You will see that once you’ve used your part and created at least one instance of it, that it can not be removed from the Custom Parts gallery, until you delete all instances of it.

Next: To get started with some working samples check out Quick Start: Custom Part Samples