A Precarious Balance

UPDATE: If you've come here looking for information about integrating PayPal into Community Server or about paid subscriptions for Community Server, I and several other Community Server technical evangelists have put together a product named Four Roads Commerce. You can find information about it at the Four Roads website. 

I've been on a short break writing about the Paid Subscriber project; the bread and butter project needs a good dose of attention as I near the finish line on some infrastructure changes.

We've recently talked about how to store settings for a PayPal payment gateway by making use of XML and a custom data provider. We followed that up with an overview of creating language resources.

The next challenge is to create a basic administrative screen to configure the gateway.

The only reason I can even write this post is because of Wyatt Preul's CS Module Management Administration page. Reading his code showed me how to put this together. That guy's good.

The destination

The following screenshot should give you an idea of what I want. In the Administration area of the Control Panel, under the System Tools section, there's a Payment Settings menu item. When you click it, you go to the Manage Payment Settings screen where you can configure payment settings that apply to all communities (i.e., "Global") and payment settings for the current community.

If you click the Add Settings button (after we add settings, it will say "Configure"), you see a modal dialog like the following:

Create an assembly to hold your code

The admin screen and all its backing code needs to go somewhere. I want it to be in its own assembly yet be able to debug and test with the full set of Community Server source code. Here's what I did:

1. Download and install the Community Server SDK.
2. Load the SDK solution and add a ASP.NET Web Application project. Note that I'm comfortable with web app projects as they exist in VS.NET 2003. So I installed the Web Application Project support for Visual Studio 2005.
3. Add project references to the following CS projects:
   • CommunityServerComponents20.csproj
   • CommunityServerControls20.csproj
   • CommunityServerWeb20 (Internal).csproj
4. Add references to the following assemblies:
   • ComponentArt.Web.UI
   • MetaBuilders.WebControls.MasterPages
5. Open the project properties.
6. In the textbox labeled "Post-build event command line", enter script that causes this project's assembly to be copied into the CommunityServerWeb20 project's bin directory. The path will end up being {CS SDK root}\source\web\bin.

Following is the script I used for Step 6:

echo POSTBUILDSTEP for $(ProjectName)
 
xcopy "$(TargetPath)" "$(SolutionDir)Web\bin\" /i /d /y
if errorlevel 1 goto BuildEventFailed

Add a web form to your assembly

This is the user interface for the payment settings. In our case, we need two forms. One to provide the overview of the global and community-specific settings. Another to let us edit the actual settings. The goal of this post is to give you an overview of how to get a screen integrated into the CS Control Panel, so I won't go into details about the forms just yet.

Copy your form to the Control Panel Tools directory

In order for CS to see your forms, the *.ASPX files need to be somewhere within your CS web application directory structure. In Wyatt's example, he plopped the ASPX files into {CS root}\web\ControlPanel\Tools. Looked good to me so I did the same. Note that if you are using the CS SDK, the path will be {CS SDK root}\source\web\ControlPanel\Tools.

Add a menu item to SetupNavBar.config

At this point, our assembly is being copied into CS's bin directory and the *.ASPX files are within its directory structure. Now we need to tell CS about the screen. All Control Panel menu items are configured via the file SetupNavBar.config, located in directory {CS root}\web\ControlPanel.

SetupNavBar.config is an XML file. Its contents are retrieved by an instance of class ControlPanelNavigationSidebar. The source code for that class is located in {CS Root}\web\ControlPanel\Controls\ControlPanelNavigationSidebar.cs.

Following is an example of the XML in SetupNavBar.config:

To add our own menu item to the System Tools tab, we add another Tab element within the SubTabs element.

<Tab resourcename="CP_Tools_NavBar_SystemTools" name="SystemTools" roles = "systemadministrator">
   <SubTabs>
   ...
      <Tab text="Payment Settings" href="~/ControlPanel/Tools/PaymentSettings.aspx"
         name="PaymentSettings"/>
   </SubTabs>
</Tab>

Note that we hardcoded the text. Right now, we cannot make use of a custom language resource. The code that builds the control panel uses the resourcename attribute on a Tab element, but it ignores the resourcefile attribute and looks for the resource in the ControlPanelResources.xml file. You could modify ControlPanelResources.xml, but my preference is to leave CS code alone.

At this point, we've created a custom assembly to hold our code, created an empty web form to hold the UI for our settings, and hooked the form into the CS Control Panel. If you run the CS SDK solution, you should be able to navigate to the Control Panel, and see a menu item named Payment Settings.

In the next post, we'll rough in the user interface.

--
Sean Winstead

Tags: CommunityServer