Apr

30

Cuyahoga: "Hello World" sample module tutorial

Filed on April 30th, 2007 at 11:59 am under , , , , ,  

Cuyahoga is an impressive open source web site framework (and CMS) with many impressive features like:

  • RDMBS indipendency via NHibernate
  • Enterprise architecture
  • Plug-in architecture
  • Deployable, using Mono, to platforms different from Windows, like Linux, Mac OS X, Solaris, unlike other popular .NET CMS
  • Search engine based on DotLucene
  • Full ASP .NET 2.0 engine
  • logging system via log4net (the same logging engine in zigGIS)

People willing to deeply dig in Cuyahoga may download the latest release (1.5.0) source code and this basic tutorial for developing Cuyahoga modules.

The problem with this tutorial is that is a bit out of date (is based on VS 2003 and on a old release of Cuyahoga) so I thought to make this post to update the tutorial to VS 2005 and to the current stable release of Cuyahoga.

Here I am assuming that you are using VS 2005 IDE and Cuyahoga 1.5.0. You can of course use other IDEs without problems, but my post is concerned about using VS 2005.

We will create a very simple module, just showing the classic "Hello World" text. In my next posts I will write a longer tutorial with data management.

Open the Cuyahoga source code solution. The current (1.5.0) Cuyahoga solution has the following structure:

Cuyahoga source code solution

If you want to customize Cuyahoga for your needs, the best option is to create one or more modules, and plug them in the Cuyahoga core. It is discouraged to directly modify the Cuyahoga core, if doing so you would get in troubles when you want to update the Cuyahoga release of your web site to a newer release.
Note that this is the same approach used by the Cuyahoga's development team: they implemented additional more specific features as additional features (Articles, Forum, RemoteContent…): if you need them you can plug them in in your portal, if not you don't add them and your portal will be lighter.

The first thing to do is to create an ASP .NET Web Application Project and add it to the Cuyahoga source code solution. With Visual Studio 2005 this is not anymore possible because of the new Web Site Architecture, but you can still do this by downloading the very usefull Visual Studio 2005 Web Application Project Model by Scott Guthrie.
After downloading and installing this model, you will be able to create a new ASP .NET Web Application Project with VS 2005. Name it following the Cuyahoga standards, for example: Cuyahoga.Modules.Sample.

Still follow the Cuyahoga standards, and create at your project the following directory structure:

standard directory structure for a Cuyahoga module

After creating this directory structure, you have to configure the auto-deploy of your module to the Cuyahoga web site, in order to correctly debug your module.
To do so go to your project's properties >> Build events and add this text to the Post-Build event command line text box:

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\

Now we will go with the following steps, necessary for each module we would develop with Cuyahoga:

  • creation of the module controller
  • creation of the domain classes (not for this basic sample) and the NHibernate mapping files
  • creation of the UI components: aspx page for the administrative pages and ascx user controls for the page showing the contents inserted by the administrative pages (in this basic sample we will have just one user control)
  • creation of the sql for installing and uninstalling your module from the Cuyahoga web site

CREATION OF THE MODULE CONTROLLER

The module controller is the core of your module, and must be a subclass of Cuyahoga.Core.Domain.ModuleBase.
Add to your module project a reference to the Cuyahoga.Core project, and then add the following class at the root of your module:

using System;
using Cuyahoga.Core.Domain;
 
namespace Cuyahoga.Modules.Sample
{
    /// <summary>
    /// Controller class of the module
    /// </summary>
    class SampleModule: ModuleBase
    {
        /// <summary>
        /// Controller constructor
        /// </summary>
        public SampleModule()
        {
            //nothing in the constructor for this basic sample
        }
    }
}

note the coding conventions: your module controller should be named ModulenameModule, in this case is SampleModule.

CREATION OF THE USER CONTROL

We create an user control named Sample.ascx in the web directory of the module, with just adding the "Hello World" line.

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

