Maybe more appropriately titled, What's Not New in the NetCommunity 5.5 API, this article will introduce you to the complete revamping and expansion of the Custom Parts API in the latest version of NetCommunity. If you've already logged some hours building custom parts or you are new to the whole experience this introduction is a good place to help you get started with version 5.5 programming.
 

What Changed?

For the seasoned custom part developer let's start with the key thing that is different: the object model names and structure. If this is all new to you, you can read ahead.

Within your custom part code you previously would reference the different parts of the API via the NetCommunity property of the base class CustomPartDisplayBase or CustomPartEditorBase (depending on if you were in the display control or the editor control for your part): 

  • NetCommunity Property- top level of object model:
    • CurrentUser - properties and methods of the current user
    • Transactions - custom transactions
    • Services - access to clearing credit cards
    • CurrentChapter - access to current chapter properties/methods (if applicable)
    • Services - access to credit card clearing service
    • NetCommPage - access to properties/methods of current page 

Alternatively, as a short cut, some of these same objects were properties of the base class themselves and directly accessible as well:

  • CurrentUser
  • Services
  • Transactions
To support a more structured growth to the API we moved some things around. These old properties will still compile and function for backwards compatibility, but you will see Obsolete warnings from the compiler directing you to the newer syntax. Expect to see more methods and properties added to the API as we expose more and more of the platform functionality in subsequent releases.
 
The new model has you access everything in the API via the API property of the respective base class (CustomPartDisplayBase or CustomPartEditorBase). The API property contains a rich object model below it for accessing the entire API. You will however still access your part's content via the Content object property of base class.  So the only two properties of the base you really need focus on are API and Content, as depicted here:
 
 
 

The API

Now that everything is under one roof let's see the summary of what you now have access to. Each area of the API is represented by an object property of the API property:
 

API Properties

Pages Property

Access to a set of methods to get page information and some helpful methods that have to do with NetCommunity pages, such as GetName for getting the name of a page, NavigateTo to response.redirect to a particular page, and CurrentPage to get the Name, Id, and Title of the current page.

Parts Property

Access to various methods to party on NetCommunity parts, such as CreateNewPartInstance for creating a new instance of any part type. Other methods include GetAllPartsOfType, GetPartTypeInfoByName, and LoadCustomPartContentFromPartId.

Images Property 

Provides methods for building Image urls, including scaled thumbnail versions.

Users Property

Various methods to access the current user and specified users. Also provides the ability to create new users, log a user in and out, and to check for username availability. You can use these methods to create your own login and user registration process. The RecordNewUser method creates a built-in signup transaction that can be processed by the existing Raiser's Edge / eCRM processor as well as the ability to send a custom Welcome email.
 
The API.Users.CurrentUser property provides access to the current user's properties including username, userid, Raiser's Edge record id, Education Edge record id (if applicable), what roles the user is in, and other properties such as FirstName, LastName, and DisplayName, and if the user is logged in or an administrator.

Navigation Property

Useful methods for building URLs to site pages, documents, and style sheets. Including access to MenuXML, a cool new feature that coughs up an XML document for any given menu part that respects the current users rights, so you can build you own custom menu parts to render standard built in menus in different ways.
 
Also available from the Navigation property is the ability to build a dynamic page URL from a given Vanity name so, if a vanity name of Donate was given to a particular page, you could call this method to build http://www.myOrg.org/Donate automatically without having to worry about the protocol, domain, or virtual directory name of your installation.
 
Another powerful addition here is the GetPartEditURL() method, which creates the javascript required to summon the part editor modal dialog for any part instance. So if you are building a collection of parts that party on each other, or parts that enhance other parts like a new way to render a menu part, you can summon the designers for your dependent parts from your own parts. There is a new set of ASP.Net Server Controls available in the NetCommunity Open Platform that includes a button control to do just that. More on these server controls a little later.

Documents Property

Provides full programmatic access to the Document parts in your system. Syntactically, each document part is referred to as a Document Library. Methods exists to add, update, delete documents from a selected library, as well as methods to enumerate all libraries, get library properties, enumerate documents in any library, getting document properties, and building dynamic document URLs. There are enough methods and properties here to build your own rich document system, or just tap into the power from your custom part. 
 
One interesting example is to build a custom part(s) that manages javascript and CSS documents, and attaching them to pages using the built in ScriptManager methods of the .net framework.

RSS Property

This very useful set of methods gives you programmatic access to the RSS feeds you've created on your site via any Weblog parts, including the ability to post a story to any feed, enumerate all feeds in your site retrieving their properties, and building any feed's URL.  Useful examples here include using RSS feeds as internal notifications of activities occurring on your site and within your custom parts.
 

Transactions Property

