Orchard CMS Extension: Creating Modules

This is a continuation of a series of articles on the development of their own sites based on the Orchard CMS content management system. The first articles of this series can be found at the following links:

• How to create your website from scratch using Orchard CMS. Part 1. Introduction to Orchard CMS
• How to create your website from scratch using Orchard CMS. Part 1. Introduction to Orchard CMS (cont)
• Architecture Orchard CMS. Basic concepts
• Architecture Orchard CMS. Basic concepts. Layout Concepts (cont)
• Architecture Orchard CMS. Basic concepts. Security and Development Concepts (cont 2)
• Orchard CMS Extension: Creating Content Types
• Orchard CMS Extension: Creating Widgets

This article will focus on expanding the site based on Orchard CMS through the creation of modules that can be reused on other Orchard sites.

Introduction

Modules in Orchard are extension sets that can be packaged in a special way for reuse on other sites running the Orchard system. Orchard modules are implemented based on the concept of Areas of the ASP.NET MVC framework. Areas in ASP.NET MVC are a kind of sub-sites that contain a complete set of all functions that allow the sub-site to work separately from other sections or components of the site. A module in Orchard is an ordinary area with a special manifest file. The module can use the Orchard API, but is not required to do this.

Module structure generation

Before creating the file structure of your module, you need to download, install and enable the code generation function in Orchard. For more information on this feature, see this article .

Once you enable the code generation feature on your Orchard system, open a command prompt and create the HelloWorld module using the following command.

codegen module HelloWorld

Manifest modification

You should now have the HelloWorld folder in the Modules folder of your project with the Orchard site. In this folder you can find the module.txt file, open it and fill it as shown below:

name: HelloWorld
antiforgery: enabled
author: The Orchard Team
website: http://orchardproject.net
version: 0.5.0
orchardversion: 0.5.0
description: The Hello World module is greeting the world and not doing much more. 
features:
    HelloWorld:
        Description: A very simple module.
        Category: Sample

This text describes your module for the system. For example, some information from this text will be used in the administration panel when displaying the module.

Important. Use spaces to indent, but don't use tabs.

Adding a route

As an example, suppose your module should be able to handle the / HelloWorld address relative to the Orchard site. In order to determine what needs to be done when the user navigates to the specified address, you must determine the route. To do this, create the Routes.cs file in the HelloWorld folder, as follows:

using System.Collections.Generic;
using System.Web.Mvc;
using System.Web.Routing;
using Orchard.Mvc.Routes;
namespace HelloWorld {
    public class Routes : IRouteProvider {
        public void GetRoutes(ICollection routes) {
            foreach (var routeDescriptor in GetRoutes())
                routes.Add(routeDescriptor);
        }
        public IEnumerable GetRoutes() {
            return new[] {
                new RouteDescriptor {
                    Priority = 5,
                    Route = new Route(
                        "HelloWorld",
                        new RouteValueDictionary {
                            {"area", "HelloWorld"},
                            {"controller", "Home"},
                            {"action", "Index"}
                        },
                        new RouteValueDictionary(),
                        new RouteValueDictionary {
                            {"area", "HelloWorld"}
                        },
                        new MvcRouteHandler())
                }
            };
        }
    }
}

A route is a description of the relationship between a URL and controller actions. The above code associates a HelloWorld address with a HelloWorld realm that has a Home controller with an Index action.

Controller creation

The created module contains the Controllers folder, ready for creating new controllers. Create the following file in this folder and name it HomeController.cs:

using System.Web.Mvc;
using Orchard.Themes;
namespace HelloWorld.Controllers {
    [Themed]
    public class HomeController : Controller {
        public ActionResult Index() {
            return View("HelloWorld");
        }
    }
}

This code defines the controller that will handle requests for the HelloWorld address. The default action, Index, requests a view of what should be displayed on the page at the request of the user.

Note the controller’s Themed attribute. This attribute allows you to display data with the current custom theme.

Create view

In the Views folder, create the Home folder, and in it add the following file called HelloWorld.cshtml:

@T("Hello World!")

This file defines the main content of our view. All other content on the page will be created based on the current theme and settings of the Orchard website.

Pay attention to the use of the T helper method, which allows you to make this view localizable. This is a useful feature to keep in mind.

Adding new files to the project

We are almost ready to complete the creation of the first module. The last remaining task is to tell the system about the set of files necessary to create the module during dynamic compilation.

Open the HelloWorld.csproj project file in any text editor and add the following lines after one of the tags.

Also, add the following content to the ItemGroup section, which already has several Content tags:

Module activation

Finally, you must activate your new module. At the command prompt, type:

feature enable HelloWorld

You can also do activation through the Modules section in the administration panel of the Orchard website.

Module usage

Now you can follow the link / HelloWorld regarding your site and see that our module is working and welcomes us with a message.

Conclusion

In this article, we examined the simplest example and the basics of creating separate modules for the Orchard CMS content management system. Creating a module for Orchard is very simple. Modules in Orchard have automatic support for themes, activation and deactivation mechanisms.

In the following articles, we will look at some other aspects of working with modules in Orchard CMS: packaging, distribution, installation, and management of modules.