Getting started


The easiest way to get started with Piranha CMS is to install the NuGet package from Visual Studio, but you can also just install the binaries of even download the source code for the latest version. The different NuGet-packages available are described in detail in the article NuGet packages.


System requirements

Piranha CMS requires .NET framework 4.5 and can run on Azure Sql, SqlServer 2005/2008/2012, SqlCompact 4.0, SqlExpress and MySql. It uses the following awesome packages from NuGet:


Creating a new ASP.NET Web Pages website

To create a new Piranha CMS web site, begin by creating an ASP.NET Empty Web Site in Visual Studio. As soon as you have your new site, right-click it and choose Manage NuGet Packages, search for Piranha CMS and install and the template site package. If you want to use the package manager console, simply write:

PM> Install-Package PiranhaCMS

Once the installation is finished open up your new site in your browser of choice and you will be prompted with the installation screen to set up your admin account. After that you're good to go.

Checking for updates

After creating a new projects it's always a good idea to check for package updates to see if any of the core packages have been updated after the main template.

PLEASE NOTE: After installing version 2.2.4 of the NuGet package PiranhaCMS you need to manually update Piranha.Core to version 2.2.4.1 since the reference to AutoMapper is missing.


Creating a new ASP.NET MVC Web application

To create a new Piranha CMS Mvc application begin by creating an ASP.NET Web Application in Visual Studio and choose the Empty template. Make sure that you check to Add folders and core references for MVC. As soon as your project is created, right-click it and choose Manager NuGet Packages, search for Piranha CMS and install the template site package for Mvc. If you want to use the package manager console you write:

PM> Install-Package PiranhaCMSMvc

When installing the NuGet-package you'll get a dialog saying that App_Start\RouteConfig.cs already exists, asking you if you want to overwrite it.

If you installing Piranha CMS in a new project you should click Yes and overwrite the standard RouteConfig.cs that the MVC4 creates. If you're installing Piranha CMS in an existing MVC application and has made modifications to your routing you should click. For safety the NuGet package includes a file called App_Start\RouteConfig.PiranhaCMS.cs that has the same content as RouteConfig.cs in case you don't want to overwrite your existing file.

The main difference between the standard route config and the one included in Piranha CMS is that it ensures that no controllers from the manager interface will be included in the routing for the application, otherwise name collisions is likely to occur.

Once the installation is finished open up your new site in your browser of choice and you will be prompted with the installation screen to set up your admin account. After that you're good to go.

Checking for updates

After creating a new projects it's always a good idea to check for package updates to see if any of the core packages have been updated after the main template.

PLEASE NOTE: After installing version 2.2.4 of the NuGet package PiranhaCMSMvc you need to manually update Piranha.Core to version 2.2.4.1 since the reference to AutoMapper is missing.


Older version of Piranha CMS

To create a new Piranha CMS Mvc application for MVC 4, begin by creating an ASP.NET MVC 4 Web Application in Visual Studio and choose the Empty template with Razor syntax. Otherwise the same applies as in the above description.


Adding Piranha CMS to an existing application

When adding Piranha CMS to an existing application you don't need to install any of the template projects as they add files for building a new application from scratch. Instead you install the package that matches your application type.

Installing the NuGet packages

For ASP.NET Web Pages applications you install:

PM> Install-Package PiranhaCMS.WebPages

For ASP.NET MVC applications you install:

PM> Install-Package PiranhaCMS.Mvc

Setting up the system

If your current application already has configured forms authentication you will most likely get a duplicate forms authentication tag in your Web.config by installing Piranha CMS. You can safely remove this parameter and use your already configured authentication.

<system.web>
<authentication mode="Forms">
   <forms name="PiranhaCMS" timeout="30"/>
  </authentication>
</system.web>

You should also set the Piranha CMS Web.config setting passiveMode to true. This will disable all permalink routing and allow your current application to fully control the routing of the pages.

<piranha>
<settings>
...
<passiveMode value="true" />
</settings>
</piranha>

ASP.NET MVC Routing

By default the default route of ASP.NET MVC maps all controllers from all areas and namespaces to the default route. This can cause duplicates in controller names as the manager interfaces is built on MVC. To ensure that only your controllers are mapped to your default route you must update the RouteConfig.cs file in your application in the same way as it's done in the template project for MVC. Add the lines highlighted with bold to your RouteConfig.cs.

routes.MapRoute(
name: "Default",
url: "{controller}/{action}/{id}",
defaults: new { controller = "Home", action = "Index", id = UrlParameter.Optional },
namespaces: new [] { "YourNamespace.Controllers" }
).DataTokens["UseNamespaceFallback"] = false ;

After this is done you can navigate to your application in a web browser and you will be promted by the installation view for Piranha CMS where you set up your administrator account.

Getting the models

You can now manually load the models from Piranha CMS by the page permalinks that you generate in the manager interface.

If your application controllers inherit Piranha.Mvc.SinglePageController or Piranha.Mvc.SinglePostController you can follow the guidlines of the documentation. If you are using the standard, or a custom base class for your controllers you can get the approriate model with the following code:

var model = Piranha.Models.PageModel.GetByPermalink("my-permalink") ; // For pages
var model = Piranha.Models.PostModel.GetByPermalink("my-permalink") ; // For posts

If you want your current model to extend one of the above models you can use the following generic methods.

var model = Piranha.Models.PageModel.GetByPermalink<MyType>("my-permalink") ; // For pages
var model = Piranha.Models.PostModel.GetByPermalink<MyType>("my-permalink") ; // For posts

Upgrading Piranha CMS

Before upgrading, make sure that you read the changelog to see if any breaking changes that need manual updates are included in the package. After upgrading, go to the login screen of the manager interface and if any database updates are needed for the new version you will prompted with an upgrade dialog.


Getting the source code

You can always download the complete source code from our repository at GitHub. The master branch of the repository is always the same as the current version available from NuGet, and the solution contains both the core libraries as well as the template site. The source code for the framework is distributed with the LGPL license, and the template project is distributed with the Apache 2.0 license.


Troubleshooting

If you get the following error after a clean install it's likely that the NuGet-packages where unable to update the RouteConfig.cs file during the installation.

Multiple types were found that match the controller named 'page'. This can happen if the route that services this request ('{controller}/{action}/{id}') does not specify namespaces to search for a controller that matches the request. If this is the case, register this route by calling an overload of the 'MapRoute' method that takes a 'namespaces' parameter.

To resolve this issue, manually copy the content of the provider file ~/App_Start/RouteConfig.PiranhaCMS.cs into your RouteConfig.cs