Web-Application Framework - Catharsis - part V. - adding new Entity

Enter into Catharsis - adding new Entity

This article is next step in Catharsis documented tutorial. Catharsis is web-application framework gathering best-practices, using ASP.NET MVC (preview 5), NHibernate 2.0. All needed source code you can find on

http://www.codeplex.com/Catharsis/

Adding new Entity into solution 

At this chapter You will Enter into Catharsis! In any meaning that sentence can have.

Prerequisites: Catharsis.Guidance 0.8.7; You have installed Catharsis.Guidance (Registered the source code, or installed provided Setup); You have created new Solution (using Guidance) or opened the Example solution; You have SQL Server 2005, well you can (due to NHibernate) have any storage!!! but for our tutorial, the scripts and stuff will be SQL Server 2005 oriented.

I suggest you follow this tutorial (this chapter) exactly! Once is enough - to catch the essence of Catharsis. You‘ll see. 

Object Person

Let’s say, we need the Person object for our application. In the future phases of application development this object can hold information for Supplier’s ContactPerson, or for application User, or for Employee …

At the very beginning we will need three properties. 1) Code, which will be unique for every person 2) FirstName and 3) SecondName (not so brainy, but clear enough).

What do we need next? Create objects (classes) which will allow us to handle object Person. To create new Persons, change them, display them in the list, sort them, search … get access to right users, apply business rules …

Table Person

To store Person in DB we’ll create table:

(SQL Server snapshot)

CREATE TABLE [dbo].[Person](
   [PersonId] [int] IDENTITY(1,1) NOT NULL
 , [Code] [nchar](150) NOT NULL,
 , [FirstName] [nvarchar](250) NOT NULL,
 , [SecondName] [nvarchar](250) NOT NULL,
 CONSTRAINT [PK_Person] PRIMARY KEY CLUSTERED 
(
    [PersonId] ASC
)WITH (PAD_INDEX  = OFF, STATISTICS_NORECOMPUTE  = OFF
, IGNORE_DUP_KEY = OFF, ALLOW_ROW_LOCKS  = ON
, ALLOW_PAGE_LOCKS  = ON) ON [PRIMARY]
) ON [PRIMARY] 

Notes to table Person

Table needs primary key, in our case PersonId which is in our case of type int. Catharsis is based on integer keys (so if you want to change this behavior for your application, find and change settings in a core libraries Catharsis.Entity, Catharsis.Data).

Table should have its PersonId set to auto identity, which allows us to let that job on NHibernate and database. This key is needed for relations, foreign-keys, indexes… on a DB side. Application will use it as the ‘object built-in property ID’, mainly on UI as an identifier (the <select ...><option value="entity.ID"...> is good example).

Every POCO entity in Catharsis framework must be derived from class public abstract class PersistentObjectWithTypedId<int> from namespace Catharsis.Entity.PersistentObjects. As you will see in a future chapters there are prepared to base classes for you in ‘Firm.Product.Entity’ library Persistent and Tracked.

The last thing I would like to mention is the ‘NOT Null’ constraint. I strongly suggest you do not create NULL columns in your DB. There should be always any value provided by user (except of cases like FireDate of Employee, which is really and maybe the only good example of using Null). It could lead to a good discussion, but at this point the suggestion is enough.

Catharsis.Guidance

Well, we have table for our Person. And we have opened Catharsis solution and installed Catharsis .Guidance (see previous chapters)

Select your ‘Firm.Product.Entity’ project. Create new folder named for example ‘People’. Right click on this folder and you should see a menu item

(Re) Create COMPLETE infrastructure.

If this menu item is missing then you have to switch on the guidance (all needed steps are shown in the next picture)

(Re) Create COMPLETE infrastructure

Click this menu item and the wizard screen will appear:

Class Name will be Person. The next three inputs can be filled with properties. The first (if provided) is returned by the Entity method GetDomainObjectSignature(), which is responsible for distinguishing among instances. Fill in Code, FirstName and SecondName.

Because you have clicked on an ‘People’ folder, its name is provided as namespace. On the next page are checkboxes which now must remain unchecked. Just click Finish. And the Catharsis will be coming.

Adding few features

Catharsis.Guidance just have created many classes into every layer. You can (should) build the solution, which will fail because of missing Controller name ‘Person’.

Controller Person const

Open ‘Firm.Product.Common’ project, folder Constants. Add into the file ‘Str.Controllers.cs’ public const string Person = "Person";

ReBuild solution, no error should be reported. The last think we have to do is add Person to Navigation links.

Naviagtion to Person

In the ‘Firm.Product.Business’ project open folder AopFilters and select class NavigationAttribute.cs. This is an AOP filter-attribute, which (at current version of Catharsis) very simply sets navigation-links dependently on the user’s CurrentRole.

Just imagine: You create smart xml file with navigation. Which user can from which controller or action navigate to which links, dependently on CurrentRole. You will provide an Xml Navigation Reader on that attribute, and application as whole gets a really strong work-flow! One Place!)

The last think is assure, that you as a user, have been added to application, and that you have been granted for roles Viewer and RegisteredUser. Catharsis will help us in the runtime …

Do not hesitate and press F5, just to start debug…

Enter into Catharsis

Look, observe and test what have changed in our application. New navigation is available (for RegisteredUser and Viewer roles). You can add, update, list, sort, search and delete Person entities.

The only needed tasks was: Create Table, run the Catharsis.Guidance wizard to create all needed classes, Add constant to Controller names and grant access to this new area-entity-controller  

You'll like it...

Enjoy Catharsis 
Radim Köhler

Sources  

All needed source code you can find on

http://www.codeplex.com/Catharsis/

History  

...