I've been asked to make a form for our website that will capture the details of the person who filled it in, send their details to us, and then display a link to a downloadable document - the idea being that they only get the download if they allow us to capture their details. Additionally, if a box on the form is ticked, the form needs to email another part of the organisation to instruct them to post out a hard copy of the document.
This is exactly the kind of thing that would be pretty much impossible to do with Netcommunity out of the box, but it should be pretty straightforward to do with a custom part.
My plan is to create a standard asp.net form within a custom part, with validation for the form fields. When the form is posted back to the server, the server will double-check all of the values in the form fields, send us the details, and then check to see if the tickbox has been checked. If it has, a request for a hard copy of the document will be sent to us also. The server will then display the link to download the document. All of that will occur in the display part.
The editor part will allow the Administrator / Content Editor to change some settings, such as the SMTP server name (for the mail), the subject title of the email, the from address, and so on. It would be possible to extend this to allow the editor to customise form fields, but that's not necessary in this case as the form has a very specific purpose. All of these settings will be saved in the BBNC database, and retrieved by the display part and used accordingly when the form is posted back to the server.
I'm going to try to get the form pre-filled with details from Netcommunity, such as name and so on - however, as we're currently running BBNC 5.1, I don't think the API will allow me to retrieve much more than the username of the person on the page without talking to Raiser's Edge (the 5.5 API seems to have a few more options with regards to getting user information). I haven't yet learnt how to talk to Raiser's Edge in a Custom Part (I haven't yet needed to), so I think I might give that one a go and see how I get on.
I'll post up the source code if I can get it all to work. Either way we're upgrading to BBNC 5.6 in a few weeks.
This must seem pretty basic and simple to a 'proper' developer but I'm having fun figuring it all out nonetheless.
Thursday, 23 July 2009
Wednesday, 22 July 2009
Tutorial: Creating a Netcommunity custom part #1
Once you've got Visual Studio (or similar - see below blog post) installed, you can begin creating a custom part. Open VS and create a new ASP.NET Web Application project. If the option to use 'code-behind' is available, make sure that you do.
You can also select the language you'd like to use to program your application - I use C#, you can use whatever you like. I simply prefer the syntax of C# as it's more similar to 'classic' programming languages like C/C++ and less classic but more familiar scripting languages like Javascript (Javascript is awesome). VB.NET doesn't look right somehow. I like curly braces.
If you're not familiar with the VS environment, go and find some tutorials.
Assuming that you know your way around VS, you should see that a Default.aspx page and accompanying code-behind page (Default.aspx.cs) has been created. Delete those - you won't need them.
Add a reference to the BBNC API
First thing to do is add a reference to the BBNCExtensions DLL. This lives in the 'bin' folder of your Netcommunity installation. If you're developing on the web server where BBNC lives, then you can reference it directly. If not, copy the DLL from the 'bin' folder to your development environment and reference it from there. (to add a reference, right click on 'References' in the Solution Explorer on the right hand side of VS, and click 'Add new Reference')
Depending on the version of BBNC you're developing for, you might also need to alter the version of the .NET framework that your custom part uses. For example, Netcommunity 5.1 uses version 2.0 of the .NET framework. By default, recent versions of Visual Studio will reference a more recent version of the framework. This shouldn't present a problem if you're on a more recent version of BBNC, like 5.6, but if not - change the framework for your application by clicking on 'Project' and then '[nameofyourapp] Properties'. Simples.
(bear in mind that if you do change the .net version to 2.0, you'll need to delete some of the references to newer classes that VS automatically puts in to your application - click the 'References' tab on the right of the VS window and delete any that have a little warning sign next to them. you might also have to remove some of the 'using' statements from the top of your code-behind pages when you create them. if that doesn't make sense read this article from Microsoft )
Create some web user controls
Once all that's been done, click on 'Project' then 'Add new item'. Add a Web User Control and name it 'DisplayTest.ascx'. This user control will be added to your Solution Explorer on the right of the VS window. Double click 'DisplayTest.ascx' and the accompanying code-behind to open them up. If you're not familiar with what you see, there'll be another blog post explaining it all. For now, click on 'design' - it's underneath the main display window in VS when you're looking at DisplayTest.ascx. Type "Hello, this is DisplayTest" or whatever you'd like to say. This is what will (hopefully) appear to users looking at a page containing your custom part.
Don't worry about the code-behind, for now - the code-behind is where you can do all the clever stuff with C#. For now simply displaying some HTML should suffice. The design mode in VS is essentially a WYSIWYG editor - it'll convert whatever you type into HTML.
Next, create another Web User Control and name it 'EditorTest.ascx'. Follow the same steps as before, but this time enter different text such as "Hello, this is EditorTest".
Add some code to the EditorTest code-behind
Sadly, for the EditorTest section of our custom part, we will need to add some C# to the code-behind. To go over what we've done so far, the DisplayTest control is what the end user will see on a page. The EditorTest control is what a Content Editor or Admin using the BBNC Administration will see when they click 'Edit'. BBNC needs to know what to do when an Editor / Admin clicks 'Save' after editing any part, even a custom part, so you need to fill in some code to tell it what to do.
Firstly, open up the code-behind for EditorTest. You'll need to add another 'using' statement - add it underneath the others:
You can also select the language you'd like to use to program your application - I use C#, you can use whatever you like. I simply prefer the syntax of C# as it's more similar to 'classic' programming languages like C/C++ and less classic but more familiar scripting languages like Javascript (Javascript is awesome). VB.NET doesn't look right somehow. I like curly braces.
If you're not familiar with the VS environment, go and find some tutorials.
Assuming that you know your way around VS, you should see that a Default.aspx page and accompanying code-behind page (Default.aspx.cs) has been created. Delete those - you won't need them.
Add a reference to the BBNC API
First thing to do is add a reference to the BBNCExtensions DLL. This lives in the 'bin' folder of your Netcommunity installation. If you're developing on the web server where BBNC lives, then you can reference it directly. If not, copy the DLL from the 'bin' folder to your development environment and reference it from there. (to add a reference, right click on 'References' in the Solution Explorer on the right hand side of VS, and click 'Add new Reference')
Depending on the version of BBNC you're developing for, you might also need to alter the version of the .NET framework that your custom part uses. For example, Netcommunity 5.1 uses version 2.0 of the .NET framework. By default, recent versions of Visual Studio will reference a more recent version of the framework. This shouldn't present a problem if you're on a more recent version of BBNC, like 5.6, but if not - change the framework for your application by clicking on 'Project' and then '[nameofyourapp] Properties'. Simples.
(bear in mind that if you do change the .net version to 2.0, you'll need to delete some of the references to newer classes that VS automatically puts in to your application - click the 'References' tab on the right of the VS window and delete any that have a little warning sign next to them. you might also have to remove some of the 'using' statements from the top of your code-behind pages when you create them. if that doesn't make sense read this article from Microsoft )
Create some web user controls
Once all that's been done, click on 'Project' then 'Add new item'. Add a Web User Control and name it 'DisplayTest.ascx'. This user control will be added to your Solution Explorer on the right of the VS window. Double click 'DisplayTest.ascx' and the accompanying code-behind to open them up. If you're not familiar with what you see, there'll be another blog post explaining it all. For now, click on 'design' - it's underneath the main display window in VS when you're looking at DisplayTest.ascx. Type "Hello, this is DisplayTest" or whatever you'd like to say. This is what will (hopefully) appear to users looking at a page containing your custom part.
Don't worry about the code-behind, for now - the code-behind is where you can do all the clever stuff with C#. For now simply displaying some HTML should suffice. The design mode in VS is essentially a WYSIWYG editor - it'll convert whatever you type into HTML.
Next, create another Web User Control and name it 'EditorTest.ascx'. Follow the same steps as before, but this time enter different text such as "Hello, this is EditorTest".
Add some code to the EditorTest code-behind
Sadly, for the EditorTest section of our custom part, we will need to add some C# to the code-behind. To go over what we've done so far, the DisplayTest control is what the end user will see on a page. The EditorTest control is what a Content Editor or Admin using the BBNC Administration will see when they click 'Edit'. BBNC needs to know what to do when an Editor / Admin clicks 'Save' after editing any part, even a custom part, so you need to fill in some code to tell it what to do.
Firstly, open up the code-behind for EditorTest. You'll need to add another 'using' statement - add it underneath the others:
using BBNCExtensions;
using BBNCExtensions.Parts;
This allows you to use the classes defined in the BBNCExtensions DLL that you added a reference to earlier.
You next need to set the main class for your Control to inherit from the CustomPartEditorBase - that sounds horrendous, doesn't it? Look in the code-behind - there'll be a namespace declaration containing the name of your project (ie. namespace MyTestProject) and then underneath there will be a class containing the name of the Control you're working on - it should say something like this:
public partial class EditorTest : System.UI ETC ETC ETC
Change this so that it inherits from something else instead, namely this:
public partial class EditorTest : BBNCExtensions.Parts.CustomPartEditorBase
That colon means 'inherit from'. You need to add a similar bit of code to the code-behind for your Display part also, except that it will instead inherit from 'BBNCExtensions.Parts.CustomPartDisplaybase'. It will also need a 'using' statement. So go and do that.
Once you've done that, go back to the EditorTest code-behind file. You need to add a couple of new methods to override the default behaviour of the page when it loads. This is where the intellisense comes in handy -VS guesses what you're typing and tries to help. Underneath the Page_Load method, add another one that says this (intellisense might try to help you out with it):
public override void OnLoadContent() {
}
It doesn't need to contain anything right now, but for future reference this is the area where you can ask your application to interface with the BBNC database and grab data to present to whoever might be editing the custom part.
You also need to add this, to tell the program what to do when a user clicks 'Save':
public override bool OnSaveContent(bool bDialogIsClosing){
return true;
}
Again, we don't need our program to save anything or do anything at the moment, but this method requires a 'boolean' (yes or no) value to be returned anyway. We return true, and therefore the Editor window will close nicely. If you don't include this method, when a user tries to leave the Editor window they will encounter a server error.
Build your project
Now you need to build your project and check it for errors - click 'Build' and then 'Build [myprojectname]'. The compiler will let you know if there have been any errors that need to be rectified.
Deploy your project
If you're confident that everything is ok, you next need to deploy the files to the Netcommunity installation. If you're developing on the web server where your Netcommunity installation lives, you can publish directly to the relevant folders. If not (and I'll assume not), you'll need to FTP or RDC them to the right place. The two .ascx files (DisplayTest.ascx and EditorTest.ascx) need to be deployed into the 'custom' folder in your Netcommunity folder. Another file, which will be inside the 'bin' folder of your project and will be called '[myprojectname].dll', needs to be deployed into the 'bin' folder in your Netcommunity folder.
Let Netcommunity know
Once you've done that, you need to let Netcommunity know that you've deployed a new custom part. Login as an Administrator / Supervisor and click on 'Administration' then 'Custom Parts'. This is the Custom Parts gallery. Click on 'New custom part'.
You'll need to enter a name, and a description, and then you'll need to enter the path to where your custom part files are. The only files BBNC is interested in are the .ascx files - it can find the .dll on its own.
In the 'Display Control Source' box enter the relative path to the DisplayTest.ascx file - it might be something like:
~\custom\DisplayTest.ascx
In the 'Editor Control Source' box enter the relative path to the EditorTest.ascx file - it might be something like:
~\custom\EditorTest.ascx
Click on 'Save', and bang. Almost done. Now you need to create an instance of your part using Netcommunity and test that it works. Go to a test page you've created before, and click 'New part' somewhere in your layout where you'll be able to see it. On the list of available parts, you'll now see whatever you decided to call your Custom Part. Select it, and click next. The Editor text you typed in earlier should appear. Click Save, and then preview the page to see if it works.
It should do. So there's a very lengthy but hopefully relatively thorough introduction to how to create a simple custom part. If it looks horrendously complicated, I guess it kind of is, but you soon get into the swing of it.
Any experienced Netcommunity developers feel free to point out any mistakes I've made!
Netcommunity custom parts & helpful links
Customising Netcommunity is all based around 'custom parts' - these are custom web controls that you create, that then get integrated into the CMS. For example, you could create a custom part that just prints some text to a page - "Hello World" or whatever. Once you've created the custom part, you push it onto the web server where Netcommunity lives, and then tell Netcommunity where it is. After that, it can be used and reused like any other Netcommunity part - it becomes fully integrated.
It's up to you to decide the level of complexity of the custom part you've created. If you just want to include some HTML or Javascript into the page (something you can't always do with the formatted text part that comes with Netcommunity), it's very simple to do. However, if you want to make the custom part resemble an application, with settings that can be changed by your content editors / web editors, and with data that gets stored in the Netcommunity database, it's a bit more complicated.
I'll start with what I first tried - creating a custom part that, when included into a Netcommunity page, printed out a line of text. Sounds simple, eh. First, you'll need a few things if you haven't got them already:
Visual Studio
Full version of Visual Studio would be nice, if not, grab this one (it's free):
http://www.microsoft.com/express/vwd/
Access to the BBNC server
You'll need access to the server that your Netcommunity installation sits on. It'll probably live somewhere like C:\Program Files\Blackbaud\Netcommunity - in there is a folder called 'bin', and another folder named 'custom'. Those two folders are where you place the various files related to your custom part. If you don't have access to these folders (if you're hosted by Blackbaud for example), then you're not going to be able to deploy your custom parts.
Other useful links:
Blackbaud Labs - http://labs.blackbaud.com/NetCommunity/Page.aspx?pid=211
This is a fairly helpful resource, albeit brief when it comes to helping beginners. There's some downloadable samples of custom parts Blackbaud have made. The first example just prints some text to the page. The last one is far more complicated. All the code examples are in VB.NET.
Blackbus - http://www.blackbus.org/forum/netcommunity-bbnc
Forum for users of Blackbaud products, there's a Netcommunity section. Lots of knowledgeable people there, with plenty of questions answered that you might find helpful.
Next
I'll explain how to create and deploy a simple custom part.
It's up to you to decide the level of complexity of the custom part you've created. If you just want to include some HTML or Javascript into the page (something you can't always do with the formatted text part that comes with Netcommunity), it's very simple to do. However, if you want to make the custom part resemble an application, with settings that can be changed by your content editors / web editors, and with data that gets stored in the Netcommunity database, it's a bit more complicated.
I'll start with what I first tried - creating a custom part that, when included into a Netcommunity page, printed out a line of text. Sounds simple, eh. First, you'll need a few things if you haven't got them already:
Visual Studio
Full version of Visual Studio would be nice, if not, grab this one (it's free):
http://www.microsoft.com/express/vwd/
Access to the BBNC server
You'll need access to the server that your Netcommunity installation sits on. It'll probably live somewhere like C:\Program Files\Blackbaud\Netcommunity - in there is a folder called 'bin', and another folder named 'custom'. Those two folders are where you place the various files related to your custom part. If you don't have access to these folders (if you're hosted by Blackbaud for example), then you're not going to be able to deploy your custom parts.
Other useful links:
Blackbaud Labs - http://labs.blackbaud.com/NetCommunity/Page.aspx?pid=211
This is a fairly helpful resource, albeit brief when it comes to helping beginners. There's some downloadable samples of custom parts Blackbaud have made. The first example just prints some text to the page. The last one is far more complicated. All the code examples are in VB.NET.
Blackbus - http://www.blackbus.org/forum/netcommunity-bbnc
Forum for users of Blackbaud products, there's a Netcommunity section. Lots of knowledgeable people there, with plenty of questions answered that you might find helpful.
Next
I'll explain how to create and deploy a simple custom part.
Welcome
Hello, welcome - this blog will serve as a manual of sorts for me to keep track of how I'm getting on with using the Blackbaud Netcommunity API. It might be helpful for you if (like me) you're fairly new to ASP.NET and all the associated malarky.
Blackbaud Netcommunity (BBNC) is a content management system for websites, aimed at non-profit organisations - see http://www.blackbaud.com/ for an overview. Out of the box, it's quite inflexible in terms of what you can achieve, but luckily there's an API that is exposed to developers that allows them to customise the CMS quite heavily. Less luckily, it's not very well documented and fairly alien to anyone that isn't quite familiar with ASP.NET programming and that sort of stuff.
I haven't let that put me off though, so I've been learning C# and wading through the sparse examples provided by Blackbaud to try and figure out how they work. I've also reverse-engineered some other samples I've found. All of this means that I'm slowly starting to get it. Bonza.
Since starting to look at all this stuff, I've been able to do a number of things that would previously have been outsourced to web development company at great expense. With relatively little effort, I can now create custom web forms exactly how I would like them, that submit data to a database or fire off emails to receipients; I can customise previously inaccessible sections of the website such as the page head; and I can include custom HTML and Javascript easily and painlessly.
The most recent customisation I've made is a fully-functioning 'notice board', that allows users to post up notices and advertisements. It interfaces with a simple database, and uses Javascript to allow the user to customise how it looks. I also created a 'widget' for the homepage that grabs the last 10 items and lists them. All of this is fully integrated into the website as if it was a part of Netcommunity itself. However, there's a lot more for me to learn, especially when it comes to using the BBNC database and interfacing with Raiser's Edge, another Blackbaud application (a database).
Most of the examples you'll find floating around on the web related to BBNC customisation are written in Visual Basic.NET (VB.NET) - I really don't like the syntax of VB, so I've opted to use C# instead. Unfortunately, it appears that I'm pretty much on my own with that decision - however, it's not too difficult to convert VB to C#, especially if you use a number of nifty tools that are out there. One particular tool I've found very handy allows you to disassemble compiled .DLL assemblies - in other words, you can poke through existing customisations and convert them into the source language of your choice, VB or C#. I'll talk about that one in a subsequent post.
I'll just reiterate that I'm not a programmer, so I imagine I'll frequently use the wrong words, explain things entirely incorrectly, and quite possibly only ever come out with badly-optimised and stupid code. However, there's a small chance it might all be alright, and either way - I'm learning. Hopefully you might find some of it helpful.
Cheers.
Blackbaud Netcommunity (BBNC) is a content management system for websites, aimed at non-profit organisations - see http://www.blackbaud.com/ for an overview. Out of the box, it's quite inflexible in terms of what you can achieve, but luckily there's an API that is exposed to developers that allows them to customise the CMS quite heavily. Less luckily, it's not very well documented and fairly alien to anyone that isn't quite familiar with ASP.NET programming and that sort of stuff.
I haven't let that put me off though, so I've been learning C# and wading through the sparse examples provided by Blackbaud to try and figure out how they work. I've also reverse-engineered some other samples I've found. All of this means that I'm slowly starting to get it. Bonza.
Since starting to look at all this stuff, I've been able to do a number of things that would previously have been outsourced to web development company at great expense. With relatively little effort, I can now create custom web forms exactly how I would like them, that submit data to a database or fire off emails to receipients; I can customise previously inaccessible sections of the website such as the page head; and I can include custom HTML and Javascript easily and painlessly.
The most recent customisation I've made is a fully-functioning 'notice board', that allows users to post up notices and advertisements. It interfaces with a simple database, and uses Javascript to allow the user to customise how it looks. I also created a 'widget' for the homepage that grabs the last 10 items and lists them. All of this is fully integrated into the website as if it was a part of Netcommunity itself. However, there's a lot more for me to learn, especially when it comes to using the BBNC database and interfacing with Raiser's Edge, another Blackbaud application (a database).
Most of the examples you'll find floating around on the web related to BBNC customisation are written in Visual Basic.NET (VB.NET) - I really don't like the syntax of VB, so I've opted to use C# instead. Unfortunately, it appears that I'm pretty much on my own with that decision - however, it's not too difficult to convert VB to C#, especially if you use a number of nifty tools that are out there. One particular tool I've found very handy allows you to disassemble compiled .DLL assemblies - in other words, you can poke through existing customisations and convert them into the source language of your choice, VB or C#. I'll talk about that one in a subsequent post.
I'll just reiterate that I'm not a programmer, so I imagine I'll frequently use the wrong words, explain things entirely incorrectly, and quite possibly only ever come out with badly-optimised and stupid code. However, there's a small chance it might all be alright, and either way - I'm learning. Hopefully you might find some of it helpful.
Cheers.
Subscribe to:
Posts (Atom)