N2 CMS Developer Documentation

About

N2 CMS is a Web Application that simplifies the task of developing and managing web sites. The intended audience is professional web developers and non-technical web managers.

The first version was published in 2006. Since then 45 versions have been released. The latest version, 2.1, was published in October 2010.

Contents

About 1

System Requirements 5

Operating System 5

Web Servers 5

.NET Framework 5

Databases 5

Wildcard mapping (IIS 5-6.1) 5

Visual Studio Development 6

Shared Hosting 6

Links and Resources 6

Official Links 6

Developer documentation resources 6

Management documentation resources 6

Downloading 6

N2 CMS 2.x Source Code 7

N2 CMS 2.x ASP.NET MVC Templates Pack 7

N2 CMS 2.x ASP.NET WebForms Templates Pack 7

N2 CMS 2.x MVC Minimal Example 7

N2 CMS 2.x C# Minimal Example 7

N2 CMS 2.x Visual Basic Minimal Example 7

N2 CMS 2.x Compiled Framework and Management UI 7

Installing 7

Web Platform Installer (WPI) 7

Installing N2 CMS from Microsfot Web Platform Installer 7

Installing N2 CMS from Internet Information Services (IIS) Manager 16

Installing N2 CMS from Microsoft WebMatrix 21

Installing not yet published releases using WPI 22

Unzip 24

Installing ASP.NET Template Pack from zip 25

Changing databases 28

Using IIS 29

Using Visual Studio Integrated Development Server 29

Installing Code Snippets 29

Installing Visual Studio Item Templates 30

Installing Intellisense Documentation for Visual Studio 30

Software Architecture 30

CMS Framework vs. Web Application 30

Web Application Architecture 31

CMS Framework Architecture 31

WebForms vs. MVC 32

Routing to content with ASP.NET MVC 32

Development topics 34

Converting the project to Visual Studio 2010 34

Creating a content page controller in ASP.NET MVC 36

Creating Content Page Template in WebForms 44

Content Type Development 47

WebForms ASPX Pages 49

ASP.NET MVC View Helpers 50

Defining editors 50

Parts on WebForms 52

Parts on ASP.NET MVC 54

Integrating with Existing ASP.NET MVC Application 57

Integrating with Existing WebForms Application 65

What, where and by whom? 65

Caching 67

Creating custom editors 68

Organizing the editor interface 70

Finding content 72

Finding details 74

Filtering content 74

Security 76

Configuring permission 76

Authorizing users 76

Membership & Roles 76

Manipulating content 76

Creating content 77

Relations between items 78

Multiple sites 78

Content Globalization 78

Configuration 78

Adapters 78

Global Events 78

Management Plugins 78

Performance 78

Caching 78

Page complexity 79

Number of client requests 79

Number of queries 79

Database index tuning 79

Replacing core services 79

Building (unit) testable controllers 79

Upgrading 79

Using the trunk 79

Deployment & Shared Hosting 79

Packaging 79

FTP 79

Configuration 79

Model changes 79

Template Packs 79

ASP.NET MVC 79

Dinamico 80

WebForms 80

Add-ons 80

Frequently Asked Questions 80

Where is the documentation? 80

Medium Trust 80

Wildcard Mapping 80

Common Exception Types 80

Contributors 80

Fine-tune authorization 81

Add new roles to the content role provider 81

Configuring role to manage site area 82

Training videos 84

System Requirements

Operating System

Any OS capable of running .NET framework such as:

· Windows XP

· Windows 2003

· Windows Vista

· Windows 2008

· Windows 7

· Windows 2008 R2

Web Servers

· IIS 5-7.5

· ASP.NET Development Server

· WebMatrix

.NET Framework

· .NET Framework 3.5 SP1

· .NET Framework 4.0

N2 CMS 1.5 can also run on .NET Framework 2.0.

Databases

Supported databases include:

· SQL Server 2008 *