Unlike the Transactions property in previous versions, the API.Transactions property provides access to the built-in transaction types of NetCommunity. At press time this will include in this release just the Donation transactions. Here you have the ability to record a built-in donation transaction including the automatic processing of a credit card, custom email acknowledgment (w/ custom merge fields), and the option to not generate the donation transaction for the back office. All donation payment types are accepted including pledges, credit cards, direct debit, and checks. Tribute gifts may be created but for the 5.5 release, recurring gifts may not.  Multiple designations are also supported so that gifts may be split across multiple funds. Full support for appending gift attributes is also included. 
One nice feature here is the ability to record the gift in "demo" mode, so the credit card is not actually cleared. This allows you to fully test your custom donation form and acknowledgment email before going live.
 
The API.Transaction property also has a method for enumerating your installed merchant accounts. This is useful if you want to provide the ability to select a merchant account in the designer of your custom donation form.

CustomTransactions Property 

The methods found here were formerly on the Transaction property in prior versions. Not much has changed other than where these methods are found. These methods provide access to creating, updating, managing, and even processing custom transactions that you define.  An example here may be a Contact Me form, where your custom part uses a form to collect name and email and telephone information from a user. The data collected can be recorded as a custom transaction. All of the transactions of this type can then be managed, enumerated, and processed by other custom parts. The platform takes care of the details of persisting the data and managing the processed status. Custom Transactions are also available for download, if you want to process them in the Raiser's Edge, via a Custom Transaction Processor. But that's another article.

Utility Property

This random set of methods provides access to enumerate back office Attributes and CodeTables, enumerators for TimeZones and the current user's and web site's time zone information, and NetCommunity version information.

Settings Property

Access some of the the web site's settings properties including Password minimum length and case-sensitivity rules, and default home page id.
 
 
So that's a fly-by on the API methods themselves. With the reorganization of the object model it is well poised for even more growth in subsequent releases. In the next section we'll cover an area of the Open Platform that existed to some degree in prior versions but was not documented. In version 5.5 this area has gotten some love, so let's take a look.
 
 

Custom Server Controls

 
In version 5.5 the NetCommunity Open Platform offers a collection of ASP.net server controls that you can use in your custom parts to pull off a variety of bottled functionality that already exists in the platform. Often times these tasks include internal dependencies that the server controls can safely handle for you, such as a needed platform javascript file, processing logic, or a call to a platform web service. The list of controls includes:
 
  • AddressUI - Offers the form for entering an address, taking into account the selected country and morphing itself appropriately such as changing a field caption from City to Suburb.

  • CFAPicker - Offers a modal UI for selecting a Campaign, Fund, or Appeal from the back office, making the appropriate web service calls to populate a search form, and return the selected item.

  • EmailEditor - Offers the HTML editor in email edit mode, allowing you to specify a field provider for populating the merge fields drop down. Choices include Profile fields, Donation fields, User Registration fields or none. You can also provide a set of custom merge fields that your custom transaction part may provide the data for at runtime.  Very useful for designing email acknowledgments for custom transaction forms.

  • HtmlEditor - Offers the HTML Editor including the appropriate dialogs for link picking, and image selection. Handles the processing of the content for safe storage, including the translation of all links from actual to relative.

  • HtmlDisplay - Use this control whenever you want to display HTML that was edited with the HTMLEditor control. It handles the translation of links from relative back to fully qualified, among other things.

  • ImageSelectButton - Renders an ASP Button control that summons the Image select modal dialog. This is the same dialog used by the platform and honors security of the current user to offer the ability upload new images if allowed as well as controlling access to only those images the user has access to.

  • PageLink - This control allows the user to select a link. It shows the link currently selected and offers the standard modal dialog for selecting a link either from the site, to a document, or a manually entered URL.

  • PartEditButton - Renders an ASP Button that summons the modal dialog for editing any part instance.

  • PartSelectButton - Renders the UI for selecting another part, showing the part name currently selected. Can be set to only allow selection of a certain part type.

  • QueryPicker - Renders the UI for selecting a back office Query, showing the one currently selected. Offers the same modal dialog for searching and selecting a Query that is available in the system. Options include limiting the type of Query that can be selected and whether to look at The Raiser's Edge/eCRM or The Education Edge (if applicable).

  • TimeZonePicker - Renders a dynamic drop down that is populated with all of the available world time zones.
 
Theses custom server controls begin a pattern being adopted in the Open Platform of offering built in user interface functionality to be consumed by custom parts. Many of the functions these controls perform would be very difficult to rebuild from scratch as a custom developer and it makes sense to offer more and more of these as the Open Platform grows.
 

Summary

So that's a broad overview of the new Open Platform capabilities available in NetCommunity version 5.5. Stay tuned for some interesting samples that exercise some of the powerful possibilities for extending NetCommunity beyond the box, adding more unique kinds of content, functionality, and integration to your web site.