Introduction

This tutorial shows you how to create a simple module for the open source CMS Cuyahoga.
Visual studio 2008 was used to create this example, but it should also work in Visual Studio 2005 with the SP1 upgrade.

Supporting documents:
Cuyahoga.Modules.Sample Files VB.net
PDF tutorial

1. Download Cuyahoga source

You can download the latest version here:
http://sourceforge.net/projects/cuyahoga/files/

2. Install and run site

Set up a sample site or use your current Cuyahoga site.

3. Open the Cuyahoga solution in visual studio.

4. Add a new web application project to the solution.

Name the project using the following standard: Cuyahoga.Modules.

5. Delete all files currently in the project.

6. Add directories

Add the following directories to your project:
Web
Install
Install/Database
Install/Database/mssql2000

7. Add post build events.

Edit and then add the following post build events to your project properties:

xcopy /s /y "$(ProjectDir)"Web\*.as?x "$(SolutionDir)"Web\Modules\Sample\
xcopy /s /y "$(ProjectDir)"Install\Database\*.sql "$(SolutionDir)"Web\Modules\Sample\Install\Database\
xcopy /s /y "$(TargetDir)"Cuyahoga.Modules.Sample*.dll "$(SolutionDir)"Web\bin\

You can find the post build events window by going to:
Open Project Properties

Click the Compile tab

Click the build events button

If your using a different version of visual studio, the build events window might be a tab in the project properties window.

8. Add project references.

You will need to add at least the following two project references:
Cuyahoga.Core
Cuyahoga.Web

To add a project reference, right click on the project in the solution explorer and the select add reference.

In the add reference dialogue, navigate to the project tab and select the project you wish to add.

9. Create the module controller.

Create a new class in the root of your module project called Module.
For example – SampleModule

Add the following code to your class, remember to change SampleModule for the name of your module.

C#

using System;
using Cuyahoga.Core.Domain;

Namespace Cuyahoga.Modules.Sample
{
    ///

    /// Controller class of the module
    /// 

    class SampleModule: ModuleBase
    {
        ///

        /// Controller constructor
        /// 

        Public SampleModule()
        {
            //nothing in the constructor for this basic sample
        }
    }
}

VB.net

Imports System
Imports Cuyahoga.Core.Domain

'''

''' Controller class of the module
''' 

Class SampleModule
    Inherits ModuleBase
    '''

    ''' Controller constructor
    ''' 

    Public Sub New()
        'nothing in the constructor for this basic sample
    End Sub
End Class

10. Create a user control.

Add a new user control to your web folder, for example:

<%@ Control Language="C#" AutoEventWireup="true" CodeBehind="Sample.ascx.cs"
    Inherits="Cuyahoga.Modules.Sample.Web.Sample" %>
Hello World!

The code behind needs to inherit the BaseModule Control.

For example:

C#

using System;
using System.Data;
using System.Configuration;
using System.Collections;
using System.Web;
using System.Web.Security;
using System.Web.UI;
using System.Web.UI.WebControls;
using System.Web.UI.WebControls.WebParts;
using System.Web.UI.HtmlControls;

using Cuyahoga.Web.UI;

Namespace Cuyahoga.Modules.Sample.Web
{
    ///

    /// Sample control displayng in Cuyahoga the "Hello World" text
    /// 

    public partial class Sample : BaseModuleControl
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            //for this basic sample we do not need to do anything
        }
    }
}

VB.net

Imports System
Imports System.Data
Imports System.Configuration
Imports System.Collections
Imports System.Web
Imports System.Web.Security
Imports System.Web.UI
Imports System.Web.UI.WebControls
Imports System.Web.UI.WebControls.WebParts
Imports System.Web.UI.HtmlControls

Imports Cuyahoga.Web.UI

Namespace Web
    '''

    ''' Sample control displayng in Cuyahoga the "Hello World" text
    ''' 

    Partial Public Class Sample
        Inherits BaseModuleControl
        Protected Sub Page_Load(ByVal sender As Object, ByVal e As EventArgs)
            'for this basic sample we do not need to do anything
        End Sub
    End Class
End Namespace

11. Create the SQL installation scripts.

In the Install/Database/mssql2000 folder you need to add 3 files to take advantage of the auto install and uninstall features.

Version File

For example if your module is at version 1.0.0, you need to add a file called 1.0.0.sql with the following code:

UPDATE cuyahoga_version SET major = 1, minor = 0, patch = 0 WHERE assembly = 'Cuyahoga.Modules.Sample'
go

install.sql

The install.sql file will contain all the tables and stored procedures that need to be installed in the database to run your module, as well as update some of the CMS tables to identify your module.

For example:

/*
 *  Table data
 */
--Install the Sample module for Cuyahoga in SQL Server

INSERT INTO cuyahoga_moduletype ([name], assemblyname, classname, path, editpath, inserttimestamp, updatetimestamp)
VALUES ('Sample', 'Cuyahoga.Modules.Sample', 'Cuyahoga.Modules.Sample.SampleModule', 'Modules/Sample/Sample.ascx', NULL, getdate(), getdate())
GO

INSERT INTO cuyahoga_version (assembly, major, minor, patch)
VALUES ('Cuyahoga.Modules.Sample', 1, 5, 0)
GO

uninstall.sql

The uninstall.sql file will contain instructions to delete the tables, stored procedures and other records installed by the install.sql file.

For example:

--Uninstall the Sample module in Cuyahoga for SQL Server

DELETE FROM cuyahoga_version WHERE assembly = 'Cuyahoga.Modules.Sample'
go

DELETE FROM cuyahoga_moduletype
WHERE assemblyname = 'Cuyahoga.Modules.Sample'
go

12. Rebuild entire solution and run.

Run the site and login as admin.
Navigate to the modules page and you should now see your module in the table.

Click install and if everything is fine it should be installed and you can now add that modules to sections of the site.

Troubleshooting

Namespace problems.

You might come across a problem when you try to install the module which throws the following error:

An error occured: Loading failed for Sample.Could not find module: Cuyahoga.Modules.Sample.SampleModule, Cuyahoga.Modules.Sample

This is caused by some of the namespaces in your module not being compiled correctly.
I found out that Visual studio sometimes adds the default namespace to your class in addition to whatever namespace you declare.
So if you used Namespace Cuyahoga.Modules.Sample.Web in your code, this will actually come out as Namespace Cuyahoga.Modules.Sample.Cuyahoga.Modules.Sample.Web.
To fix this remove the default namespace from your class. So the example I provided before will now simply be: Namespace Web

Install Scripts

In order for the install scripts to work, they need to have the right file name and be places in the correct folder structure defined in the tutorial.
Its recommended to have all three files for this feature to work smoothly.

Cannot see web form or user control source files in Visual Studio.

For some reason, Visual Studio will sometimes hide certain files and folders. To see all files in the project folder go to PROJECT in the main menu and select SHOW ALL FILES.

Further reading:

http://www.paolocorti.net/2007/04/30/cuyahoga-hello-world-sample-module-tutorial/
http://www.cuyahoga-project.org/home/developers.aspx