Getting started with Orchard (for aspiring advanced user)

Nov 7, 2010 at 9:29 PM

Hi guys,

I started writing some notes back when I was getting started with Orchard 0.3; and as I rediscover Orchard 0.8, I wrote more notes which eventually turned into the following article. So, I hope it helps some people. I decided to post it here to get some feedback, and eventually transform it into a Wiki page.

The goal of this article is to ease you into Orchard. There are so many concepts to understand that I think it is necessary to give a high level view of the whole thing before digging in. So, this article starts with a common ground that any web user should understand and progressively deepens while introducing relevant technical terms. When you finish reading this, you should have a good enough understanding to start playing with Orchard (as a designer/developer) without getting confused by its high level architecture and its terminology. When introduced, each new term is put in bold so that you make sure to understand it before moving forward (TODO).

This article also contains a lot of links (TODO) to other pages with more specific explanation; so you can use it as a starting point.
For a more technical presentation, read How Orchard Works.

TODO: Many sections have very short explanation. I would like to keep the whole article short, but complete. So let me know if there are any parts that could use more words.

Looking at Orchard from outside to its most inner representation

The best way to introduce the basics of Orchard is to look at the roles that a user can have when access it: Normal user (aka reader/visitor/guest), administrator, designer and developer.

1- As a user, an Orchard website is just like any website: It starts with a front page, from which you can access other pages by following links. Depending on what the website is about, the content will vary (can be static pages, blog, wiki, e-commerce, etc.)
Figure 1.1. Picture of a website with a tree of linked boxes: front end static page at the top, below: blog box (below: comments box), wiki box, etc

2- The administrator has access to a few more aspects of the website:
a. When installing Orchard, he will see the Installation page. This step results in the creation of a database where all the content and settings of the website are stored.
Figure 2.1. Screenshot of the setup page
b. Of course, as a user, he can see the front-end as well
c. At any time, he can go to the dashboard (aka control panel/back-end) for two reasons:

  • Configure the website: Edit settings around the behavior and look of the website (or install/disable/upgrade them)
    Figure 2.2. Screenshot of the settings page
  • Edit the content of the website
    Figure 2.3. Screenshot of editing a blog post

d. Command line: It is possible to script most admin stuff from the command line, making it easy to automate certain operations
Figure 2.4. Screenshot of Orchard.exe running help command

3- The designer can modify the look of the website. He can edit the settings of an existing theme (if provided) or create one
A theme is everything that plays in the visual representation of the website. It is sometimes called skin or template. It transforms the content (user-generated data) into HTML that can be displayed in a browser. Eg: When you write a blog post, the theme defines where and how to show the menu, title, body, comments, etc.
Depending on how much customization is required, the designer may edit some or all elements of the theme.
The elements of the theme are of the following types:

  • Documents defining the layout and its zones: This is the overall representation of a page on the website (without any actual content). Eg: It says if the website should have one, two or three columns. So, a zone is a container that is part of the layout and ready to receive any content. Note that a flexible theme (like the one provided by Orchard) can adapt to hide empty zones. So, although Figure 3.1. shows a lot of zones, most of them will not be visible on actual pages because they aren't being used.
    Figure 3.1. Diagram of a theme with zones as boxes (Cf. The Theme Machine)
  • Views: Visual representation of a specific content. A view is typically a file with the extension .CSHTML or .ASPX. It provides the HTML code to use when displaying a specific type of content. So, a page with many contents (menu, blog post, comments, etc) will be created by using the composition of all the relevant individual views.
    Figure 3.2. Screenshot of a page with each content view highlighted
  • Stylesheets, Javascript and Media files: They are used to modify the look defined in the views. They are files like "Site.css", jQuery or the images for background, borders and icons
  • Widget: A web page typically presents one main content (like a blog post), but it often also has small pieces of information on the sides. Eg: a tag cloud, a list of recent posts, a twitter feed, etc
  • Layers and the binding between content to specific zones: A layer is like the description of a group of pages. Once defined, you can tell where to put each content (or widget). Eg: A layer grouping all the blog posts can be defined, then we can make a Tag cloud widget appear on the side
    Figure 3.3. Diagram of a theme with its zones filled by various content

More advanced themes may also include some programming code to further customize the look.

