I still don't understand shape

[dodyg]

I've implemented and deployed several websites using OrchardCore. I've written a lot of templates, a couple of custom modules and interacted with shapes in many places but I fundamentally don't understand what it is.

I've read this but most of the details really just fly over my head.

[ns8482e]

Shape is a building block for Orchard Core display management. A shape can be composed of many other shapes. To keep it simple analogous to MVC or MVVM pattern - you can call it either data model or view model for your views.

Here's my basic understanding - I hope that would help you understand better.

Shape

• It's dynamic data model for shape templates.
• It's defined using Type.
• It can also have a name. Shape with name called Named shape.
• Shape can have other child shapes that can be added using Add method.
• Child Named shape can also be accessed from parent as property accessor using name
• In most cases Model is shape in cshtml in orchard core.

ShapeMetadata

• It holds metadata of Shape e.g. Type, Name, Alternates, Wrappers

Shape Template or Views

• cshtml/liquid markup for the Shape.
• The default Template is named after shape type. i.e. Content shape has default template Content.cshtml
• It's confusing but sometime it's also referred as Shape. ( e.g. Content__Page is actually alternate shape template for Shape type Content . )

[Shape] attribute

• Shape template implemented in C# method. C# Method name is same as Shape type. e.g. Message is core shape implemented as C# method.

// Basic example of Shape

var parentShape= new Shape(); // Just for illustration, Use ShapeFactory to create shape
parentShape.Metadata.Type = "TypeA"; // Rendered using TypeA.cshtml
parentShape.PropertyA = "Parent"; // Accessed as Model.PropertyA inside TypeA.cshtml shape template

var anotherShape= new Shape();
anotherShape.Metadata.Type = "TypeB"; // Rendered using TypeB.cshtml
//Named shape
anotherShape.Metadata.Name = "childShape";
anotherShape.PropertyB = "Child"; // Accessed as Model.PropertyB inside TypeB.cshtml shape template

parentShape.Add(anotherShape);

dynamic a = parentShape.PropertyA;

// Get Named shape as dynamic property
dynamic b = parentShape.childShape.PropertyB;

// Or with Named function
parentShape.Named("childShape").PropertyB;

// Following code will render TypeA.cshtml or TypeA.liquid or call C# method TypeA having [shape] attribute.
@await DisplayAsync(parentShape)

ShapeResult

It is a shape builder factory returned by a DisplayDriver that defines the shape - with type, model and placement location.

DisplayDriver

Called by DisplayManager - It returns ShapeResult that is used by DisplayManager to construct a shape instance.

Alternate

Alternate is a Shape Templates (Views) for the Shape. shape.Metadata.Alternates is collection of alternates - last one in the collection is used to render the view.

Wrapper

Wrapper is a shape template(Views) for the Shape - wraps extra html around original shape . shape.Metadata.Wrappers is collection of wrappers - all wrappers rendered when shape is rendered.

Shape Morphing

It's technique to target different shape template for given shape by changing it's Type.

var shape= new Shape(); // Just for illustration, Use ShapeFactory to create shape
shape.Metadata.Type = "TypeA";
shape.PropertyA = "A";

// Render Shape Template TypeA.cshtml
@await DisplayAsync(shape)


shape.Metadata.Alternates.Clear();
shape.Metadata.Wrappers.Clear();
shape.Metadata.Type = "TypeB";

// Render Shape Template TypeB.cshtml
@await DisplayAsync(shape);

[dodyg]

Thank you.

Is the ShapeMetaData a dynamic object as well? Are Type, Name, Alternates, Wrappers more of a convention or are they fixed properties?

I think one of the disconnect I have is understanding how the shapes are being used by various facilities in OrchardCore. For example, what part of the shape that a DisplayDriver use? Are these fixed properties or more like a key in a dictionary?

[ns8482e]

