During the past 2 evenings I've been reading an Orchard Book, called Orchard CMS Up and Running. This is the first and only book on Orchard right now so I was excited to see it on the list of available books for the O'Reilly Blogger Review Program. The book is only 132 pages, but the description says "You’ll create, manage, and display dynamic content with out-of-the-box functionality, and then build themes, modules, and widgets to customize the site." That is quite an impressive statement made by a 132 page book.

For Web Developers

Orchard CMS Up and RunningOrchard CMS Up and Running clearly states the book is for web developers and the book supports that claim by choosing to work with the Orchard Source Code and with the inclusion of later chapters that discuss developing Orchard Themes and Modules. Examples include writing C# and Razor code to create a very simple theme, custom field, and custom widget. The book discusses shape overriding and creating alternate shapes and wrappers.

Let me say right now that at 132 pages you are getting broad strokes and expected to be able to do a lot of things on your own with few pictures and very little guidance. You better be able to download, install, and get Orchard up and running using Visual Studio and IIS on your own. If you want to clone the Orchard Repository and work from the source code using Mercurial, you better know how to do it. An understanding of the layout and structure of the Orchard Source Code is also somewhat assumed, because you will be navigating it yourself as you create themes and modules and override shapes.

In general, the book has no pictures of Visual Studio, Windows Explorer, and the Command Line where you will be doing a lot of the development and initial set-up of the environment. This may make it difficult for some to visualize what needs to be completed and where to add various drivers, handlers, views, and other assets when dealing with Orchard Development. There isn't any hand-holding here so just be prepared.

Building an Orchard Website

Once you have set-up your development environment and have Orchard CMS Up and Running ( pun intended ), your goal is to build a basic website for a band. You create various pages to display a blog, about us, bios of band members, image gallery, list of events ( gigs ), etc.

Daisy's Gone Website in Orchard CMS

Although you do create a theme, the theme is really just a spin-off of The Theme Machine that comes with Orchard. It's not going to look pretty, but you'll learn the basics of creating Orchard Themes, overriding shapes, etc. There is decent coverage of Zones, Layers, and Placement.info file, albeit most of this can be found in the Orchard Documentation.

The book walks you through downloading a few modules from the Orchard Gallery to display a Bing Map, Image Gallery, and Contact Form. Again, there is no walkthrough of installing and configuring these modules as well as no pictures to guide you through the installation and configuration. The book essentially mentions it will use the modules and provides a small paragraph or two that attempts to guide you through the process. In the end you see a snapshot of the web page with the image gallery, Bing Map, and contact form magically working. As mentioned in the book, you'll have to enable messaging and email messaging in Orchard for the contact form to email you the new contacts, but there is no guidance in the book to accomplish that task either.

Orchard doesn't provide everything out of the box that this website needs so the author walks you through the creation of a custom module ( field ) as well as a widget. I love the examples, but again, the book jumps you from running the Code Generation Module to individual code snippets and there just needs to be more overview and pictures to show what is happening here to put the code snippets in context. In all seriousness, the code generation tool creates a C# library project with a certain structure and has the option to include it in the Orchard Solution ( which the author doesn't use and I don't know why ). This is briefly mentioned, but there are no screenshots to show what this looks like and hence you better figure it out.

In the end, I just don't you will be able to accomplish building the website given the instructions unless you have a decent understanding of Orchard.

The Source Code

After reading the book I was intrigued about the source code. I wanted to get it up and running on my development machine to look at the custom theme, module, and widget. Unfortunately, as of the morning of 6/22/2012, after cloning the source code it won't compile. When looking through the source code I also didn't see a custom module, called Contrib.PlacesField, that was built in the book. I went to the Orchard Galley in hopes of finding it there, and it doesn't appear there either.

So, I went ahead and created my own Orchard 1.4.2 website and copied over the AppData, Media, and Modules folder to at least get the website running locally. Again, there is no Contrib.PlacesField Module anywhere in the source and there is no custom theme being used - it is The Theme Machine. I did get it running, but too bad the author did not provide a username and password to actually administer it. I could hack it since I am running it locally, but this is companion material for the book and I don't think I should have to hack it.

I am assuming the author didn't expect anyone to download it?


Overall, I love the concept of this book - creating an Orchard CMS Website from scratch using several built-in features as well as the creation of custom modules, widgets, and a theme to show the extensibility of Orchard. I even like the idea of creating a band website that would have a blog, gallery, list of gigs, etc. It is a great idea.

Unfortunately, the book takes too many shortcuts. If the book really assumes you have no knowledge of Orchard, I don't think you'll be able to truly create the website. And, the fact that the companion source code is not working, doesn't appear to have the custom module and theme, and we don't know the username and password just worsens the problem.

As it stands the book takes a middle-of-the-road approach that won't really please non-developers or developers. It doesn't provide enough context to the development of modules and themes that realistically you can't get from the documentation. It also doesn't provide enough hand-holding for non-developers that want to learn how to create an Orchard website without doing development. Fill in these gaps and you have a good book.