Weâre about to start building an Orchard website. Weâll create some content. Weâll manage some content. Weâll change the way our site looks and behaves. Weâll write some code to extend the functionality thatâs available out of the box. Though we could perform all of these tasks without ever looking at the Orchard source, weâre .NET developers. Weâre most comfortable in Visual Studio, so why wouldnât we start there?
Though itâs not entirely necessary, itâs my preference to build modules, create themes, and manage my Orchard sites all within the context of the full Visual Studio 2010 Orchard solution. Aside from being able to debug the site with Visual Studio, having the source handy also provides a great reference when creating your own Orchard extensions. Weâll learn how to develop extensions in the chapters ahead.
Orchard extensions are known as modules. Creating a module requires writing code, typically C#, but any .NET language will work. You could write that code in Notepad or any text editor of your choice, but that wouldnât be the most efficient way to work. In this chapter and those that follow, I assume that youâll be working with Visual Studio 2010 Professional or higher.
The Orchard documentation contains tutorials on how to perform tasks, such as creating modules, without Visual Studio. While it certainly is possible to do so, itâs impractical to consider this approach for all but the most basic of Orchard workflows. You could use the Express editions of Visual C# and Visual Web Developer. However, you wonât be able to open the master solution. Express editions donât support mixed project type (web and class library) solutions.
Note
A $500 IDE might seem to be an expensive barrier to entry for an open source project such as Orchard. To lower the bar, the Orchard team has provided documentation and tooling that supports non-Visual Studio workflows. The open source IDE MonoDevelop is probably the best alternative, as you can work within the master Orchard solution.
There are two ways to get the Orchard solution onto your local development environment. The simplest way is to go to the Orchard downloads at CodePlex.com, which is Microsoftâs open source project hosting site. Though I sometimes use the source control option described below for my Orchard development, Iâm instead going to use a packaged release for this book. That will guarantee weâre all using the same source. The solution Iâm using for this book can be found at http://orchard.codeplex.com/releases/view/74491.
With each release (major or minor), Orchard zip files are made available on this page. One is a precompiled version of Orchard, which is optimized for users who want to deploy Orchard and wonât be coding extensions for the site. This package is labeled Orchard.Web.1.4.0.zip. At the time of this writing, 1.4.0 is the current version. This ZIP file appears under the heading âRecommended Download.â
Note
The URL http://orchard.codeplex.com/releases/view/74491 will always point to the 1.4.0 release. Click the âDownloadsâ tab on the page to find downloads for the latest version as it may have changed by the time this book is published.
A second ZIP file download is a snapshot of the Orchard source code as it existed for the release. This package is labeled Orchard.Source.1.4.0.zip. Download this zip file and extract it to work with the most recent and stable release of Orchard. This ZIP file appears under the heading âOther Available Downloads.â Each release will have different zip files available, but the web and source downloads should be consistently available.
As an alternative, you could get the Orchard source by cloning the source control repository. This is the method I prefer for module development, as it guarantees that I will be developing against the most recent committed changes. Of course, there is a risk that a feature in the current codebase will not make the final cut. For this reason, to follow along with the examples in this book you should download the source as described previously in this chapter. However, Iâll describe how to clone the source later in case you wish to try that option instead.
The Orchard team uses the distributed version control system (DVCS) Mercurial. You donât need to understand much about Mercurial (Hg) in order to use it to get the Orchard source. I wonât cover anything beyond where to download Mercurial and the two commands youâll use with Mercurial and Orchard. If you would like more information on Mercurial, I suggest reading Mercurial: The Definitive Guide by Bryan OâSullivan (OâReilly).
Mercurial is an open source project and is freely available at http://mercurial.selenic.com/. There is a Windows shell extension called TortoiseHg, which allows you to access common commands by right-clicking on folders in Windows Explorer. When you download and install TortoiseHg, the command line client is also installed. After running the installer, open up a command prompt and enter the following command:
hg clone https://hg01.codeplex.com/orchard Orchard
The clone command in Mercurial is loosely analogous to a checkout command in Subversion or Team Foundation Server. One significant difference is that cloning copies the entire repository locally. With a DVCS such as Mercurial, there is no centralized repository.
The first argument passed to the clone command is the URL where
the repository may be found. The second is the name of the local
directory to where your repository will be copied. This path is relative
to the directory from which you ran the hg
command. In other words, if the command
prompt opened into C:\users\John,
youâd have a new folder: C:\users\John\Orchard.
Note
If the hg command was not recognized by Windows, it is likely that the path to hg.exe was not added to your systemâs path environment variable. By default this path is C:\Program Files (x86)\Mercurial.
If you choose to obtain the source by way of cloning the repository, itâs a good practice to get the latest changesets, or commits, to the repository. Open a command prompt to the directory into which you cloned Orchard and run the following command:
hg pull
The pull
command will get
the latest version of the Orchard sources. However, Mercurial doesnât by
default add updates into your working copy. To update your local
repository with any changes found during a pull, run the following
command:
hg update
If you navigate to the directory where you either unzipped the source package or cloned the Mercurial repository, you should see two directories src and lib. Open up the src directory and locate the file Orchard.sln, which is the Orchard solution. Open this solution file and build it.
After youâve successfully compiled the Orchard source, youâll need to create a virtual directory in Internet Information Services (IIS). Name this virtual directory âOrchard.â The physical path of the virtual directory should be set to the location of the Orchard web project. If you copied the Orchard source to a directory c:\dev\Orchard, then the physical path would be c:\dev\Orchard\src\Orchard.Web.
Alternatively, you could simply use the ASP.NET Development Server
that ships with Visual Studio. In fact, the default settings of the
Orchard solution are to run the Orchard.Web
project using this server. While,
generally speaking, the development server should be adequate for the
purpose of Orchard site development, I prefer to work with IIS when
possible. IIS will be what you use in production, so youâre more likely
to catch certain issues in development with a local IIS setup.
After youâve created the virtual directory, open up a web browser and navigate to http://localhost/orchard. If you are using the ASP.NET Development Server, simply run the Orchard.Web project using Ctrl+F5 to start the site without debugging (or just F5 to start with debugging). You should see the screen in Figure 1-1.
Note
The very first run of an Orchard site will probably seem slow as some of the dynamic components are compiled and cached.
The Get Started page (Figure 1-1) requires you to provide a few quick details to get your Orchard site up and running. The first three questions ask you to name your site and provide an administrative username and password. These values should be straightforward. You then have the option to select a SQL Server Compact or full SQL Server (or SQL Express) database. Typically youâll choose SQL Server Compact for development only, but a low traffic site might make do with a SQL Server Compact database.
Create your new site with the name âDaisyâs Gone.â Revisit the Preface to remind yourself of the purpose of our site. You should also change the default admin name to something identifiable, like âjzablocki.â Make this change so that when content, such as blog posts or event listings, is added to the site, the name of the author isnât âadmin.â Weâll also opt to use SQL Server Compact for storage since weâre setting up this site for development purposes.
Note
An advantage of using SQL Server Compact is that youâre easily able to reset an Orchard site back to its starting state (the Get Started page) by deleting the App_Data folder containing the siteâs local database. On my system, this path is C:\dev\Orchard\src\Orchard.Web\App_Data\Sites. Resetting the site is useful when you want to ensure a clean slate for new site development.
The final question on the Get Started page involves selecting an Orchard recipe. Recipes are preset site configurations and are simply XML files stored in a well-known path. Itâs also possible to create your own. The default Orchard setup includes three:
- Default
Includes frequently used Orchard features. This recipe is suitable as a starting point for most sites.
- Blog
Creates an Orchard site to be used as a personal blog.
- Core
Configures Orchard to have only the minimum required features. This recipe is much better for Orchard development than for site creation.
Though the âCoreâ recipe is suitable for module development, weâre going to use âDefaultâ since weâre going to be building a fully functional site. After youâve answered these five questions, click the âFinish Setupâ button. You should see a modal progress bar appear with the message âCooking Orchard Recipeâ (see Figure 1-2).
After the recipe has finished cooking, youâll be redirected to your siteâs home page (Figure 1-3). Youâll see the site name that we entered on the âGet Startedâ page in the upper-left corner and a series of text sections, each with a title and some content.
At the very bottom of the home page, youâll see the default templateâs footer with a few links. The last link is labeled âDashboard.â Click that link to get to the admin pages for your site. When you click through, youâll land on the admin home page. This page simply has links to finding more information on Orchard. The functionality for managing content is accessible via the menu on the left side of the screen. Weâre going to explore the admin pages in more detail in the chapters ahead. For now, weâll just take a quick tour of the basics.
Start by clicking the âContentâ link on the menu. This is the admin page where youâll manage content, such as your siteâs home page (Figure 1-4). There are three tabs on this page, which are described here. (Donât worry about the new terms in this chapter; weâre going to revisit them over the next few chapters.)
- Content Items
Single piece of content, such as a blog post or an event listing.
- Content Types
Blueprints for content items. Defines the attributes and behavior of the content items that youâll create using the admin tool.
- Content Parts
Reusable pieces of functionality that may be used to compose content types.
To get a sense of how content is created using these tools, click the Create New Content button in the upper-right corner of the page. Youâll be taken to a page where you are shown two links: Page and Projection. Select Page. Youâll then arrive at the page shown in Figure 1-5.
Right now, our site has only the home page. Weâre going to use the New Page form to add an About page. For the title, enter âAbout Daisyâs Gone.â Then add some content describing the band. Weâll also check the option to âShow on main menu,â which will add a tab to the siteâs main navigation. Checking this option enables an additional textbox for setting the menu text. Enter âAbout.â
Youâll then have the option to set a âCreated Onâ timestamp. Weâll let this default to the current date and time. Weâll also choose to âPublish Nowâ rather than select a future date via the âPublish Laterâ option. The Save button will allow you to save your work without having it appear on the site.
After you publish your page, click the Your Site link in the upper-left corner of the admin pages. Youâll be taken to the home page. Notice the new âAboutâ link that has been added to the menu. Your new page is accessible via that tab (Figure 1-6).
Note
When working with a CMS such as Orchard, itâs useful to keep one browser tab open to the Dashboard and a second open to your site. This practice will allow you to Ctrl+Tab between tabs to see your changes on the live site without navigating away from your current admin location.
Widgets are UI components that may be added to some or all pages of an Orchard site. Click on the âWidgetsâ menu item to manage these components. On this page, youâll see a listing of layers and zones.
- Layer
Set of rules that define when widgets will appear.
- Zone
A placeholder into which widgets may be inserted.
In Chapter 4, weâll learn about zones, layers, and layouts in detail. For now, know that a theme defines a siteâs layout and a layout defines which zones are available. The listing of zones you see on the âWidgetsâ admin page were defined in the default theme, which is called âThe Theme Machine.â Layers define rules for which zones will be active.
Notice that the zones TripelFirst
, TripelSecond
, and TripelThird
have links with the text âFirst
Leader Aside,â âSecond Leader Aside,â and âThird Leader Aside,â
respectively. If you click over to your siteâs home page, youâll see
that these are headings on the three zones at the bottom of the page
(Figure 1-3). Click through âFirst
Leader Asideâ and youâll find yourself on a page where you can edit the
HTML page of this widget. Appropriately, this is called an HTML
Widget. If you click the âAddâ button
next to any zone, youâll see âHTML Widgetâ listed as an option for
each.
As we learn to create and manage content, weâll go over these
options in more detail. For now weâll take a quick look at changing
widgets. Click on the HTML
widget
under âTripelFirst.â Enter the title âNews and Notes.â Click on the
bulleted list in the HTML editor and enter some news or some notes. Save
the changes and visit your siteâs home page again. You should see your
new content reflected on the home page (Figure 1-8).
Note
You might be wondering why the third set of zones are named âTripelâ and not âTriple.â Itâs not a misspelling. The zones are a sort of inside joke and a tribute to Tripels, which are a particular style of high alcohol, strong pale ales.
A great deal of functionality is available for an Orchard site by downloading and installing Orchard modules. Clicking on the âModulesâ admin menu option at first reveals the set of installed modules under the âFeaturesâ tab. The âDefaultâ recipe we chose to setup our site has influenced this listing, as recipes can instruct the Orchard software to include different modules. Weâll explore the âFeaturesâ tab in more detail when we write our first custom module.
We want visitors to know where to find the band on rehearsal nights, so weâre going to include an embedded Bing map that will display a push pin at this location. Weâll place this map on the home page only. Bing Maps arenât out of the box Orchard functionality, so weâre either going to have to code a solution or find one thatâs already coded for us. Fortunately, the work has already been done.
Click on the âGalleryâ tab; youâll see a listing of modules available for download and installation. Search for âBing Maps.â There will be a few results. The one we want is a module named âBing.Mapsâ that was authored by Orchard project lead Bertrand Le Roy. Click âInstallâ to download and install the module. After it is installed, youâll be prompted to enable it. After you enable it, you will be able to add it to a zone.
Note
At the time of this writing, there is a bug that might lead to a âPackage installation failedâ error when installing a theme or module from the Gallery. If you get that message along with a note about permissions errors, click SettingsâGallery and set the gallery feed URL to http://packages.orchardproject.net/FeedService.svc/.
Return to the âWidgetsâ admin page. Change the âCurrent Layerâ drop-down box from âDefaultâ to âTheHomepage.â Locate the zone âTripelThird.â Click âRemoveâ to delete the existing HTML Widget from that zone. Click âAddâ and select the âBing Map Widgetâ from the list of possible widgets. Enter the title âWhere Daisyâs Gone Practicesâ; a latitude and longitude of 42.375,-70.983; and width and height of 300Ã200. Set the âZoomâ level to 10 and click âSave.â If you navigate to the site home page, you should now see a Bing Maps widget where before there was placeholder text (Figure 1-9).
Weâve seen how to manage content. Now weâll look briefly at who can manage content. The âUsersâ admin feature contains forms for managing users and roles. Creating a user is a relatively straightforward process. Click âAdd New Userâ and enter a username, email, and password. You are also able to add users to roles. There are a number of predefined roles that are part of a standard Orchard installation.
- Administrator
Has full control over a site and its content
- Editor
Can edit and publish, but not create content
- Moderator
Can validate user-generated content, such as comments
- Author
Can create and publish content
- Contributor
Can write, but might not be able to publish content
There are also roles defined for Anonymous and Authenticated users, but membership is based on whether a user is logged into the site. These roles are not assignable. New roles with custom permissions may also be created. The âAdd a roleâ button is accessible via the âRolesâ tab. When creating a new role, you select the permissions you want to be available for users in this role.
Weâre going to create two users in addition to our administrator, who in my case is named âjzablocki.â Click âAdd new userâ and enter the username âgcocca.â Check the âEditorâ and âAuthorâ roles and save the new user. Create another new user with the username ânsilviaâ and check the role âModerator.â Save this user. Gregâgcoccaâwill now be able to create, edit and publish content. Ninoânsylviaâwill be able to moderate user generated comments.
One additional user setting to be aware of is under the âSettingsâ section of the admin menu. Click SettingsâUsers and youâll find additional user management settings. You can allow users to self-register, reset their own passwords, verify email addresses, and go through an approval process before having authenticated access to the site. Weâll stick with unauthenticated comments for our content and leave all options unchecked.
Weâve now seen how to get an Orchard site up and running from the Orchard source. Weâve created and edited content. Weâve downloaded a module from the Orchard Gallery and added it to our home page. A simple site could be built and maintained using what little weâve learned so far. Our site wonât be too complicated, but it will require some basic customization. In the chapters ahead, weâre going to learn how to unleash the power and extensibility of Orchard.
Get Orchard CMS: Up and Running now with the O’Reilly learning platform.
O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.