How to create a new Control

Suppose you need to implement the following user story:

As a user, I want to create a CustomLabel that not only has a property Text of the Label but also a AnotherText property that stores another text. When someone modifies the value of AnotherText, it should trigger an event indicating that this property has been changed.

In order to implement this user story, you will have to do the following things:

1. An Observable Class

2. A Data Transfer Object

3. A Mapper

4. Register the mapper in the RegistrationClass

1. Creating CustomLabel Observable Class

Please follow the following steps:

1. Create the class

2. Add ObservableAttribute

3. Add the required properties and add InterceptedAttribute to the properties that you want them to be persisted throughout the WebMAP's life cycle.

   [Observable]
   public class CustomLabel : Label
   {
    [Intercepted]
    public string AnotherTextInternal { get; set;}
   
    public string AnotherText
    {
        get
        {
            return this.AnotherTextInternal;
        }
        set
        {
            this.AnotherTextInternal = value;           
            this.AnotherTextChanged(EventArgs.Empty);  
        }
    }
   
    [Intercepted]
    public EventHandler AnotherTextChanged { get; set; }
   
    protected virtual void OnAnotherTextChanged(EventArgs e)
    {
        this.AnotherTextChanged?.Invoke(this,EventArgs.Empty);
    }
   }

Observations when adding ObservableAttribute

When you add this attribute, it means the the class will be an observable class. So please take into account the following observations:

• An observable class can have private, internal or public modifier.

• An observable class can be sealed.

• An observable class can be abstract.

• When you add Observable attribute to a class. All classes that inherits from that class will be observables. Even if attribute is not present in one of those classes.

Observations when adding InterceptedAttribute

When you add this attribute, it means the the property will be intercepted, this means that this property will live under the WebMAP's life cycle, its value will be persisted throughout the requests. So please take into account the following observations:

• Properties can be virtual or non virtual.

• Properties cannot be abstract.

• Properties can be public, private, internal or protected.

• Properties must be auto implemented

• Property type can be any value type or string, or any type marked as an observable.

• Properties can be static

2. Creating CustomLabel Data Transfer Object

Please follow the following steps:

1. Create a Data Transfer Object class

2. Add DataTransferAttribute to the class

3. Add the properties that you want to synchronize between frontend and backend

[DataTransfer("cstmlbl")] 
public class CustomLabel
{ 
    public string Text { get; set; }
    public string AnotherText { get; set; } 
}

Observations

• Classes should not inherit from any other classes

• Use nullable types for value types. For example int? instead of int

• The name used on the DataTransfer attribute should be

  • unique

  • as short as possible

  • it should start with a lowercase consonant

  • it should not use vowels

  • if it is made up of several words the next word should have just its first letter in uppercase

3. Creating CustomLabel Mapper

Please follow the following steps:

1. Create the mapper class

2. Implement IMapper interface, in which the first type parameter of this generic interface should be the model. The second parameter of generic interface is the DTO class.

3. Implement the methods of IMapper

   public class CustomLabelMapper : IMapper
   {
    public void Configure(MapperInformation config)
    {
        // There are not References to report
    }
   
    public object Map(IObservable observable)
    {
        var source = observable as CustomLabel;
   
        var result = new DTO.CustomLabel()
        {
            Text = source.GetChange( x=> x.TextInternal),
            AnotherText = source.GetChange( x=> x.AnotherTextInternal)
        };
        return result;
    }
   
    public void ApplyChanges(IObservable observable IDataTransfer dto)
    {
        var target = observable as CustomLabel;
        var source = dto as DTO.Label;
        if (source.Text != null && source.Text !=target.Text)
        {
            target.Text = source.Text;
        }
        if (source.AnotherText != null &&source.AnotherText != target.AnotherText)
        {
            target.AnotherText = source.AnotherText;
        }
    }

   Observations

4. Map: this method is called to create a DTO instance and populate from the model. If you do not want to send anything to the client you can return null

5. ApplyChanges: this method is called to sync back data from the client. In this method you can take data sent from the client and apply those changes to the model on the backend. E.g. If there were a change of AnotherText from client side, it will update the value and trigger the AnotherTextChanged event.

6. Configure: this method is called to setup which data elements from the model must be considered as references.

7. The extension method GetChange must be used. This returns null when the property doesn't been modified during the request, otherwise, it returns the value of the modified property.

4. Register the mapper

This final step is simply going to the Registration class (situated under DTO project) and add the following line to the RegisterMapper method:

public class Registrations : IRegistration
{  
    public void RegisterMappers(IMapperCatalog catalog, ILogger logger)
    {
        ...
        ...
        catalog.AddMapper(new CustomLabelMapper());
    }
}