BVC 5 - Create a Content Block

Summary

BVC5 is the most customizable version of BV Commerce to date. This article will show you how to build a content block module to add new features without recompiling and without modifying the core source code of the application. The new BVModule class makes it easy to get started and provides helpful functionality to create rich content for power users.

The Content Block Module Architecture

Content block modules are built out of ASP.NET user controls, images, style sheets, and sometimes custom DLLs. They can be written in any .NET language that you wish and can be added to any BVC5 store just by copying files into the correct folders on web site.

All content block modules are stored in the /BVModules/ContentBlocks folder of BVC5 stores. Inside the /BVModules/ContentBlocks folder is one sub-folder for each content block. The name of the folder is used as the name of the content block module. For instance, the Image Rotator control that ships with BVC5 can be found in the /BVModules/ContentBlocks/Image Rotator folder as shown in Figure 1.

Figure 1 – Content Block Folder Structure

Each content block module folder must contain a user control named view.ascx. This user control is required. Most modules will also contain a control named adminview.ascx which is used by the administration web site and customizable modules will include a control named editor.ascx which lets administrators change module settings. All of these controls must inherit from the BVSoftware.BVC5.Core.Content.BVModule class or they will be ignored by the web site.

Figure 2 – Controls normally found in modules

At run time, the web site scans the /BVModules/ContentBlocks folder and looks for available modules. When an administrator edits a content column or custom page in the admin web site, a drop down list shows all available modules. If an adminview.ascx file is found it will be loaded used by the admin web site to display the module in the content columns. If an editor.ascx control is found, an “edit” button will be available next to the module in the content column editor.

Figure 3 - Editing a Content Column

Once an administrator has added a module to a content column or custom page, it will immediately display on the store in the appropriate location. The store pages will scan the /BVModules/ContentBlocks folder for the requested module’s view.ascx control. If the module isn’t found, it is ignored and will not be shown on the store.

The BVModule base class

The BVSoftware.BVC5.Core.Content.BVModule class is the heart of all content block modules. Without it BVC5 has no way to communicate with your module. To make sure your module is wired up correctly, edit the source code for your view.ascx, adminview.ascx, and editor.ascx controls so that they are inheriting the BVModule class. You will probably want to add a reference to the BVSoftware.BVC5.Core DLL in your source code.

Figure 4 - Inheriting from the BVModule class

The BVModule class contains a property named BlockID. This is a unique identifier for each instance of your module that can be used to save and load settings. For example, the Mailing List Signup module has a setting for which you can register a user email address when the user signs up. If you have two Mailing List Signup forms on the same page in your store, each module will have its own unique BlockID assigned. This would let each module be configured to work with a different mailing list.

The BVModule class contains several functions that will help make your job as a module developer easier. Take a look at Figure 5 for a complete list.

Figure 5 - BVModule Class

ClearAllSettings	Used to erase all single settings for the module. Useful as a way to reset to defaults.
GetAllSettings	Returns a list of all saved settings for the module.
GetSetting	Gets a single setting by name
SaveSetting	Sets a single settings by name and value
GetSettingList	Gets a sorted setting list by ListName
GetSettingListItem	Gets a single item from a setting list
InsertSettingListItem	Adds a single item to a setting list
UpdateSettingListItem	Updates a single item in a setting list
DeleteSettingListItem	Removes an item from a setting list
MoveSettingListItemUp	Moves an item up in a sorted setting list
MoveSettingListItemDown	Moves an items down in a sorted setting list
NotifyFinishedEditing	Called when editor.ascx has completed all tasks to let the admin web site continue.

The BVModule class provides two different ways to store block settings: Single Settings and List Settings. Single Settings are used to store individual items for a block. For instance, you may wish to store a custom title or text string for your block in a single setting. List Settings are used to store sorted lists of configuration information. For example, the Image Rotator module uses a List of Settings called “Images” to store the Urls of the images it rotates. The HTML Rotator module uses a List of Settings to store the HTML content it rotates. One particularly useful feature of the List Settings type is that you get the ability to move items up and down in sorted order without writing any code.

The other important feature of the BVModule class is the NotifyFinishedEditing method. If your module includes an editor.ascx control, you should call this method after you save or update settings. For example, the Mailing List Signup module includes both “Save Changes” and “Cancel” buttons. The “Cancel” button calls the NotifyFinishedEditing method without saving changes and the “Save Changes” button calls various SaveSettings methods before calling the NotifyFinishedEditing method.

Tutorial 1 – Hello, World Module

In this tutorial we will create the most basic Content Block module possible. When complete, this module will display the text “Hello, World” on our BVC5 store.

1. Create a new folder called “Hello World” in the /BVModules/ContentBlocks folder of your web site.

2. Create the view.ascx and view.ascx.vb files for the main view of the module.

a. For Visual Studio 2005: Right-click on the “Hello World” folder and select “Add New Item.” Add a WebUserControl and make sure the “Place Code in Separate File” checkbox is checked.

b. If you’re using a text editor or other editing tool create files named view.ascx and view.ascx.vb. Edit each to match the ones that would have been created by Visual Studio 2005. See the code listed below.

3. View.ascx should look like this

4. View.ascx.vb should look like this

5. Now we need to add some text to our control. Add the message "Hello, World" to the view.ascx file. It should look like this:

6. Finally, we need to make sure that we inherit from the Content.BVModule class so that BVC5 knows how to communicate with our module. Edit the view.ascx.vb file to look like this:

7. Our module is ready to be tested. Log into the admin web site and go to Content->Home Page->Edit column 1. Look for your control called “Hello World” to appear in the new block drop down list and add it to the first content column of your home page.

8. Click the "Go to Store" link in the admin and your custom module should show up on your store and look something like this: