Creating an Orchard Module

In my last post, Prep-Work to Developing an Orchard Module, I outlined the steps I took to fork the Orchard Source Code and clone it to my local development machine using TortoiseHg and VisualHg.  Now that I have the Orchard Project on my machine, I’m ready to create an Orchard Module.  There is already good documentation on creating an Orchard Module from the community (Walkthrough Writing An Orchard Module – Orchard Documentation,Creating a module with a simple text editor – Orchard Documentation, etc.), but I’ll regurgitate some of it here hopefully to solidify the process in my mind and perhaps yours too!

Here’s how I created the module structure:

Creating a Module Project from the Command line:

I followed the steps outlined in the Orchard Documentation, Creating a module with a simple text editor, using the code generation module and the Orchard console to build the module project shell.

  1. Run Orchard.exe located within the bin folder of the Orchard Project (Console application)
    image
  2. Run the Orchard Instance in the browser and search in the Module Gallery for Code Generation module; install this module.
  3. Ensure the Code Generation module is enable by running the following command in the Orchard console environment:

    feature enable Orchard.CodeGeneration

  4. Finally, create the module structure by using the Code Generation command within the console environment:

    codegen module Slider

    Where Slider is the name of your module.

When finished, you should see the new module structure in the Orchard Project under the Modules Solution folder (in addition, you’ll see the module physically located in the Orchard.Web\Modules folder of the project):

image

If you now run the Orchard project, you’ll see a new feature in the modules section labeled Slider (or whatever name you chose).

image

This is coming from the Module.txt file that was created by the Code Generation:

image

If the Module.txt file did not exist, Orchard would not be able to pick up your Module and list it in the administrative section.

Also pertinent to point out, the Project includes references to Orchard.Core and Orchard.Framework among other typical MVC references:

image

And the Scripts and Styles folders all contain their own Web.config file in addition to a Web.config file in the root of the project.  These configuration files tell Orchard that any files requested from these folder should be handled by a StaticFileHandler.  The details of why this is needed eludes me right now, but suffice to say these are important attributes to displaying the content (JavaScript files, CSS files, etc.) in these folders.

So there you have it!  A module shell that provides you with the starting point for bending Orchard to your will.  Now time to harness the power of the module by doing something useful.

Advertisements

Prep-Work to Developing An Orchard Module

In my last post, I discussed the need to perform some custom development within the Orchard Platform to provide specific functionality in the form of a widget that the site owner could include in pages within the site.  The Projector Module, though very customizable, did not allow me the flexibility to inject a precise html structure based on a list of content items.  A module called Featured Item Slider from NimblePros had very similar functionality that I was looking for, so I decided to roll up my sleeves, pop the hood to all the goodness that is Orchard and dare to build (or at least adapt) a custom module.

To do that though, there are some steps to take before hand.  You need the ability to debug the code and the Web Matrix IDE is just not going to be adequate enough; especially considering my crutch to using F12 on objects in Visual Studio 2010 (Function Key F12 traces an object back to it’s declaration from within code).

Here are the steps I took to get Orchard’s source code on my machine in an attempt to build a custom module:

  1. Getting familiar with the Source Code strategy
    So I joined up with CodePlex and read up on some tutorials on using Mercurial the source control system that Orchard/CodePlex is using.  The TekPub episode to Mercurialwas a valuable resource; the video quality is poor, but the content is enlightening to new users.Installed TortoiseHg and VisualHg to allow me to pull the source code and work with the repository within VS2010.

    Steps to creating a repository for the code (using TortoiseHg):
    While the functionality is the same between versions, the tutorial shows an outdated version of TortoiseHg.  Don’t let this hinder you understanding the concepts!

    1. Create a fork in the Orchard Project and clone the forked repository (TekPub episode @ 23:18).
      Or if starting a new Project (this is not related to Orchard development but good to know):
      Create repository in solution directory of project (TekPub episode @ 5:17)
      Keeping in mind that:

      1. The .hg folder that is created is the repository
      2. The .hgignore file represents all the files Mercurial should not track.
    2. Enable Visual Studio Integration for VisualHg (TekPub episode @ 8:37)
      1. Enabled in: Tools | Options | Source-Control | Plug-in Selectionimage
      2. To commit changes right-click on the project or file and select commitimage
    3. Sending code changes back to CodePlex (TekPub episode @ 17:32)
      1. Use the Clone URL from your CodePlex fork with the Synchronize command in TortoiseHg/VisualHg.
        image
  2. Fork the Orchard Project to my development branch titled DebuggingEnvironment and Clone it to my development machine (using Steps in 1A above)
    I now have a branch of the project in CodePlex that I have cloned to my local development machine and can begin creating a module.