Fixed properties coming from IShape. Shape is default the implementation of IShape. However you are not restricted to use just Shape class for your Shape Model - You can create your own if you need. ShapeViewModel is another implementation provided in OC.

In my example above - for simplicity, I used new Shape() - You do not instantiate shape like that in OC. Instead you use <shape type="MyShape"> tag helper or New.MyShape() shape factory to create shapes or provideInitialize / Dynamic / View methods in DisplayDriver.

ShapeResult is not a Shape and as I said above DisplayDriver returns ShapeResult not a Shape

Let's put it this way, If Shape object having other child shapes - as Metaphor if it's your favorite food item that you want to cook, then

• DisplayManager creates your favorite food item.
• But DisplayManager needs recipe for each ingredient.
• DisplayDriver is registered recipe book that provides recipes requested - It may return one ore more ingredient recipes.
• ShapeResult is the recipe for the ingredient. It provides instruction on how to create the ingredient and use them.
• Finally DisplayManager uses recipes to create each ingredient (child Shapes) and final food item (final Shape)

Tip: context.Shape in DisplayDriver represents the instance of final shape being built.

[giannik]

this should go in the docs.

[hishamco]

@ns8482e thanks for informative explanation, I think we should add them to docs if we miss some or write a blog post that we can refer too

Thanks so much Niraj

[hung-doan]

@ns8482e does the shape work with the Admin UI ?, or It only works with the Site UI only ?.
Btw, is there any way to list all support shapes in the system. If there is any module like that, It would be a great help for the learning as well as the implementation.

[ns8482e]

@hung-doan You can override Admin UI, Shape templates using Admin Template feature

[hungdoan-groove]

@ns8482e Can you give me an example of Admin Template?, It confuses me as there are two types of template:

• Admin Template
• Template

How should I know which template should I use ?.
For example, I tried to change the Email template. I use "TemplateUserConfirmEmail" template, It worked with Template, but "Admin Template".

What is the rule do indicate when should I go with the "Admin Template" or when should I go with the "Template"?.

[ns8482e]

Templates is for front-end UI and AdminTemplates targets Admin UI. These shape templates takes precedence over front-end UI Theme and Admin Theme respectively. Use these features when you would like to define your shapes at runtime. It supports only liquid syntax.

in other words,

It allows you to customize existing themes at runtime, To customize front-end UI, define your shape in Templates. If you want to customize admin experience then define your shape in AdminTemplates

[Skrypt]

It is as simple as saying that since Orchard Core uses a composition design pattern with it's Content Types. Content Types needed to use Dynamic typing. So, it's ViewModels needed to also be Dynamic (see what inherits ShapeViewModel). Shape can be used in a lot of different places where Dynamic objects are used to build up the UI with the DisplayManager which defines things like Drivers (DisplayDrivers, BuildEditorDrivers) which has been implemented to allow to dynamically bind dynamic ViewModels to a controller action.

Simple explanation is that a common ViewModel will generally be strongly typed and pass only one Content Type (for example) but @sebastienros needed to make this smarter to not need to create a different Editor / Display for each of these dynamic ViewModels. Also, it would have not made any sense to use a strongly typed ViewModel for these since a Content Type definition is dynamic and can be changed on runtime.

So from there started having the need of a Shape which is a dynamic UI part that can be containing a Content Part, Content Field ... ... which can be morphed when you want to see it in it's details, summary view

[dodyg]

This is a new video about Shape https://www.youtube.com/watch?v=adJ9n9y_6P0

[MarGraz]

Hi Everyone,

as Orchard Core newbie I can completely understand @dodyg 😊

Has the explanation made by @ns8482e here, and @Skrypt here been added to the official documentation?

I'm looking at the reference guide and I can't find it.
Can I submit a pull request to add it? If yes, in which section should I add this info about Shapes?

Thank you

[MarGraz]

Could be nice also to add this in a page dedicated to the Shape, and have a table that lists all the available shapes, like this one.