Orchard CMS extension: module creation

This is a continuation of a series of articles on the development of your own sites based on the Orchard CMS content management system. The first articles in 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. Safety and development concepts (cont 2)
• Orchard CMS extension: creating content types
• Orchard CMS extension: creating widgets

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

Introduction

Modules in Orchard are sets of extensions 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 (Areas) of the ASP.NET MVC framework. Areas in ASP.NET MVC are a kind of subsites that contain the full set of all functions that allow the subsite 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 so.

Module structure generation

Before you create 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 function in the Orchard system, open the command line and create the HelloWorld module with the following command.

codegen module HelloWorld

Manifest Modification

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

  name: HelloWorld
 antiforgery: enabled
 author: The Orchard Team
 website: http://orchardproject.net
 version: 0.5.0
 orchardversion: 0.5.0
 description: Hello world module. 
 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 for indents, but do not use tabs.

Adding a route

As an example, imagine that 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 a 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<RouteDescriptor> routes) { foreach (var routeDescriptor in GetRoutes()) routes.Add(routeDescriptor); } public IEnumerable<RouteDescriptor> 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 connection between a URL and a controller action. The above code links the HelloWorld address to the HelloWorld area, which has a Home controller with an Index action.

Creating a controller

The created module contains the Controllers folder, ready to create 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 as requested by the user.

Pay attention to the Themed attribute of the controller. This attribute allows you to display data with the current custom theme.

Creating a view

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

 <h2>@T("Hello World!")</h2> 

This file defines the main content of our presentation. All the rest of the page content will be created based on the current theme and settings of the Orchard site.

Note 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 needed to create a module during dynamic compilation.

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

 <ItemGroup> <Compile Include="Routes.cs"/> <Compile Include="Controllers\HomeController.cs"/> </ItemGroup> 

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

 <Content Include="Views\Home\HelloWorld.cshtml" /> 

Module activation

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

  feature enable HelloWorld 

You can also activate via the Modules section in the Orchard administration panel.

Use of the module

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

Conclusion

In this article, we reviewed the simplest example and the basics of creating separate modules for the Orchard CMS content management system. Creating an Orchard module is easy. Modules in Orchard have automatic support for themes, the mechanism of activation and deactivation.

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