whats the point of "display type"?

Topics: General, Writing modules
Jun 24 at 3:22 PM
Edited Jun 26 at 3:58 AM
the documentation implies that "content + displaytype" makes the shapename...
however I'm not seeing this in my stuff, or in a lot of the code, HOWEVER, I am still trying to come to grips with "content vs part" subtlties...

var shop = _Osvc.ContentManger.BuildDisplay(thing, displaytype);

Where thing is a IContent with a ContentItem with a ThingPart, CommonPart, TitlePart etc...
(eg: => ContentManager.New<ContentItem>("Thing"); )

this returns a shape, however I'm seeing this shape comeback

rather than what I would have assumed (based on the description in the documentation)

I notice a lot of other modules use display type in many and varied ways...
most just using "shapeHelper.Parts_Thing_Summary(Stuff: goeshere)" to dictate the shapename...
what is the actual purpose/goal of this property and its use?

Alternates (right name?) work for SUB objects defined in the placement.info file... so perhaps my expectation of the BuildDisplay() operation is incorrect...

I guess my question is really why (if its not just for convenience) would you choose a particular option over another...
explicit shape creation vs displaytype... is there a preference for any reason?... Is one or the other falling out of favour... etc...
Jun 26 at 9:19 AM
Edited Jun 26 at 9:21 AM
The point of "display type" is to provide an additional piece of metadata to whomever it concerns. Off the top of my head there are two primary systems that leverage this information:
  1. Content shapes
  2. Placement.info
Content shapes
Whenever ContentManager.BuildDisplay is called, it creates a shape called Content and sets its DisplayType property to the value that was passed to the call to BuildDisplay. When this shape is rendered, a shape table provider kicks in for this shape that adds alternates to the Content shape based on this display type. So no actual shape based on the display type is created, but instead a bunch of shape alternates are created. The reason you see things like "Parts_Thing_Summary" is because certain drivers just happen to return those shapes. And for good reason:

Placement.info files are used by the ContentManager when creating Content shapes based on content items. Placement.info is an XML file that contains configuration about what shapes to display when. One such condition is the DisplayType condition. This allows content part drivers to yield multiple shapes (one for the Detail and one for Summary display type for example), but only the shapes that match certain conditions are actually rendered. Take for example the TitlePart's driver and placement.info file:

protected override DriverResult Display(TitlePart part, string displayType, dynamic shapeHelper) {
            return Combined(
                    () => shapeHelper.Parts_Title(Title: part.Title)),
                    () => shapeHelper.Parts_Title_Summary(Title: part.Title)),
                    () => shapeHelper.Parts_Title_SummaryAdmin(Title: part.Title))
As you can see, it returns multiple shapes. But look at its Placement.info file:
    <!-- available display shapes -->
    <Place Parts_Title_Edit="Content:before.5"/>
    <Match DisplayType="Detail">
        <Place Parts_Title="Header:5"/>
    <Match DisplayType="Summary">
        <Place Parts_Title_Summary="Header:5"/>
With that file in place, only one shape will ever be rendered, depending on what display type was specified to the content manager.
Note that although the Parts_Title_Summary shape uses the same name as the display type "Summary", this is not required at all; any other shape name could have been used, like Parts_Title_BriefVersion. It's the <Match DisplayType="..."> condition that determines what shape provided by the driver actually gets rendered.

I wrote an article that delves deeper into content parts, drivers, shapes and placement here: http://www.ideliverable.com/blog/a-closer-look-at-content-types-drivers-shapes-and-placement
Marked as answer by smerlon on 7/8/2016 at 6:39 PM
Jul 9 at 12:52 AM
Edited Jul 9 at 12:54 AM
good answer and great link too...
I guess I was confused/off-side from my impression that (as in your examples) it looks like its doing things twice, once in the driver and again in the placement.info... so why not (in driver) just build one shape, since its going to get the "display type" anyway to allow placement.info, to do its thing and each of the shapes has the same data... seems wasteful... however (I'm guessing) this is SOC and better for flexibility and customisation...
From reading into your link and examples it seems that (amongst other thigns) this allows for "defaults" from the display driver and then overrides and and "non-code" tweaking of alternates and ordering...
Thanks for all this.