The code behind class of the user control must inherit from Cuyahoga.Web.UI.BaseModuleControl, so you will need to add a reference to your module's project to the Cuyahoga.Web projects.

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
{
    /// <summary>
    /// Sample control displayng in Cuyahoga the "Hello World" text
    /// </summary>
    public partial class Sample : BaseModuleControl
    {
        protected void Page_Load(object sender, EventArgs e)
        {
            //for this basic sample we do not need to do anything
        }
    }
}

CREATION OF THE SQL INSTALLATION AND UNISTALLATION SCRIPTS

If you want to deploy your module to many web site, or to make it available to the Cuyahoga community, the most convenient way is to create the sql installation and uninstallation scripts.
You have to place both script in the database directory of your module, for each database you want to make available the module (SQL Server, Postgres, MySQL…).

For this basic sample I am assuming you will make your module available only for SQL Server based Cuyahoga web site, but feel free to easily conver the two scripts for other databases.

--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, '2007-27-04 14:36:28.324', '2007-27-04 14:36:28.324')
GO
 
INSERT INTO cuyahoga_version (assembly, major, minor, patch) 
VALUES ('Cuyahoga.Modules.Sample', 1, 5, 0)
GO
--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

Note: you are not forced to write your installation and uninstallation scripts. This is for your commodity. You could just run the two scripts within your RDBMS.
But doing so Cuyahoga will let you install and uninstall the module, and this is very confortable for other people using your module.

Here the basic things to note are that one row is inserted in the cuyahoga_moduletype table (to make Cuyahoga aware of the existence of your module) and one row in inserted in the cuyahoga_version table (to make Cuyahoga aware of the version number of your module).
For more complex modules, when you will have to provide external tables for persisting data, you will have to add this tables in this script (for example look at the sql scripts for the Articles module).

TESTING THE SAMPLE MODULE

Now run your solution (you have to set the Cuyahoga.Web project as the startup project), go tho the admininstration interface of your web site, and go to the "manage modules" section: you will have the possibility to install (and uninstall) the Sample module:

Installation of a module

When the module is installed you can use it. Still from the administration section of the Cuyahoga CMS, add a page and create in the page a new section:

Creation of a new section, and adding the module

Then save and preview your new page, with the new section containing the module.

In the next times I will post a tutorial covering the development of a more complex Cuyahoga module, with domain objects, persistence and NHibernate mapping files.

Comments

6 Responses to “Cuyahoga: "Hello World" sample module tutorial”

  1. Travis Laborde on May 24th, 2007 8:53 pm

    Wow, what a great tutorial!!!

    I had a few problems getting it set up since I went with VB.NET for my module, and apparently there is a tweak that must be done to the root namespace or some such thing. I fiddled with it until I got it to work.

    I just discovered Cuyahoga, and your tutorial was GREAT!

    I greatly look forward to your next installment!

    Travis

  2. Paolo Corti on May 24th, 2007 11:33 pm

    Glad that you liked it Travis
    by the way, i have seen that at the Cuyahoga web site they have updated at the 1.5.0 release the original tutorial on which is based mine. So you may check it out, because I am not sure when I will exactly be able to add a second part covering more advanced topics (domain and Nhibernate, basically).

  3. trung on May 27th, 2007 12:37 am

    I want to try this framework

  4. rbailey on June 11th, 2007 2:09 pm

    I like your tutorial. Very clear.

    I am having a bit of a problem with Cuyahoga however. I have tried to setup the sample but when I run it, the following exception is thrown: "'Cuyahoga.modules.Sample.Web.Sample' is not allowed here because it does not extend class 'System.Web.UI.UserControl'.".

    Also, when I try to add a node at the root level, I am informed that a node with the same culture already exists. Well, if I can't do that, then how do I add another page to the site? I see no add new page link.

    Thanks for your help,

    Richard Bailey
    Lodestone Solutions

  5. Paolo Corti on June 11th, 2007 2:19 pm

    Richard
    to add another page to the site go to the root page (Home or YourSite node) and you will find an "add new child" button at the end. That is the way for adding content to your site.
    Instead I can not figure out what could be your problem with the exception you have, in any case some people i know tested this tutorial and they had not troubles…
    Let me know

  6. T.t.t!Ck. on August 17th, 2007 1:23 pm

    good job!
    thanks!