4- The developer has a complete insight of the architecture of Orchard and can extend it.
Orchard is organized in modules. Each module provides a building block (aka add on/plugin) to the website with a high level distinct goal. For example, you can have:

  • Extension module: Adds some (low-level) features that will benefit the website. Eg: Ability to search your content or to use an external editor to write blog posts (like Live Writer)
  • Content module: Adds everything (code and visual) required to view/edit some type of content (like blog posts)
  • Widget module: Adds a small visual content that can be displayed on the side of existing content modules (like a Tag cloud next to a blog)
  • Theme module: Changes the look of existing content modules (This is what the designer would typically create)
  • All the above: A module can have many extensions, content types, widgets and themes all in one package

Orchard is designed to be highly extensible; this means that almost anything that you interact with can be extended, replaced or disabled.
Out of the box, Orchard comes with a number of modules to provide a good user/administrator experience; but a designer/developer can change it.
Orchard v0.8 comes with only one theme (called "The Theme Machine"). However, it has enough zones to allow various arrangements. This is important because, by default, a site can only have one theme (unless you develop a module allowing more), so the theme must be flexible enough to allow pages to have different layouts. If you are not satisfied, you can copy it and add more zones.

Content

In order to fill your website, Orchard allows you to edit and display content. It comes with the ability to create pages and blog posts out of the box. But it also allows you to define your own content. This is important because you may want to have events or profiles or anything else that isn't supported out of the box. This section explains the various elements that plays into providing that capability.

  • Content: Data that is typically displayed on the front-end website. I use this term as a generic way of calling anything that is user-generated.
  • Content Type & Item: A content type is like a dynamic class; it defines a structure of data for a specific type of content. That structure can be changed, even by the administrator. A content item is an instance of content type. So, BlogPost can be a content type, and when you write one, that one is a content item.
  • Content Part: Because many content types share many aspects; these aspects can be created independently and reused in each content type. That's what a content part is. Eg: A blog post can have comments; a photo can also have comments; so, instead of implementing the "comments" feature twice, we can create it as a content part and reuse it for both content types.
  • Content Field: In the same spirit of reusability, we can have smaller types that must behave in a certain way. Eg: Most content types will need Date, phone number, email address, etc. They aren't simple properties since we can attach some behavior (like validation rules) but they aren't content parts either (too "small").

Note that a content type can only have one of each kind of content parts. But it can have many fields of the same kind. The reason is in the semantic meaning of these concepts. For example, a blog post can only have one commenting aspect and it can have many dates (creation date, last update date, etc.).

Record: In order to be able to save a content type/part (in a SQL database), it needs to be "linked" to a record. It is a class with all the properties that should be saved. Eg: A Map part must save its coordinates (Latitude & Longitude), so it will be linked to a record with these two properties; and Orchard will do the rest to load/save it. You will not have to deal with records unless you develop your own module. But it is useful to understand this concept in case you encounter it.

Welding/Composition: TODO: Give a practical example of a content type being created with parts & fields (eg: event), then a content item created, then more content parts/fields added (eg: map)

Missing features

Since Orchard is still under development and hasn't reached v1.0; there are a number of features that you may expect from a CMS but that aren't yet available. They should all be present by the time v1.0 is released (in January).

  • Still a bit buggy and slow
  • There are few modules and they have simplistic implementation
  • Only one simple theme + No mobile theme
  • No medium trust
  • Scarce documentation

Conclusion

I am going to stop here, for now. At this point, you should have a good understanding of what is Orchard. Any article talking about how to use it should be easy to understand. I still need to get into a bit more details about modules, themes and the low-level architecture of Orchard. This would be useful when you start learning how to create them.

Let me know what you think of this so far.

Nov 11, 2010 at 7:03 AM

Does this article fit in the documentation? Or should it be discarded?

Coordinator
Nov 11, 2010 at 3:55 PM

I think you should add it to the wiki or make it a blog post which we can point to from the site's home page and the wiki, whichever you prefer. Thanks for writing this.

Nov 12, 2010 at 4:52 AM

I prefer adding it to the wiki (I no longer have a blog :) ).

Would you approve my account on the wiki?

Coordinator
Nov 12, 2010 at 6:48 AM

You're in.

Nov 12, 2010 at 7:17 AM

Thanks.

I would like to create a new page in the section "Getting Started Extending Orchard", but I don't have the rights to.

Coordinator
Nov 12, 2010 at 7:19 AM

Tell me the name of the page you want to create. I'll create it for you and then you can edit it.

Nov 12, 2010 at 8:31 AM
Edited Nov 12, 2010 at 8:37 AM

Since "Getting started with Orchard" is already used (and is a bit vague), let's go for:

"Introduction to Orchard's architecture"

My second choice is: "First steps into Orchard"

Coordinator
Nov 12, 2010 at 6:30 PM

There it is: http://orchardproject.net/docs/First-steps-into-Orchard.ashx