In my next post, I’ll explain how to actually create a development module within the Orchard Project.

Orchard’s Projector Module: the tool of choice?

Being new to Orchard, I was hoping I could minimize the learning curve and get by with just theming a site and using the out-of-the-box functionality so-to-speak to quickly get a website up and running.  I picked a theme from Script Tutorials called Mono that I wanted to implement on the Orchard platform.  While I’m still in the process of working this theme into Orchard, I wanted to share some of what I’ve learned along the way.  Keep in mind, probably less than a month ago, I had only heard of Orchard as being a viable open source platform for CMS.  I’m still only scratching the proverbial surface with Orchard.  My hope is I can retain more through sharing my experiences along the way.  If it turns out to be a help and encouragement to you, I’d love to know and may consider sharing more of my experiences working with the platform.

One problem that has broadened my understanding of the Orchard platform was coming up with a solution that would let Orchard inject a specific HTML stream to the client based on a list of Content Items.  Simple, you say, just use the new Projector Module and whip out some custom queries and your well on your way!  Well, almost.  I love the flexibility of the Projector Module and I intend to use it extensively if I become married to this platform, but I couldn’t quite get the Projector Module to succumb to my will for what I see could be a very common pattern.  Projector Module is great when you want to sequentially iterate over a list of content items and display information.  For example, if I had a Content Type consisting of Name, and ImagePath, the Projector Module could easily filter by that Content Type an produce HTML similar to the following:

<div>
	<img src="~/images/image1.jpg" name="Image1" />
	<img src="~/images/image2.jpg" name="Image2" />
	<img src="~/images/image3.jpg" name="Image3" />
</div>

But my problem was that I needed to generate output similar to this instead:

<div id="slider">
	<img src="~/images/image1.jpg" title="#htmlcaption-1">
	<img src="~/images/image2.jpg" title="#htmlcaption-2">
	<img src="~/images/image3.jpg" title="#htmlcaption-3">
</div>
<div id="htmlcaption-1">
	<h5 >Headline 1</h5> <p>Sub-Headline 1</p>
</div>
<div id="htmlcaption-2">
	<h5>Headline 2</h5> <p>Sub-Headline 2</p>
</div>
<div id="htmlcaption-3">
	<h5>Headline 3</h5> <p>Sub-Headline 3</p>
</div>

Where a Content Type consisting of Name, ImagePath, Headline, SubHeadline is used to populate the pattern above.  I could not see a feasible way to do this with the Projector Module.  I could have created two Projector Widgets on the same page I suppose; one to generate the content in the “slider” div and another to produce the other div tags; but that seems to be too expensive having two widgets essentially iterating over the same data twice!  Maybe not; but it does make it more complex for the contributor who has to keep up with it in the Administrative Section.  And what about the dependencies?  I need to make sure the page running these widgets references jQuery among other custom scripts and styles.  Using Projector for this just seemed like using a Flat-head screw driver on a Phillips-head screw.  It may do the job, but it’s probably not the best tool of choice.

