Hello Orchard – Creating a Orchard module using latest source code

What is Orchard?

Project Orchard is the latest open source CMS project by folks in Microsoft based on ASP.NET MVC platform. It has some relationship with project Oxite which is another CMS used by the MIX event website. You can read more about Orchard from the official website here. And you can also check out the official download as well as the latest build from Codeplex. It is light weight where you can do copy-paste deployment onto shared webhosting, doesn’t require SQL Server to run yet at the same time you can add functionalities as a Orchard Module.

 

Official Download

The official download dates back to March 2010 at the time of MIX 2010. The feature sets are primitive and less composite than what’s in the roadmap. It has been 4 months since the release and the team will release a official Alpha release by end of July 2010.

Having said that, the March release comes with a walkthrough which you can follow to build a customized module for Orchard. You can check out the walkthrough here.

March 2010 release

Walkthrough Document

Video walkthrough

Latest Build

In the true spirit of open source, the Orchard team chose Mercurial instead of Team Foundation Server to be the source code host of the project. Codeplex supports both source control systems maybe because of some non-.NET or non-Windows hosted there.

In the March 2010 release Modules are actually ASP.NET MVC 2 Area where else in the latest build, they are individual ASP.NET MVC Web App. The new module design makes Orchard more suitable for composition and multi tenancy, in a way like SharePoint features.

Because of this architecture change, the walkthrough mentioned above does not work with the latest build. So in this and subsequent blog post, I will share more about creating a customized module for latest build of Orchard

Downloading latest build

To get the latest build, you either download from the source tree using TortoiseHG which is a Windows based Mercurial client (instructions here) or you can download the latest changeset from the source code page at Codeplex.

image

Whenever you download source code packages as a zip file from the Web, remember to ‘unblock’ it from the file property page else Visual Studio will give you a not trusted source warning message which can be annoying at times.

image

 

Understand the Orchard architecture

I won’t dwell too deep into this as Bertrand Le Roy wrote an extensive document titled How Orchard Works here. Architects should read this document first to understand how things work.

Accessing the latest change set

image

I downloaded the latest change set as of today and from Windows Explorer you will notice there are 2 Visual Studio solution file. Note also that it has been updated to support Visual Studio 2010 solution. You also note that there is a Windows Azure solution file here but let’s check this out in my future post.

The whole Orchard application framework is inside the Orchard folder while Orchard.Web is the ASP.NET project which can be hosted inside IIS. Let’s open up Orcahrd.sln using VS2010.

image[15]

All in all there are more than 30 projects in project Orchard with Orchard.Core, Orchard.Framework and Orchard.Web at the center of this CMS. On top of that there are some core modules which Orchard needs such as the User, Pages, and Setup modules.

Build and setup a sample site

Orchard supports both SQL Server and SQLite database but for sake of debugging and troubleshooting I will choose SQL Server. Let’s create an empty database inside SQL Server called OrchardTutorialDB in the local SQL Express instance.

image

Back to Visual Studio 2010 with the project opened, press Ctrl-F5. IE will be opened and you will see the Orchard setup page

image

At this page, you need to give a name for the website and assign a website admin account. Then click on ‘Use an existing SQL Server database’ to setup SQL Server. Key in the connection string in the following format

Data Source=.\sqlexpress;Initial Catalog=OrchardTutorialDB ;User Id=myUsername;Password=myPassword;

Note: Skip and leave the Database Table Prefix empty at the moment because of a known bug with using the prefix

image

Click ‘Finish Setup’ and a few minutes later you will see the website up and running!

image

I will normally change my theme to a more presentable one.

image

Hello Orchard – Adding a new Module

Note: from this point onwards I will reuse some of the text in the Orchard Walkthrough document.

NOTE: Step 2 to 4 and 15 to 17 are very additional steps to make the walkthrough works in the new change set.

The objective here is to build a very simply Hello World style webpage themed by Orchard with a menu item on top.

Objectives:

1. A simple custom area that renders “Hello World” on the app’s front-end

2. Views in the custom area that take advantage of the currently applied Orchard theme

3. A menu item on the front-end for navigating to the custom area’s view

Follow These Steps:

1. Right-click the Modules node in VS Solution Explorer, and choose “Add > New Project…”

image

2. In the project creation screen, choose “ASP.NET MVC 2.0 Empty Web Application”

<Very Important> On the path text box, it is default to <Orchard location>\src folder. Change it to <Orchard location>\src\Orchard.Web\Modules\ folder (Screenshot below). Else Orchard will not recognize the new module.

Finally Type “Orchard.Commerce” for the area name and click [OK].

image

3. For Orchard to discover this module, you need to add a module.txt file at the project root folder and insert the following content.

name: Commerce
antiforgery: enabled
author: Patrick Yong
website: http://patrickyong.net
version: 0.1
orchardversion: 0.1.2010.0312
description: Commerce
features:    Orchard.Commerce:
Description: Commerce.
Category: Commerce

4. Modify the web.config file accordingly. Basically I added <httphandlers> and <handlers> in <System.WebServer> for MVC routing.

<?xml version="1.0"?>
<!--  For more information on how to configure your ASP.NET application, please visit  http://go.microsoft.com/fwlink/?LinkId=152368  -->
<configuration>
<system.web>
   <!--             Set compilation debug="true" to insert debugging             symbols into the compiled page. Because this             affects performance, set this value to true only             during development.    -->
   <compilation debug="true" targetFramework="4.0">
   <assemblies>
      <add assembly="System.Web.Mvc, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add assembly="System.Web.Abstractions, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add assembly="System.Web.Routing, Version=4.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
      <add assembly="System.Data.Linq, Version=4.0.0.0, Culture=neutral, PublicKeyToken=B77A5C561934E089"/>
   </assemblies>