· SQL Server 2008 Express *

· SQL Server 2005 *

· SQL Server 2005 Express *

· SQL Server 2000

· SqlCe

· MySQL *

· SQLite *

· Firebird

· Jet

· DB2

· Oracle9i

· Oracle10g

* A connection string example can be found in web.config

Wildcard mapping (IIS 5-6.1)

On IIS 5 to IIS 6.1 wildcard mapping can be enabled to support “extensionless urls” (no ending .aspx on each page address). To enable this use IIS Manage.

· http://n2cms.com/wiki/IIS-Wildcard-Mapping.aspx

Visual Studio Development

Visual Studio 2008 or Visual Studio 2010 (needs project upgrade) are recommended for site development with N2 CMS. Visual Studio Express can also be used.

Shared Hosting

Some users report no problems running in shared hosting under medium trust, others have had problems. N2 CMS has been tested on unmodified medium trust. It’s recommended you ask the hosting provider before you buy a long-term plan. Find more info online:

http://n2cms.com/wiki/Medium%20trust.aspx

Links and Resources

Official Links

· Web site: http://n2cms.com/

· Downloads: http://n2cms.codeplex.com/releases

· Forum: http://n2cms.codeplex.com/discussions/

· Bug tracker: http://n2cms.codeplex.com/workitem/list/basic

· Source code: http://code.google.com/p/n2cms/source/checkout

· Demo site: http://demo.n2cms.com/

Developer documentation resources

· http://n2cms.com/Documentation.aspx

· http://api.n2cms.com/

· http://code.google.com/p/n2cms/wiki/Welcome

· http://n2cms.com/wiki.aspx

· http://n2cmstutorial.blogspot.com/

· http://stackoverflow.com/questions/tagged/n2

· http://jamesbroo.me/tag/n2-cms/

· http://martinondotnet.blogspot.com/search/label/n2cms

· http://www.codeproject.com/Articles/86664/N2CMS-Forum-Addon-Fixing-the-Theme.aspx

· http://interferencelogik.com/docs/N2CMS_TheLittleHandbook.pdf

Management documentation resources

· http://training.lithe.net.au/

Downloading

The latest versions are available for download on Codeplex:

· http://n2cms.codeplex.com/releases

N2 CMS 2.x Source Code

This package reflects the N2 CMS framework development environment and contains both template packs and all examples along with the framework source code. For site development it’s recommended to start from one of the template packs, or examples.

N2 CMS 2.x ASP.NET MVC Templates Pack

This is the source code of the MVC template package along with a compiled version of the framework. Use this package to develop your own site with existing functionality using ASP.NET MVC.

N2 CMS 2.x ASP.NET WebForms Templates Pack

This is the source code of the WebForms template package along with a compiled version of the framework. Use this package to develop your own site with existing functionality using ASP.NET WebForms.

N2 CMS 2.x MVC Minimal Example

This package contains a simple example site along with a compiled version of the framework. Use this package to understand the basics of ASP.NET MVC + N2 CMS or if you don’t need existing templates.

N2 CMS 2.x C# Minimal Example

This package contains a simple example site along with a compiled version of the framework. Use this package to understand the basics of WebForms/C# + N2 CMS or if you don’t need existing templates.

N2 CMS 2.x Visual Basic Minimal Example

This package contains a simple example site along with a compiled version of the framework. Use this package to understand the basics of WebForms/Visual Basic + N2 CMS or if you don’t need existing templates.

N2 CMS 2.x Compiled Framework and Management UI

This is the N2 CMS framework compiled and zipped for upgrade of a previous version, or integration with an existing site.

Installing

To install N2 CMS in a development environment unzip one of the template packs or examples, open the solution file within with visual studio and run (Ctrl+F5). This will start a site using SQLite embedded database and the visual studio integrated web server.

Web Platform Installer (WPI)

The same WPI package can be installed from the “Microsfot Web Platform Installer”, from “Internet Information Services (IIS) Manager” or from “Microsoft WebMatrix”.