This leads me to the decision maybe it’s going to require a custom module.  Reviewing similar modules in the gallery, I ran across one that essentially solved this problem.  NimblePros has produced the Featured Item Slider, a module that creates a slide show that comes very close to the functionality I was aiming for in my selected theme.  I tried using the Featured Item Slider and was mostly successful, but it wasn’t producing the *exact* functionality.  But now, I have a good idea that this is the direction I need to head toward, so I’m in the process of modifying the Featured Item Slider to create a simpler, less configurable, module that produces exactly what I need!

Stick around and I’ll share what I’ve learned as I dive into the details of Creating an Orchard Module!

When Installing Modules from the Orchard Gallery Fail…

Here’s another hiccup I’ve run across while working with Orchard and want to share it.  I’ve seen it documented a couple of times and I believe Bertrand Le Roy has resolved it in his replies.

From a fresh install of Orchard (very fresh, in fact) using WebMatrix, my very first step is to add the Designer Tools Modules, a jam up and jelly tight tool (to coin a phrase from a colleague of mine) for aiding with Theme design.

When I attempt to install the module from the gallery using the Install link (not Download link), I receive the following error:
image

Based on Bertrand’s suggested fix, I updated the Gallery Feed (located under Settings->Gallery) to use the http://packages.orchardproject.net/FeedService.svc/ feed:
image

Then re-attempted the download and …
image
I’m a happy camper!  Funny thing is though when I revert back to the original feed, it remains fixed!Well almost!  When I use http://orchardproject.net/gallery/server/FeedService.svc, I receive the following:
image

But if I append a forward-slash at the end of the URL: http://orchardproject.net/gallery/server/FeedService.svc/

It works!  So what’s the walk-away here?  A forward-slash can make all the difference is the success or failure of a module being installed.  Perhaps this feed link can get updated down the road in the Orchard project.

Orchard Lists are Modules too!

It’s embarrassing to post how long this one stumped me.  So here’s the scenario:  I’ve got my depth set and my plow trudging through some Orchard Tutorials hoping to ramp up on this in no time flat in preparation for a real estate website.  Through one of the tutorials on creating list, http://docs.orchardproject.net/Documentation/Creating-lists, I discover a discrepancy.  My version of Orchard isn’t producing the same effects as the Tutorial’s examples.  I did not have an option to create a new list of content types!  Hours later, after posting to the CodePlex discussion board, and bearing no fruit, I went for a jog, cleared my head and came back to shut down my laptop.  But just before doing so, I figured I would take one last stab at it before heading home defeated. 

Problem:
Tutorial is showing a create new list option on the dashboard which I do not have:
imageimage

Solution:
There is a List Module that must be installed and enabled. 
image

Apparently, when you install Orchard from WebMatrix, you do not get the full set of “standard” modules.  It would be awfully considerate of those providing the documentation if they were to anticipate these little diversions along the way and provide Orchard Newbies with enough information that we do not have to sift hours through the Orchard to bear such little fruit.

This has taught me a very important lesson: If you’re in Orchard and things do not look as they should be, your first inclination should be to determine if you’re missing a module!  This has bitten me twice ashamedly

A walk through the Orchard

Orchard.Net that is!  I’m taking it a step at a time.  Looking to use this platform as the start of a real estate website.  Hoping it will be smooth and painless, but…

After installing Orchard 1.4 from WebMatrix, setting up my database (SQL Server 2008) and comparing the output of the homepage with that of similar walkthrough tutorials, I discovered I was missing something that seemed useful.  As the administrator, I did not have the edit button and dashed border around my content.  How do I edit quickly?  Aside from click, click, clicking my way through the dashboard for the first time and discovering there’s a content tab for content and a widget tab for widgets both of which are on the home page.

imageContent has a publish feature where it isn’t active as soon as you save it unless you publish it.  Widgets, on the other hand, do not.  When you click save, it’s out there!  Good to know!

Problem: Edit using Content and Widget Zones

I see this when logged in as the admin in Orchard:

 image

I should be seeing this:
image

Solution:

Enabling the Modules: Content Control Wrapper and Widget Control Wrapper appears to have corrected the problem:

image

More to come..