</compilation>
<customErrors>
   <error statusCode="404" redirect="FileNotFound.htm" />
</customErrors>    -->    <pages controlRenderingCompatibilityVersion="3.5" clientIDMode="AutoID">
<namespaces>
   <add namespace="System.Web.Mvc"/>
   <add namespace="System.Web.Mvc.Ajax"/>
   <add namespace="System.Web.Mvc.Html"/>
   <add namespace="System.Web.Routing"/>
   <add namespace="System.Linq"/>
   <add namespace="System.Collections.Generic"/>
   <add namespace="Orchard.Mvc.Html"/>
   </namespaces>
</pages>
   <httpHandlers>
      <add verb="*" path="*.mvc" validate="false" type="System.Web.Mvc.MvcHttpHandler, System.Web.Mvc, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
   </httpHandlers>
</system.web>
<system.web.extensions/>
<!--         The system.webServer section is required for running ASP.NET AJAX under Internet        Information Services 7.0.  It is not necessary for previous version of IIS.  -->
<system.webServer>
   <validation validateIntegratedModeConfiguration="false"/>
   <modules runAllManagedModulesForAllRequests="true"></modules>
   <handlers>
      <remove name="MvcHttpHandler"/>
      <remove name="UrlRoutingHandler"/>
      <add name="MvcHttpHandler" preCondition="integratedMode" verb="*" path="*.mvc" type="System.Web.Mvc.MvcHttpHandler, System.Web.Mvc, Version=2.0.0.0, Culture=neutral, PublicKeyToken=31BF3856AD364E35"/>
   </handlers>
</system.webServer>
<runtime>
   <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
         <assemblyIdentity name="System.Web.Mvc" publicKeyToken="31bf3856ad364e35" />
         <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />
      </dependentAssembly>
   </assemblyBinding>
</runtime>
</configuration>

5. Right-click the newly created “Ocrhard.Commerce > Controllers” folder, and choose “Add > Controller…”

6. Name the Controller “HomeController”

7. Right-click on the “Index()” method name and choose “Add View…”

image

8. Selected the “Create a partial view” option and click [Add]

image

9. Add the following HTML to the View page: <p>Hello World</p>

10. Add Orchard.Framework and Orchard.Themes to the project reference

image

11. Add the following namespace imports to the HelloController.cs file:

using Orchard.Themes;
using Orchard.UI.Navigation;

12. Add an [Themed] attribute to the HelloController class:

[Themed]
public class HomeController : Controller

13. Add another class to create a new Menu item, you can create a new .cs file in the project root folder or add it inside the controller class

public class MainMenu : INavigationProvider
 {
        public Localizer T { get; set; }
         public String MenuName
        {
            get { return "main"; }
        }

         public void GetNavigation(NavigationBuilder builder)
        {
            builder.Add(menu => menu.Add(T("Shop"), "4", item => item.Action("Index", "Home", new { area = "Orchard.Commerce" })));
        }
}

14. Type Ctrl-F5 to build and run in VS.

15. Login as admin (using the admin account you created during setup) and navigate to the admin page

image

16. Scroll down to look for Site Configuration menu and click on Features

image

17. Voila! If you had done everything right, you will see Orchard.Commerce as a module under the Commerce category. Now click on the ‘Enable’ button.

image

18. After a moment, message(s) will appear and to try out the feature, click on Your Site on top.

image

19. Now you notice an additional item on the top menu

image

 

10. Finally click on ‘Shop’ to Navigate to this URL in the browser: http://localhost:<port>/Commerce

image

11 thoughts on “Hello Orchard – Creating a Orchard module using latest source code

  1. I like your tutorial, but C# and xml examples are not visible, probably you should change the style.

    I’m using Firefox.

  2. Pingback: Building a Staffing Website? A New Open-Source CMS to Consider

  3. This ain’t working. And it’s very ambiguous with web.config files (there’s 1 in root and 1 in views, for example) so who knows, it might be “my” fault that it’s not.

  4. Exactly what I need. Thanks. BTW, in step 12, you said: Add an [Themed] attribute to the HelloController class! What HelloController?

    I added an [Themed] attribute to the HomeController class and it work. But when I click on the “SHOP” menu, Orchard rendered only Hello World!, no styles/themes applied to new module! Could you please tell me what I did wrong?

    Thanks

  5. This almost worked for me, but I had some errors in the Orchard.CommerceAreaRegistration.cs class. The class was created as:
    public class Orchard.CommerceAreaRegistration : Area Registration {

    }
    But I had to remove the “Orchard.” from the class name in order to get it to build without errors. However, once built I did not see my new module. I’m working with version 1.3 and don’t know if that is the reason. I’m continuing on. Thanks for the detail.

  6. Hello, I followed step by step this tutorial, but always I got this error “The extension ‘Orchard.Commerce’ manifest could not be loaded. It was ignored.”
    I’m using the last version 1.4, (I’m very new in the Orchard world)
    can somebody help to figure it out this problem?

  7. I enjoy what you guys tend to be up too. This sort of clever work and reporting!

    Keep up the excellent works guys I’ve incorporated you guys to
    our blogroll.

Leave a Reply

Your email address will not be published. Required fields are marked *

*

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>