Charting the Orchard API

When first starting out developing applications with Orchard, I remember well the need for more extensive documentation and samples on the API and concepts that exist in Orchard.
I remember  how glad I was to find Piotr's blog about the most important extensibility points. Although it didn't provide in-depth details, at least it pointed me to what services there were available, which helped me enormously getting up to speed. I kind of envy these guys who seemed to "get" Orchard as of day 1. It took me a whole lot longer before I gained creative freedom to build anything I needed with Orchard.

Orchard is generally considered to have a steap learning curve for theme and module developers, even for experienced MVC developers. How come? for one thing, it depends on one's knowledge and experience with concepts like Dependency Injection, MVC, the Repository Pattern and the EventBus Pattern. But for the biggest part, it's a lack And then there's a whole new world called dynamic and shapes, alternates and drivers, and a rich set of API features. As Sebastién Ros put it: Orchard is a puzzle. Each part on its own is hard to grasp without understanding other parts. This was especially true for me with regards to content types, parts, fields, drivers and shapes. Also the liberal use of Clay and C#'s dynamic type system has given me a great deal of frustration, since I was unable to use intellisense as I am used to. I remember at some point I realized that when I had a static reference to some content part, it would behave differently when I would cast it to dynamic: I suddenly could perform other operations on it. I was so confused.

However, since day 1 I saw the potential, the beauty, the power that Orchard beholds. And yet it was sometimes a love/hate relationship, frustrations of not understanding, while loving the architecture and its richness. I have never seen a .NET CMS that is free to use with such a great looking backend and is as modular as Orchard and built on top of the MVC framework.
As amazing Orchard is as a framework and application, to be really succesful it needs a large community that will be able to use it. I know of developers who tried Orchard for a few months, but then walked away because it was just too hard to be productive. There simply isn't enough documentation that goes beyond the simple examples that we have today.

To help change that, I started out with an end-to-end turorial: Writing a Webshop Module from scratch, featuring a multi part series on how to write a real world module from beginning to end (although the tutorial is not quite finished yet).
Although the tutorial is a nice introduction to ORchard develoipment, what is still lacking is an extensive list of API's and concepts, each one explained in isolation as well as examples and tutorials to see how everything fits together.

This series of posts is an attempt at charting and documenting Orchards's most useful concepts, services and features as I come accross them during real world development.

Authentication & Authorization 

API

  • IAuthenticationService
  • IAuthorizationService
  • IMembershipService
  • IPermissionProvider
  • OrchardSecurityException

 

Scenarios

  • Implementing your own user registration & user profile
  • Protecting your controllers

 

Related articles

Background tasks

API

  • IBackgroundTask
  • IScheduledTask
  • IScheduledTaskHandler

 

Scenarios

Related articles

Caching

API

  • IVolatileProvider
  • IVolatileToken

 

Scenarios

Related articles

Content Management

API

  • IContentManager
  • IContentDefinitionManager
  • IContentHandler
  • IContentPartDriver

 

Scenarios

  • Creating your own content editor page
  • Allowing users to manage content on the front-end

 

Related articles

Data access, mapping & migrations

API

 

Scenarios

  • Data access without the content type system using IRepository<T>
  • Data access with Entity Framework and connecting to non-Orchard tables
  • Creating the database schema using a migration class

 

Dependency Injection

API

  • IDependency
  • ISingletonDependency
  • IUnitOfWorkDependency
  • ITransientDependency
  • Component
  • Autofac.Module

 

Scenarios

Related Articles

Event Bus

API

 

Scenarios

Related articles

Messaging

API

  • IMessagingChannel

 

Scenarios

Related articles

Misc

API

 

Scenarios

Related articles

Modules

API

  • Feature

Scenarios

Related articles

Navigation

API

  • INavigationProvider

 

Scenarios

  • Integrating with the Admin menu

 

Related articles

Request filters

API

  • IFilterProvider

 

Scenarios

Related articles

Shapes

API

  • IShapeTableProvider
  • IShapeFactory
  • IShapeDisplayEvents

 

Scenarios

Related articles

Testing

API

Scenarios

Related articles

 

Tags: orchard, API, Extensibility, Documentation, Tutorials

13 Comments

  • Josh said

    <p>I love what you're doing. Orchard's official docs can be contributed to using GitHub. Why not add your info there to keep it all in one place?</p>

  • Mel said

    <p>I hope this will be more practice than MSDN style docs! I was thinking about doing this myself but it would take me at least another year to get to grips with it first!</p>

  • Sipke Schoorstra said

    <p>Thanks! Yes, creating an MSDN-style docs sounds like a great idea! It would definitly be easier to maintain then using a blog. Do you have some framework in mind which we could use?</p>

  • Sipke Schoorstra said

    <p>That is definitely a great idea. More hands move mountains more easily! That said, I'm using this site as a scrapbook of sorts for now, trying things out. When it gets more substantial, I'll definitely contribute. Thanks!</p>

  • Sipke Schoorstra said

    <p>Absolutely. The intent is to make the API visible in its entirety, while at the same time isolating each feature and providing practical examples on how some feature may be used, including background information. I'm looking for a solution where we may find information easily. Some sort of MSDN framework, or wiki, may be quite suitable for this. What do you think?</p>

  • pszmyd said

    <p>Hey Sipke - just recalled I wrote a similar (covering smaller part of the API, though, but with a little bit more description) article a while ago. <a href="http://szmyd.com.pl/blog/most-useful-orchard-extension-points#.T5iOIat1Dng" rel="nofollow">http://szmyd.com.pl/blog/most-...</a> I think joining forces would be a good thing;)</p>

  • Sipke Schoorstra said

    <p>Hey! I know, that's the exact url I referenced in the intro of this page :)<br>Joining forces would be a good thing indeed. What do you propose? Perhaps setup a central wiki or other docs engine on which we can work?</p>

  • pszmyd said

    <p>Orchard docs are kept on GitHub - I guess it's the best place to start working on the API description: <a href="https://github.com/OrchardCMS/OrchardDoc/tree/master/Documentation" rel="nofollow">https://github.com/OrchardCMS/...</a></p>

Comments have been disabled for this content.