Installing N2 CMS from Microsfot Web Platform Installer

Make sure WPI is installed and start it. You can download WPI from:

· http://www.microsoft.com/web/downloads/platform.aspx

Locate N2 CMS in Web Applications / CMS / N2 CMS 2.x MVC Edition and check it and click Install.

Click I Accept to accept the LGPL license agreement.

This installs N2 CMS as an application in a virtual directory, i.e. http://localhost/N2CMS/. Use the Web Site drop down to change this.

Most users will want to Create new database. The Database Administrator is used to create the database and requires elevated permissions. The Database User is used by the web site to store and read content during operation (this user needs to be permitted to create tables in the database). The database password must be at least 8 characters, contain lower- and uppercase characters and numbers. The database server is the name of the SQL Server instance. The database name is the name of the database which is created. The web administrator password is the password for the “admin” user when managing the web site online. Fill the blanks and click Continue.

Lean back and wait while the site is deployed.

Click on the Launch N2 CMS 2.x MVC Edition link to continue on the web based setup wizard. The online setup wizard can be reached at any time from the “/n2/installation/” path.

Click on please help me install on a new site.

The username is “admin”. Use the password you chose previously and click Log in.

Click Create tables, and advance to step to by clicking on “step 2”.

Select a theme of your liking and click “Please import this”. Advance to step 3.

Click on restart, then click on managing.

Congratulations. The site is installed. When you return to it you can access this management UI from the /N2/ path.

Installing N2 CMS from Internet Information Services (IIS) Manager

You can download a template pack from Codeplex and install it using IIS manager.

Right-click on a web site, Deploy / Import Application…

Select the package you downloaded from Codeplex and click Next.

Click Next.

Select “Create new database” and click Next.

From now on it’s the same as “Installing N2 CMS from Microsoft Web Platform Installer. Continue reading there.

Installing N2 CMS from Microsoft WebMatrix

Install Site from Web Gallery. Select CMS / N2 CMS 2.x MVC Edition and click Next.

From now on it’s the same as “Installing N2 CMS from Microsoft Web Platform Installer. Continue reading there.

Installing not yet published releases using WPI

Often there is a newer version available than the one in Application Gallery.

Click Options in the lower left corner.

Write http://n2cms.com/wpi.xml in “Display additional scenarios” and click Add feed, and then OK.

Select the N2 CMS tab, click on Customize and check the release you want to install. The installation procedure is the same as in the previous tutorials.

Unzip

The template packs and examples can run straight from unzip. The steps to follow are roughly the same as “ASP.NET MVC template pack”.

Installing ASP.NET Template Pack from zip

Download ASP.NET MVC template pack (or WebForms) and unzip.

Find the solution file within, and open it.

Visual Studio may ask permission to configure IIS. Choose YES.

To use SQLite database copy [ziproot]\Libraries\System.Data.SQLite.dll to [ziproot]\N2CMS\bin

To start the site, press Ctrl+F5.

Voila! You can access the management UI from the URL /n2/ with the username/password admin/changeme. You can change the password in web.config.

Changing databases

N2 supports several kinds of databases. To configure another database open web.config in the site’s root directory and find the <connectionStrings> section.

<!-- Some connection string examples

SQLite: <add name="N2CMS" connectionString="Data Source=|DataDirectory|\n2.db;Version=3;New=True;" providerName="System.Data.SQLite"/>

SQL Server 2005: <add name="N2CMS" connectionString="Server=(local);Database=N2_Templates;Integrated Security=SSPI"/>

SQL Express 2005: <add name="N2CMS" connectionString="Data Source=.\SQLEXPRESS;AttachDbFilename=|DataDirectory|\N2.mdf;Integrated Security=True;User Instance=True" providerName="System.Data.SqlClient"/>

