Shape/template naming conventions?

Topics: General
Aug 8, 2012 at 3:11 PM
Edited Aug 8, 2012 at 7:58 PM

I'm new to Orchard and maybe I'm being stupid, but I've read through the documentation on Accessing and Rendering Shapes and I cannot figure out how to name shapes and templates.  They provide rules to create the shape name from the template name, but how do you come up with the template name?

  1. When do I use a directory?  Is it optional?
  2. What "magic strings" are available (edit, summary, etc.)?
  3. How do you order everything?  Seems like the order varies between shape names and templates....  (Content_Summary__BlogPost vs. Content-BlogPost.Summary)
  4. How does Orchard determine specificity for alternates?  Their example uses hello.world-orange.cshtml but what if I also had a hello.world-blue.cshtml.  What does the color even mean?
  5. How do you determine all the different tokens that are needed to properly name a given shape?

As a new user, I feel like this is easily the murkiest part of Orchard.  Thanks for any help!

Edit: Change bullet points to integers.

Developer
Aug 8, 2012 at 6:15 PM
Edited Aug 8, 2012 at 6:15 PM
  1. Using a directory is optional, although I don't think directories work in all cases except for shapes created from the drivers (e.g. either use Parts/MyShape.cshtml or Parts.MyShape.cshtml). If you would create a shape from another place (e.g. a controller), always use the dot instead of dash (e.g. MyShape_Object should be templated as MyShape.Object.cshtml, not MyShape/Object.cshtml. However, I'm not sure if this is entirely correct. Try it :).
  2. The "magic strings" you are feferring to are called display types. In theory, you can come up with any display type you want to. The way it is used is as follows: when you invoke the BuildDisplay method on the ContentManager object, you can specify the display type. So the caller of that method determines what display type will be used. This display type is used in placement.info files to match certain shape configurations. Now, most of the times BuildDisplay is invoked by the ItemController of the Contents module, since most of the time you will be rendering content. This controller uses the following display types: "Detail" and "Summary". The AdminController of the Contents module uses "SummaryAdmin" when rendering a list of content items. If you were to write your own controller that renders a content item or a list of items, you could use any display type you want.
  3. I don't understand this question.
  4. I don't know how alternates are ordered, but the first alternate that can be found is used. So as a general rule of thumb, the more specific alternates will be found first. What determines the specificity, I don't know. I guess the first one that shows up in the list of alternates of a shape.
  5. The name of a shape is determined by its name :) So if you create a new shape using IShapeFactory, e.g. Shape.MyShape, "MyShape" will be the name. As for shape alternates, that's the job of any IShapeTableProvider implementation, of which many exist across all of the modules. One provider will add an alternate for content URL, another will add  an alternate for the zone and widget type, etc. The possibilities are endless, since you can define an alternate based on anything and everything. Check out the source code and you'll find many implementations. For example, checkout Orchard.Projections/Shapes.cs

 

Aug 9, 2012 at 2:33 PM
First off, thank you very much for providing such a detailed answer!
  1. Does it only work on terms like parts and fields?  What about content?  What are these terms called?  Do they always go at the beginning?
  2. Awesome, thanks!
  3. I'm trying to figure out if there is a specific order that all these different possible terms go in.  In the table, the display type always shows up at the end of the template name but in the middle of the shape name.  They also provide rules for converting periods, backslashes, and hyphens to underscores, but they don't explain when you should use periods, backslashes, and hyphens??
  4. Okay, I'll just have to experiment I guess.
  5. I'll definitely take a look at the source code!

Thanks again for your help!  

Developer
Aug 9, 2012 at 7:00 PM

Alternates don't work for parts nor fields; they only work for shapes.

As for the order, I think that the last added alternate will be the more specific one. The first template that matches the alternate will be used to render.

As for the rules, I admit that I am confused by that table of conventions. It looks like it all depends on how you start the name of your shape. It's something I'll investigate when there's time.