What is the groupId parameter in the IContentManager.BuildDisplay method of Orchard for?

Question

The method IContentManager.BuildDisplay used to call to the drivers of a ContentItem has an optional groupId argument. I have navigated through the source code but I did not understand exactly what is its use case. It seems to be able to filter shapes, but I'm not sure I understand how.

Could you clarify this for me? Thanks in advance.

Fosterling

Answer 1

Yes, this parameter is used for filtering shapes. You can provide an optional parameter via .OnGroup() method of ContentShape object returned from Display/Editor method of a driver.

By default it's an empty string. If you provide a groupId parameter in BuildDisplay - only the shapes with that group id specified would be taken into account when building the final output.

I found it particularly useful when needed to render the same part differently in different scenarios - returning a Combined result with ContentShape objects (each with different group specified) in it from the driver's Display method.

Remember that if you explicitly specify a group in BuildDisplay method - only the shapes with that group set will be used.

Chuppah

True. This group is currently used to handle the tabs in admin pages if I'm not mistaken. – Giorgi

Thanks a lot. This will prove pretty useful. – Fosterling

@Bertrand: Your're right - it's currently used to handle site settings menu sub-items in Dashboard. – Chuppah

Is it possible to apply this grouping to Fields? I tried using OnGroup on the Part which contains the Fields, but only the Part editor displayed, not the Fields (which makes sense as they use different Drivers). – Touter

Is calling .OnGroup(x) the same as specifying @MyGroup in Placement.info? – Ailis