SQL Server 2000: <add name="N2CMS" connectionString="Data Source=SQLServer2000;Database=SQLDatabase2000;User Id=SqlUser2000;Password=SqlPassword2000;Network Library=DBMSSOCN;" providerName="System.Data.SqlClient"/>

MySQL: <add name="N2CMS" connectionString="Data Source=MySQLServer;Database=MySQLDatabase;User Id=MySQLUser;Password=MySQLPassword;" providerName="MySql.Data.MySqlClient"/>

-->

N2 supports several kinds of databases. To configure another database open web.config in the site’s root directory and find the <connectionStrings> section. Remove the existing connection string and update the most relevant template to your database’s settings.

Using IIS

The most easy way to configure IIS is to let WPI or visual studio configure the web application for you. Doing this manually means creating a web site or a web application below a site (not virtual directory) and setting the path to the unizipped site’s root directory.

Using Visual Studio Integrated Development Server

To use the integrated web server right-click on the templates project, choose project properties, select the Web tab and select Visual Studio Development Server.

Installing Code Snippets

The downloadable packages on Codeplex contains a number of templates and snippets which are useful when developing N2 sites.

Snippets are copied to [Documents]\Visual Studio 20xx\Code Snippets\Visual C#\My Code Snippets. Once the snippets have been placed here they can be invoked from visual studio by their name and tapping tab twice (e.g. n2propfta [tab] [tab]). This will expand a property with an editable attribute. Available snippets:

· n2prop.snippet

· n2propcb.snippet

· n2propenum.snippet

· n2propfta.snippet

· n2propimage.snippet

· n2proptb.snippet

· n2propuc.snippet

· n2propurl.snippet

Installing Visual Studio Item Templates

The snippets folder also contains some Visual Studio Item Templates that appears when adding new items in Visual Studio. Copy them from the Snippets folder in the template package zip to [Documents]\Visual Studio 2008\Templates\ItemTemplates\Visual C#. The item templates creates a content class and a corresponding template or controller. Available templates:

· N2 Item Template.zip

· N2 Page Template.zip

· N2 Page Controller.zip

Installing Intellisense Documentation for Visual Studio

Check for /bin/N2.xml. This enables code documentation during intellisense operations and hovering in Visual Studio.

Software Architecture

An N2 CMS web site is layered into two parts. One part is a CMS Framework and another other part is the Web Application.

CMS Framework vs. Web Application

The framework is represented by N2.dll, N2.Security.dll and N2.Management.dll as well as all files below the /N2/ folder. These reflect upon the application to create a UI where the site’s structure and content is managed. The framework provides tools the application can use to create a navigable web site.

The application references N2.dll and uses API:s in the N2 namespace to model content items so they can be managed from the management UI. The application contains the external shape of the site including master pages, style sheets and application logic. The application is developed with ASP.NET MVC or WebForms, either way they use the same version of the N2 CMS framework.

Web Application Architecture

The N2 framework has only one requirement on the application. There must be a class inheriting from N2.ContentItem. Instances of this class represent the pages managed in the UI. It’s a good idea to use multiple classes for different kinds of pages, and use inheritance to share common properties.

Each content class is related to one or more ASPX templates, or views which display the user managed content in a shared layout. The framework provides base classes and controls to simplify placing content, creating navigation and more.

When a page instance is created in the UI it is assigned a name which gives this page an URL from which it can be accessed. Assuming the start page has the path “/”, a page named “hello” will be accessible from the path “/hello/”. The framework is responsible for mapping this logical path to the ASPX template or view.

CMS Framework Architecture

The N2 CMS Framework uses Inversion of Control to compose all of the CMS’ functionality. During initialization a set of services are constructed and exposed through a singleton context located at N2.Context.Current. Many helper methods such as N2.Find.Items access this context to do their job.

Most of the interaction with N2 CMS is done through inheritance of classes or usage of attributes. During the initialization phase N2 analyzes the application and learns how to connect the content in the database with the application code.