Introduction To Orchard
Orchard is just one of many free open source, community-focused Content Management System’s built on ASP.NET MVC platform. A few other popular CMSs are: DNN, WordPress, Drupal, and Joomla. A CMS is simply a software application that helps you, the user, create, edit, organize, and publish content.
While CMSs are a great tool that comes with a handful of built-in modules to make it easy for the “admin user” there are many features that may not come with a built-in module. This is where creating a custom module would be most beneficial. There are a couple steps to follow to get your custom module up and running. I will explain them below:
- An instance of Orchard Development Environment ( How to Install Orchard CMS )
- Basic knowledge of Orchard CMS
Step 1: Installing and/or Enabling Orchard’s Command Line Code Generation
We are going to set up our custom module using Orchard’s Command Line Code Generation that comes installed by default in our Orchard Project. In order to get started we need to make sure that our site has the command line module installed and enabled.
Follow the steps below:
- Login to your Orchard site.
- Click on “Modules” in the sidebar.
- On the “Features” tab locate the filter text input and type in “Code Generation”.
- If Code Generation shows in your list of Modules make sure to click “Enable” if it is not already enabled.
If you cannot find the command line module follow the additional steps below:
- Click on the Gallery Tab
- Search for Code Generation and Install it
- Enable Code Generation
Now that we have successfully enabled and/or installed the Command Line Code Generation we can begin to set up our custom module. When we create a module using the command line we are only setting up the structure of an empty module.
To Learn More About Orchard Command Line: http://docs.orchardproject.net/en/latest/Documentation/Command-line-scaffolding/
Step 2: Creating A Custom Orchard Module
We now have to locate the command line .exe file and run it. This will be located in your Orchard.Web bin folder (\src\Orchard.Web\bin). Once you have located the correct folder you will find a file called Orchard.exe. Double click on the file to fire up the command line interface (this may take some time). In order to create a new module we will need to use the following syntax:
codegen module < module-name> [/IncludeInSolution:true | false]
Once you go back to your Orchard environment in Visual Studio you will be prompted with the dialog below. You will want to make sure to click “Reload All”. This will reload the solution and will now include your custom module you created.
If you navigate to the Modules folder in your solution you will be able to see your new Custom Module.
Step 3: Learning About The Manifest File
Inside your new project you will see a Module.txt file. This file is known as the manifest file and should be located in the root of the project. The manifest file holds this module’s metadata such as name, description, author, etc. and is important for customizing the application. Every module in Orchard is required to have this file.
The metadata comes with default values you can customize by simply editing the file itself.
When you run your Orchard Project and click on “Modules” in the admin sidebar you will find your custom module located at the top under “Uncategorized”. Below you can see that the metadata is being pulled from Name and Description in the manifest file (Module.txt). Remember to enable your module.
By default, the module category is set to Uncategorized. However, if you would like to add a category called “Custom Modules” for organization purposes and throw all your custom modules under that category it is very easy to do so. Go back to the Module.txt file and add Category: Custom Modules under Description.
It will place your new custom module under that category. If you have more than one custom module just make sure they all have a matching category name.
In order to understand go back to your modules page and scroll down the list of Modules to the category you just created called, “Custom Modules”. You will find that your module is now placed under that category.
To Learn More About Manifest Files: http://docs.orchardproject.net/en/latest/Documentation/Manifest-files/
This is how we setup any custom module we create in Orchard. Following the steps above give us a good starting point for any custom feature/module we need to create for a client.
One Last Thing To Share
As I was writing up this post I stumbled across, Orchardizer for Visual Studio. Orchardizer basically saves development time and creates files we need for Modules, Themes, Content Parts, etc.
How To Download Orchardizer:
- In Visual Studio, on the Tools menu choose Extensions and Updates
- In the Extension Manager choose and expand the Online Gallery mode
- In the search type in Orchardizer
- Click the Download button in the right-hand corner
- Once that is installed you will be prompted to restart Visual Studio
I have never used this on an Orchard Project yet I only played around with creating a Content Part while I was writing this post but I see value in the extension and plan to use it next time when I need to create a custom Content Part.