Using Composite Controls for the implementation of Bootstrap 5 components

You may already be aware that DotVVM 4.0 has introduced a new feature called Composite Controls, which provides a new way to write controls in DotVVM. This approach eliminates the need to declare DotVVM properties in code-only controls, for which you had to use the dotprop code snippet and work with long property declaration blocks. Instead, it only requires declaring a `GetContents` method and placing individual control properties as arguments of the method. By using this approach, the control code appears much more attractive and readable.

For instance, consider the following example of a Bootstrap Badge control:

public class Badge : BootstrapCompositeControl
{
     public static DotvvmControl GetContents(
         HtmlCapability htmlCapability,
         TextOrContentCapability textOrContentCapability,
         [DefaultValue(BadgeColor.Primary)] ValueOrBinding<BadgeColor> type,
         BadgeVisualStyle visualStyle = BadgeVisualStyle.Default,
         ICommandBinding? click = null
     )
     {
         return new HtmlGenericControl("span", textOrContentCapability, htmlCapability)
             .AddCssClass($"badge {visualStyle.ToEnumString()}")
             .AddCssClass(type.Select(t => t.ToEnumString()))
             .SetProperty(Events.ClickProperty, click);
     }
}

Right away, we can observe a few new types introduced by the composite control approach. The first argument type is HtmlCapability, which is a collection of properties utilized across multiple controls. DotVVM provide some composite control capabilities out of the box, such as HtmlCapability (containing common properties such as ID, Class-*, Style-*, or Visible) and TextOrContentCapability (which renders either Text (string-only value or binding) or Content properties (any hierarchy of HTML and other controls specified as inner elements). It also throws the DotvvmControlException when both of these properties are set – this helps to ensure that the syntax is clear and consistent.

The greatest benefit we learned is possible to do with your own capabilities to share logic between multiple controls. To achieve this, such capability classes must be marked with the DotvvmControlCapability attribute and be sealed. Since the classes are sealed, you cannot use inheritance, but you can easily include the child capability as one of the properties.

To illustrate, consider this example of CheckBoxCapability and the inner CheckBoxCoreCapability:

[DotvvmControlCapability()]
public sealed record CheckBoxCapability
{
    public CheckBoxCoreCapability CoreCapability { get; init; } = null!;

    [DefaultValue(null)]
    public IValueBinding<IEnumerable>? CheckedItems { get; init; }

    public CheckBox ToControls()
    {
        return CoreCapability.ToControls()
            .SetProperty(a => a.CheckedItems, CheckedItems);
    }
}

As you can see, the child capability is reused in the ToControl method. In many capabilities, we’ve created a convention of declaring a ToControl/ToControls method which builds the corresponding UI from the capability properties, which helps to encapsulate various pieces of the presentation logic.

The inner CheckBoxCoreCapability can be reused in multiple components – for example ButtonGroupCheckBox, FormControlCheckBox, and others. The CheckBoxCapability is used only in the CheckBox control as it adds several things which are relevant to the CheckBox control only.

Dealing with enums

Let's revisit the sample Badge control. Its next property is a new generic type called ValueOrBinding<T>. When the control is used in DotHTML files, the Type property can allow either a hard-coded value of the BadgeColor type (<bs:Badge Type={value: BadgeColor.Blue} />), or a data-binding from a view model (<bs:Badge Type={value: _root.MyBadgeColorProperty} />).

It’s also possible to allow only either hardcoded values (with composite control property of type BadgeColor) or binding only (with composite control property of type IValueBinding<BadgeColor>).

public enum BadgeColor
{
    [EnumMember(Value = "bg-primary")]
    Primary,
    [EnumMember(Value = "bg-secondary")]
    Secondary
}

public class CardImage : BootstrapCompositeControl, ICardItem
{
     [MarkupOptions(MappingMode = MappingMode.Exclude)]
     public CardImageStyle Style
     {
         get { return (CardImageStyle)GetValue(StyleProperty)!; }
         set { SetValue(StyleProperty, value); }
     }     public static readonly DotvvmProperty StyleProperty
         = DotvvmProperty.Register<CardImageStyle, CardImage>(c => c.Style, CardImageStyle.Default);     public IEnumerable<DotvvmControl> GetContents(
         HtmlCapability htmlCapability,
         ValueOrBinding<string>? alternateText,
         ValueOrBinding<string> imageUrl,
         ValueOrBinding<string>? toolTip,
         [MarkupOptions(AllowBinding = false, MappingMode = MappingMode.InnerElement)]
         CardBody? overlay = null
     )
     {
         yield return new HtmlGenericControl("img", htmlCapability)
             .SetAttribute("src", imageUrl)
             .SetAttribute("alt", alternateText)
             .SetAttribute("title", toolTip);         if (overlay is not null)
         {
             yield return overlay;
         }
     }
}

public DotvvmControl GetContents(HtmlCapability htmlCapability, DropDownCapability capability)
{        
    if (!capability.IsSplitButton)
    {
        throw new DotvvmControlException(this, "Cannot set parent reference.");
    }
}